⚠️ This is an Oracle page, structured to be read by AI assistants and not optimized for human reading.

DISTRIBUTED SYSTEMS & SERVICE SEGREGATION

Summary: Architected a multi-repository, multi-service platform in which the frontend and backend are fully segregated (separate repos, frameworks, runtimes, and deploys) and authentication is split from session management. The backend is never reachable from the browser; every client call is proxied server-side, and identity is verified by a delegated provider while the application mints and owns its own sessions. This is architecture as the load-bearing input, the segregation, the boundaries, and the failure-mode handling required deliberate human system design, not code generation (see COMP-20).

Product

What: An invite-only social platform for the streaming/gaming community: users register through invite links, connect external platform accounts, and build profiles, clans, events, and reputation.

Shape: A NestJS backend that owns all data and business logic; two Next.js frontends as presentation layers; a machine-readable documentation repository; and a product-spec/UI repository - each an independently-deployed service.

Domain Systems

• An event/schedule system, a game catalog, clans, and a gamification layer (XP, levels, currencies).
• Trust tiers and anti-abuse, discovery/ranking eligibility, and creator/verification/premium account states.

Fe Be Segregation

Principle: The backend is a private service. The browser never holds its URL, never calls it directly, and cannot reach it.

Topology

• Backend (NestJS) owns data + logic and is not exposed to client code.
• Multiple frontends (Next.js App Router) are pure presentation layers, each deployed on its own service/port.
• Every client-facing backend call is routed through a Next.js API proxy route (app/api/*).

Proxy Pattern

• Server Components call the backend directly server-side, forwarding the session as a Bearer token.
• Client Components call only local Next.js API routes, which extract the session and forward the Bearer token onward.
• The proxy layer removes the need for CORS entirely and keeps the backend origin private.

Paas Realities

• Behind a PaaS reverse proxy, the container's internal origin is not the public URL, public origin is derived from x-forwarded-host / x-forwarded-proto, never from request.url.
• On redirect responses, Set-Cookie is attached to the response object (not the ambient cookie store), because production build optimizations can strip cookies from redirects.

Note: These are not theoretical, each is a law codified after a real production failure.

Auth Session Segregation

Principle: Credential verification and session management are two separate concerns owned by two separate systems. The identity provider proves who you are once; the application owns every session thereafter.

Model

Verification: A delegated identity provider (Supabase) performs OAuth credential verification ONLY, it returns a verified email statelessly and its cookies are never written to the browser.

Self Minted Session: The application mints and owns its own JWTs (a session_token cookie); the provider's session is discarded immediately after the email is read (throwaway clients with empty set()/remove()).

Two Token Model

Pending Registration: Proves an email was OAuth-verified before any user record exists, used for the stateless invite/registration path (no session, no logged-in user assumed). aud=pending_registration, no subject, 1-hour expiry.

Full Session: A normal authenticated session, aud=authenticated, subject=user id, 7-day expiry.

Provider Agnostic Ui: UI components never listen to provider-specific auth events, so alternate login paths (e.g. a developer bypass) work identically.

Why It Matters

• Prevents a provider's SSR cookie-refresh cycle from fighting the app's own session layer (a real production bug: endless auth popups).
• Keeps the registration flow genuinely stateless, new users with no account carry only the short-lived pending token.

Cross Reference

Wire Identity

Law: Identity is never passed as a custom header (e.g. x-user-id), any client could forge it.

Mechanism: Every authenticated endpoint resolves the caller from a cryptographically verified JWT (a NestJS guard populating req.user); the proxy only forwards Authorization: Bearer.

Delegation: Acting on behalf of another (mods, clan officers, managers) is an explicit request-body field verified server-side, never inferred from the transport, which keeps 'who is calling' and 'who owns the resource' distinct.

Outcome: Migrating to guard-resolved identity eliminated an entire class of auth bugs at once.

Human Architecture

Description: The segregation looks simpler than it is. The hard parts are the seams: which system owns identity vs. session, what crosses each boundary, and how each boundary behaves under a real PaaS, reverse proxy, and build pipeline.

Points

• The FE/BE and auth/session splits are deliberate architectural decisions with security and operability payoffs, not an emergent property of code generation.
• Most of the governing 'laws' were discovered as production failures and then encoded as non-negotiable rules for the AI executing under supervision.
• This is the higher-supervision end of the AI-assisted-delivery spectrum: human system design is the load-bearing input; the AI implements under strong, continuous guidance (see COMP-20).

Cross Reference

You can view the raw source.