Initializing
Back to Projects
Year2026
DomainFullstack
AccessOpen Source
Complexity9.2 / 10
Live Link
ReactViteVikeHonoPostgreSQLPrismaTypeScriptTailwind CSSMotionRedisMinioDockerRazorpayPM2Traefik
FullstackProduction

MOSONiE — Socio-Economic Foundation Platform

Production-grade NGO website with 100/100 Lighthouse scores, SSR via Vike+Hono, Razorpay donations, Minio storage, and a premium Control Matrix admin dashboard.

Lighthouse Score100/100
Public Pages (SSR)0
Admin Modules0
API Endpoints0+
Subdomains0

Table of Contents


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:

Parsing system architecture diagram...

Three-Tier Architecture

LayerComponentsPurpose
PresentationReact 19 + Tailwind + MotionUser-facing public pages and admin dashboard
ApplicationVike SSR + Hono APIServer-side rendering, routing, API endpoints
DataPostgreSQL + Prisma + RedisPersistent storage, ORM, caching layer

Tech Stack

LayerTechnologyVersion
RuntimeBun1.x
Frontend FrameworkReact19.x
BundlerVite8.x
SSR FrameworkVikelatest
Backend APIHonolatest
StylingTailwind CSS4.x
AnimationMotion (Framer)12.x
DatabasePostgreSQL16-alpine
ORMPrisma5.x
CachingRedis7-alpine
Object StorageMiniolatest
Payment GatewayRazorpay2.x
EmailResend6.x
Process ManagerPM2latest
Reverse ProxyTraefiklatest
ValidationZod3.x
SecurityHelmet8.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:

typescript
// 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:

typescript
// 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:

typescript
// 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:

typescript
// 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:

typescript
// 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:

typescript
// 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)

PageRouteFeatures
Home/Hero, Impact stats, Programs teaser, Testimonials, Partners, CTA
About/aboutMission, Vision, Values, History, Team preview
Programs/programsCategory filter, program cards, image gallery
Team/teamFounders, Board, Staff, Volunteers with profiles
Testimonials/testimonialsCategory filter, quote cards with photos
Events/eventsUpcoming + past events, calendar view
Reports/reportsCategory filter, search, PDF download
Blog/blogArticle listing, category filter, search
Gallery/galleryMasonry grid, lightbox, albums
FAQ/faqAccordion with FAQPage JSON-LD schema
Donate/donateTiers, one-time/recurring, Razorpay, 80G notice
Contact/contactForm, map, contact details
Partners/partnersAssociate & funding partners grid

Design System: Control Matrix / Mosonie Modern

The UI follows a premium design system with strict 8px semantic grid:

css
/* 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:

typescript
// 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:

code
/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 endpoints

Authentication Flow

JWT-based authentication with httpOnly cookies:

typescript
// 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:

ModuleRouteCapabilities
Dashboard/adminReal-time telemetry, platform stats, live audit logs
Programs/admin/programsCRUD for foundation initiatives with dynamic status
Team Members/admin/teamModern grid for board, staff, contributors
Impact Scorecard/admin/impactSocial performance metric calibration
Events/admin/eventsLifecycle management with gallery support
Blog/admin/blogMarkdown content with category filtering
Gallery/admin/galleryAlbum management and media organization
Partners/admin/partnersFunding and associate partner management
Donations/admin/donationsReal-time contribution tracking
Newsletter/admin/newsletterSubscriber management and sync
System Logs/admin/system-logsImmutable audit trails
Settings/admin/settingsGlobal metadata, SEO, contact parameters
Inquiries/admin/inquiriesContact form triage
Storage Browser/admin/storageS3-integrated asset manager
Auth & Security/admin/loginJWT session control and RBAC

The admin dashboard uses Client-Side Rendering (SSR disabled) for optimal editing experience:

typescript
// 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

MetricTargetStrategy
Performance95+SSR HTML, Redis cache, presigned URLs, code splitting
Accessibility100Semantic HTML, ARIA labels, focus rings, WCAG AA
Best Practices100HTTPS, security headers, no deprecated APIs
SEO100Unique meta/OG per page, JSON-LD, sitemap

Optimization Techniques

  1. Asset Migration: 100% WebP/AVIF with responsive sizing via OptimizedImage component
  2. Resource Preloading: Critical fonts and third-party domains preconnected
  3. LiteYouTube Facade: Video embeds deferred via lightweight facade
  4. Partytown: Analytics offloaded to web worker
  5. Aggressive Caching: Tiered Redis for API, immutable for assets
  6. HSTS Bypass: Configurable for local Lighthouse audits

Lighthouse CI Integration

Automated performance auditing via LHCI:

yaml
# 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

SubdomainServiceAccess
mosonie.orgWeb + APIPublic
storage.mosonie.orgMinio S3Public
console.mosonie.orgMinio ConsoleAdmin only
db.mosonie.orgAdminerAdmin only

Docker Production Stack

bash
# 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       # Preview

Deployment Pipeline

  1. Pre-flight checks (SSH, Git)
  2. Local API verification tests
  3. Git commit & push
  4. Rsync code to VPS
  5. Docker build & restart
  6. Prisma schema migration
  7. Health check (Web + API)
  8. Production module audit
  9. Summary report

Service URLs (Production)

ServiceURL
Websitehttps://mosonie.org
APIhttps://mosonie.org/api/v1
Adminhttps://mosonie.org/admin
Minio Consolehttps://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.

Submit a Technical Suggestion