Table of Contents
- The Challenge
- Architecture & Solution
- Tech Stack
- Key Engineering Decisions
- Frontend Deep-Dive
- Backend API
- Admin Dashboard
- Performance Optimization
- Deployment
- Roadmap
The Challenge
MOSONiE — Socio-Economic Foundation is a registered non-profit organization dedicated to community upliftment through health, livelihood, and education programs across North-East India. The organization needed a modern, high-performance web platform that could effectively communicate their mission while enabling online donations and managing content through a comprehensive admin interface.
The previous implementation was a traditional SPA (Single Page Application) without server-side rendering, resulting in poor SEO performance and slow initial load times. The organization required perfect Lighthouse scores across all metrics (Performance, Accessibility, Best Practices, SEO) to establish credibility with potential donors and partners. Additionally, the admin dashboard needed to support content management for programs, events, blog posts, galleries, team members, and donations without requiring technical expertise.
The requirement: Build a production-grade platform achieving 100/100 Lighthouse scores with full SSR for SEO, integrated Razorpay donation system, comprehensive admin dashboard (Control Matrix interface), and production-ready Docker deployment with Traefik reverse proxy.
Architecture & Solution
The platform follows a modern SSR architecture combining Vite for bundling, Vike for server-side rendering, and Hono as the backend API framework, all running on Bun runtime:
Three-Tier Architecture
| Layer | Components | Purpose |
|---|---|---|
| Presentation | React 19 + Tailwind + Motion | User-facing public pages and admin dashboard |
| Application | Vike SSR + Hono API | Server-side rendering, routing, API endpoints |
| Data | PostgreSQL + Prisma + Redis | Persistent storage, ORM, caching layer |
Tech Stack
| Layer | Technology | Version |
|---|---|---|
| Runtime | Bun | 1.x |
| Frontend Framework | React | 19.x |
| Bundler | Vite | 8.x |
| SSR Framework | Vike | latest |
| Backend API | Hono | latest |
| Styling | Tailwind CSS | 4.x |
| Animation | Motion (Framer) | 12.x |
| Database | PostgreSQL | 16-alpine |
| ORM | Prisma | 5.x |
| Caching | Redis | 7-alpine |
| Object Storage | Minio | latest |
| Payment Gateway | Razorpay | 2.x |
| Resend | 6.x | |
| Process Manager | PM2 | latest |
| Reverse Proxy | Traefik | latest |
| Validation | Zod | 3.x |
| Security | Helmet | 8.x |
Key Engineering Decisions
1. Vike SSR for Perfect SEO
The platform uses Vike (vite-plugin-ssr) to enable server-side rendering for all public pages, ensuring search engines can crawl content effectively while providing fast initial page loads:
// src/pages/+config.ts
export default {
// Enable SSR for all pages
ssr: true,
// Use React as the renderer
clientRouting: true,
// Prefetch on hover for fast navigation
prefetchLinks: true,
} satisfies Config;The SEOHead component provides per-page meta tags and Open Graph data:
// src/components/common/SEOHead.tsx
export function SEOHead({
title,
description,
image,
type = 'website',
schema
}: SEOProps) {
return (
<>
<title>{title}</title>
<meta name="description" content={description} />
<meta property="og:title" content={title} />
<meta property="og:description" content={description} />
<meta property="og:image" content={image} />
<meta property="og:type" content={type} />
{schema && (
<script type="application/ld+json">
{JSON.stringify(schema)}
</script>
)}
</>
);
}2. Redis Tiered Caching Strategy
The API implements a tiered caching strategy with Redis for immutable data and graceful degradation:
// server/middleware/cache.middleware.ts
const cacheMiddleware = async (c: Context, next: Next) => {
const cacheKey = `api:${c.req.path}:${JSON.stringify(c.req.query())}`;
// Check Redis cache
const cached = await redis.get(cacheKey);
if (cached) {
return c.json(JSON.parse(cached));
}
await next();
// Cache successful responses for 5 minutes
if (c.res.status === 200) {
await redis.setex(cacheKey, 300, JSON.stringify(response));
}
};3. Minio S3 Integration for Media Storage
All media assets are stored in Minio (S3-compatible) with presigned URLs for secure access:
// server/services/storage.service.ts
class StorageService {
private client: S3Client;
private bucket = 'mosonie-media';
async uploadFile(buffer: Buffer, filename: string, contentType: string) {
const key = `uploads/${Date.now()}-${filename}`;
await this.client.send(new PutObjectCommand({
Bucket: this.bucket,
Key: key,
Body: buffer,
ContentType: contentType,
}));
return this.getPresignedUrl(key);
}
async getPresignedUrl(key: string, expires = 3600) {
const command = new GetObjectCommand({
Bucket: this.bucket,
Key: key,
});
return getSignedUrl(this.client, command, { expiresIn: expires });
}
}4. Razorpay Donation Integration
The donation system supports one-time and recurring payments with 80G tax benefit notification:
// server/services/payment.service.ts
async function createDonationOrder(amount: number, email: string, name: string) {
const razorpay = new Razorpay({
key_id: process.env.RAZORPAY_KEY_ID,
key_secret: process.env.RAZORPAY_KEY_SECRET,
});
const order = await razorpay.orders.create({
amount: amount * 100, // Convert to paise
currency: 'INR',
receipt: `DON-${Date.now()}`,
notes: {
email,
name,
type: 'donation',
},
});
return order;
}
async function verifyWebhookSignature(payload: string, signature: string) {
const expected = crypto
.createHmac('sha256', process.env.RAZORPAY_WEBHOOK_SECRET)
.update(payload)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expected)
);
}5. Security Middleware Stack
The platform implements comprehensive security through layered middleware:
// server/index.ts
const app = new Hono();
// Security headers via Helmet
app.use('*', helmet({
contentSecurityPolicy: {
directives: {
defaultSrc: ["'self'"],
imgSrc: ["'self'", "data:", "https://storage.mosonie.org"],
scriptSrc: ["'self'", "'unsafe-inline'"],
styleSrc: ["'self'", "'unsafe-inline'"],
},
},
hsts: process.env.DISABLE_HSTS !== 'true' ? { maxAge: 31536000 } : false,
}));
// Rate limiting
app.use('*', rateLimit({
limit: 100,
window: 60, // 100 requests per minute
}));
// CORS
app.use('*', cors({
origin: ['https://mosonie.org', 'https://admin.mosonie.org'],
credentials: true,
}));
// Audit logging
app.use('*', auditLogMiddleware);
// JWT authentication for admin routes
app.use('/api/v1/admin/*', authMiddleware);Frontend Deep-Dive
Public Pages (13 SSR Pages)
| Page | Route | Features |
|---|---|---|
| Home | / | Hero, Impact stats, Programs teaser, Testimonials, Partners, CTA |
| About | /about | Mission, Vision, Values, History, Team preview |
| Programs | /programs | Category filter, program cards, image gallery |
| Team | /team | Founders, Board, Staff, Volunteers with profiles |
| Testimonials | /testimonials | Category filter, quote cards with photos |
| Events | /events | Upcoming + past events, calendar view |
| Reports | /reports | Category filter, search, PDF download |
| Blog | /blog | Article listing, category filter, search |
| Gallery | /gallery | Masonry grid, lightbox, albums |
| FAQ | /faq | Accordion with FAQPage JSON-LD schema |
| Donate | /donate | Tiers, one-time/recurring, Razorpay, 80G notice |
| Contact | /contact | Form, map, contact details |
| Partners | /partners | Associate & funding partners grid |
Design System: Control Matrix / Mosonie Modern
The UI follows a premium design system with strict 8px semantic grid:
/* src/index.css - Tailwind v4 tokens */
@theme {
--font-sans: 'Inter', system-ui, sans-serif;
--spacing-xs: 8px;
--spacing-sm: 16px;
--spacing-md: 24px;
--spacing-lg: 32px;
--spacing-xl: 48px;
--shadow-premium: 0 4px 6px -1px rgb(0 0 0 / 0.1),
0 2px 4px -2px rgb(0 0 0 / 0.1),
0 0 0 1px rgb(0 0 0 / 0.05);
--ease-premium: cubic-bezier(0.22, 1, 0.36, 1);
}
@layer utilities {
.animate-premium {
animation-duration: 300-500ms;
animation-timing-function: var(--ease-premium);
}
}Partytown for Analytics Offloading
Third-party analytics scripts are offloaded to a web worker to prevent blocking LCP:
// vite.config.ts
export default {
plugins: [
partytown({
dest: join(__dirname, 'dist', 'public', '~partytown'),
forward: ['dataLayer.push'],
}),
],
};Backend API
API Structure
The Hono API follows RESTful conventions with versioning:
/api/v1/
├── /auth # Authentication (login, logout, session)
├── /programs # Program CRUD
├── /team # Team member management
├── /events # Event management
├── /blog # Blog posts
├── /gallery # Media galleries
├── /partners # Partner management
├── /donations # Donation tracking
├── /reports # Report downloads
├── /faqs # FAQ management
├── /inquiries # Contact form submissions
├── /newsletters # Subscriber management
├── /storage # Minio file operations
└── /health # Health check endpointsAuthentication Flow
JWT-based authentication with httpOnly cookies:
// server/api/v1/auth.routes.ts
const authRouter = new Hono();
authRouter.post('/login', async (c) => {
const { email, password } = await c.req.json();
const user = await prisma.user.findUnique({ where: { email } });
if (!user) {
throw new HTTPException(401, { message: 'Invalid credentials' });
}
const valid = await argon2.verify(user.password, password);
if (!valid) {
throw new HTTPException(401, { message: 'Invalid credentials' });
}
const token = await sign({ userId: user.id, role: user.role }, JWT_SECRET, {
expiresIn: '7d',
});
c.header('Set-Cookie', `token=${token}; HttpOnly; Path=/; Max-Age=604800; SameSite=Strict`);
return c.json({ success: true, user: { id: user.id, email: user.email, role: user.role } });
});Admin Dashboard
The Control Matrix admin interface provides comprehensive content management across 15 modules:
| Module | Route | Capabilities |
|---|---|---|
| Dashboard | /admin | Real-time telemetry, platform stats, live audit logs |
| Programs | /admin/programs | CRUD for foundation initiatives with dynamic status |
| Team Members | /admin/team | Modern grid for board, staff, contributors |
| Impact Scorecard | /admin/impact | Social performance metric calibration |
| Events | /admin/events | Lifecycle management with gallery support |
| Blog | /admin/blog | Markdown content with category filtering |
| Gallery | /admin/gallery | Album management and media organization |
| Partners | /admin/partners | Funding and associate partner management |
| Donations | /admin/donations | Real-time contribution tracking |
| Newsletter | /admin/newsletter | Subscriber management and sync |
| System Logs | /admin/system-logs | Immutable audit trails |
| Settings | /admin/settings | Global metadata, SEO, contact parameters |
| Inquiries | /admin/inquiries | Contact form triage |
| Storage Browser | /admin/storage | S3-integrated asset manager |
| Auth & Security | /admin/login | JWT session control and RBAC |
The admin dashboard uses Client-Side Rendering (SSR disabled) for optimal editing experience:
// src/pages/admin/+config.ts
export default {
// Disable SSR for admin - better for interactive editing
ssr: false,
// Enable client-side navigation
clientRouting: true,
} satisfies Config;Performance Optimization
Lighthouse Targets
| Metric | Target | Strategy |
|---|---|---|
| Performance | 95+ | SSR HTML, Redis cache, presigned URLs, code splitting |
| Accessibility | 100 | Semantic HTML, ARIA labels, focus rings, WCAG AA |
| Best Practices | 100 | HTTPS, security headers, no deprecated APIs |
| SEO | 100 | Unique meta/OG per page, JSON-LD, sitemap |
Optimization Techniques
- Asset Migration: 100% WebP/AVIF with responsive sizing via OptimizedImage component
- Resource Preloading: Critical fonts and third-party domains preconnected
- LiteYouTube Facade: Video embeds deferred via lightweight facade
- Partytown: Analytics offloaded to web worker
- Aggressive Caching: Tiered Redis for API, immutable for assets
- HSTS Bypass: Configurable for local Lighthouse audits
Lighthouse CI Integration
Automated performance auditing via LHCI:
# lighthouserc.json
{
"ci": {
"collect": {
"numberOfRuns": 3,
"url": ["http://localhost:3000/"],
"staticDistDir": "./dist/public"
},
"assert": {
"assertions": {
"categories:performance": ["error", { "minScore": 0.95 }],
"categories:accessibility": ["error", { "minScore": 1 }],
"categories:best-practices": ["error", { "minScore": 1 }],
"categories:seo": ["error", { "minScore": 1 }]
}
}
}
}Deployment
Production Subdomains
| Subdomain | Service | Access |
|---|---|---|
| mosonie.org | Web + API | Public |
| storage.mosonie.org | Minio S3 | Public |
| console.mosonie.org | Minio Console | Admin only |
| db.mosonie.org | Adminer | Admin only |
Docker Production Stack
# Full automated deployment
./deploy.sh "commit message"
# Options
./deploy.sh --auto # Non-interactive
./deploy.sh --skip-build # Restart only
./deploy.sh --skip-test # Skip API verification
./deploy.sh --dry-run # PreviewDeployment Pipeline
- Pre-flight checks (SSH, Git)
- Local API verification tests
- Git commit & push
- Rsync code to VPS
- Docker build & restart
- Prisma schema migration
- Health check (Web + API)
- Production module audit
- Summary report
Service URLs (Production)
| Service | URL |
|---|---|
| Website | https://mosonie.org |
| API | https://mosonie.org/api/v1 |
| Admin | https://mosonie.org/admin |
| Minio Console | https://console.mosonie.org |
Roadmap
- Phase 1 — Core Infrastructure (Complete) - Vike SSR, Hono API, Prisma, PostgreSQL
- Phase 2 — Public Pages (Complete) - 13 SSR pages with full SEO
- Phase 3 — Admin Dashboard (Complete) - 15 modules with Control Matrix UI
- Phase 4 — Payment Integration (Complete) - Razorpay for donations
- Phase 5 — Media Storage (Complete) - Minio S3 integration
- Phase 6 — Performance Optimization (Complete) - 100/100 Lighthouse
- Phase 7 — Security Hardening (Complete) - Helmet, rate limiting, audit logs
- Phase 8 — Email Automation (In Progress) - Resend integration for newsletters
- Phase 9 — Multi-language Support (Planned) - i18n for regional languages
- Phase 10 — Volunteer Portal (Planned) - Public volunteer registration and tracking
Conclusion
The MOSONiE platform achieves its goal of a 100/100 Lighthouse score through careful architectural decisions around SSR, caching, and asset optimization. The Vike + Hono combination provides excellent developer experience while delivering the SEO performance required for a non-profit organization dependent on search visibility.
The Control Matrix admin dashboard enables non-technical staff to manage all content types without external assistance, from program updates to donation tracking. The integration with Razorpay facilitates online donations essential for the organization's fundraising efforts, while Minio provides scalable media storage without relying on expensive third-party services.
The production deployment via Docker with Traefik ensures secure, reliable access with automatic SSL provisioning, and the comprehensive documentation and agent rules enable maintainability as the project grows.
Architecture Feedback
Spotted a potential optimization or antipattern? Let me know.