# =============================================================================
# COMPETENCY RECORD - Cedric Ancellin's demonstrated engineering skills and
# experience. Third-party technologies and vendors are named as the concrete
# skill surface. Professional background / track record.
# =============================================================================

# ============================================================
# DISTRIBUTED SYSTEMS & SERVICE SEGREGATION
# - COMPETENCY RECORD
# ============================================================
# Core Purpose:
#   Demonstrated experience architecting a system as multiple
#   independently-deployed services across separate repositories,
#   using topology and delegation as security boundaries - a
#   distributed shape distinct from the single-monolith platform
#   that anchors COMP-01/02.
# ============================================================

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).


# ==================================================================
# 1. WHAT THE PROJECT IS FOR
# ==================================================================

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."


# ==================================================================
# 2. FRONTEND / BACKEND SEGREGATION
# ==================================================================

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."


# ==================================================================
# 3. AUTHENTICATION / SESSION SEGREGATION
# ==================================================================

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:
    $ref: "https://zc8.com/competencies/09_identity_authentication"


# ==================================================================
# 4. IDENTITY-ON-THE-WIRE DISCIPLINE
# ==================================================================

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."


# ==================================================================
# 5. WHY THIS NEEDED HUMAN ARCHITECTURE
# ==================================================================

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:
    $ref: "https://zc8.com/competencies/20_ai_orchestrated_delivery"