[Architecture] Build Server-Side Layer with Middleware, API Routes, and Server Components

[KarenZita01]

Description

The frontend has no middleware, no API routes, and no server-side logic. Next.js provides powerful server-side features like middleware for request processing, API routes for backend functionality, and server components for performance. None of these are utilized.

Backend-for-frontend (BFF) gaps:

• No API routes for proxying blockchain calls
• No server-side data fetching with server components
• No middleware for auth checks, redirects, or header manipulation
• No rate limiting for API routes
• No request validation for API inputs
• No server-side caching strategies
• No webhook handlers for backend events
• No server-side logging
• No health check endpoint
• No server-side session management

Technical Context & Impact

• Affected Components/Files: src/middleware.ts (missing), app/api/ (missing), src/lib/server/ (missing)
• Impact: No server-side processing; all logic runs client-side

Step-by-Step Implementation Guide

1. Create middleware: src/middleware.ts:
   • Auth check: verify session token on protected routes
   • Locale detection and redirect
   • Security headers (CSP, HSTS, X-Frame-Options)
   • Bot detection (block known crawlers from /dashboard/*)
   • Rate limiting by IP
2. Add API routes: app/api/:
   • GET /api/meters - Proxy to backend API with auth
   • POST /api/transactions - Build and return Stellar transaction XDR for signing
   • GET /api/billing/summary - Aggregated billing data
   • POST /api/webhooks/stellar - Handle Stellar network events
   • GET /api/health - Health check returning server status and version
3. Add server-side data fetching: Convert key pages to server components where possible:
   • Dashboard overview - fetch meter count, total streams, TVL on server
   • Meter list - initial data fetch on server, hydrate client
4. Implement API request validation: src/lib/server/validate.ts with Zod schemas for each API route
5. Add server-side caching: stale-while-revalidate pattern for API response caching
6. Create server utilities: src/lib/server/:
   • logger.ts - Structured logging (pino or similar)
   • auth.ts - Server-side auth verification
   • cache.ts - Redis or in-memory cache for backend proxy
7. Add webhook secret verification: Verify x-webhook-signature header with HMAC-SHA256
8. Set up error reporting: API routes report errors to Sentry with context

Verification & Testing Steps

1. Call /api/health -> returns { status: 'ok', version: '1.0.0', timestamp }
2. Test middleware auth: request protected page without auth -> 302 redirect
3. Test API proxy: GET /api/meters -> returns meter list from backend
4. Test rate limiting: 100 requests in 1 minute -> 101st returns 429
5. Test webhook handler: send valid Stellar webhook -> returns 200
6. Test server component: view page source -> verified data rendered on server
7. Run npx tsc --noEmit