Historical snapshot archived 2026-09-25. This records an earlier review or plan, not current implementation or live ticket state. For current work, follow root AGENTS.md, the relevant BloxClips skill, and owning repository source/tests. Preserve approved decisions as evidence; verify their present authority before acting.

Historical snapshot — superseded for agent navigation (2026-09-25). This document can describe retired architecture, old database/payment models, or primary-checkout paths. Do not use it as current implementation policy. Start with the project router, resolve the owning Treehouse lease, then load its repository skill/source index. The original text below is retained for historical reasoning.

Architecture

System context

flowchart LR
    User[Creator / Admin / Visitor] -->|HTTPS, cookie session| Frontend[Next.js frontend]
    Frontend -->|REST + SSE, credentials included| API[Express API]
    Frontend -->|contact / member count / Roblox proxy| NextRoutes[Next.js server routes]
    API --> DB[(PostgreSQL)]
    API --> Social[YouTube API / Apify]
    API --> Payments[Stripe / PayPal / NowPayments / Tax1099]
    API --> Messaging[Discord / Resend / Twilio / Google Calendar]
    API --> Storage[Cloudflare R2 or local storage]
    NextRoutes --> Whop[Whop company API]
    NextRoutes --> Resend[Resend + Turnstile]
    Bot[Discord bot process] --> Discord[Discord]
    Bot --> DB
    API -. in-process timers .-> Workers[Payment, tax, PV tracker work]
    Workers --> DB
    Workers --> Payments
    Workers --> Social

There is no durable queue service. “Workers” above are functions scheduled inside the API process. The separate bot process and API process each create a Discord client for different purposes.

Application components

flowchart TB
    subgraph FE[Next.js repository]
      Public[Public marketing and case studies]
      Creator[Creator dashboard pages]
      AdminUI[Admin operations pages]
      Fetch[Direct fetch callers + adminFetch]
      NextAPI[Next route handlers]
      Public --> NextAPI
      Creator --> Fetch
      AdminUI --> Fetch
    end

    subgraph BE[Backend repository]
      Compose[src/api/index.ts Express composition]
      MW[Auth/admin/origin/rate-limit middleware]
      Routes[Domain routers]
      Services[Utility/service workflows]
      Prisma[Prisma client]
      Schedulers[In-process schedulers]
      DiscordIntegration[Discord publishing/client]
      Compose --> MW --> Routes --> Services --> Prisma
      Routes --> Prisma
      Schedulers --> Services
      Schedulers --> Prisma
      Routes --> DiscordIntegration
    end

    Fetch --> Compose

The backend does not consistently use a controller/service/repository split. Routers often perform orchestration and Prisma access directly, while complex work such as payout processing, tax forms, referral accounting, social scraping, and budget calculation is delegated to src/utils/ modules.

Deployment boundaries

Confirmed code boundaries:

• One Next.js application.
• One API process started by src/api/server.ts.
• One Discord bot process started by src/index.ts.
• One PostgreSQL database.
• External object storage is optional in development and mandatory in production.

The older DEPLOYMENT.md describes DigitalOcean, PM2, Supabase/PostgreSQL, and Cloudflare, while the frontend has Vercel configuration. No current infrastructure-as-code or CI workflow confirms which topology is live.

Request lifecycle

For a typical authenticated mutation:

1. A client component constructs ${NEXT_PUBLIC_API_URL}/api/... and calls fetch(..., {credentials: "include"}).
2. Express applies Helmet/CORS, JSON limits, cookies, origin protections, device/referral parsing, and rate limits in src/api/index.ts.
3. requireAuth reads auth_token, verifies its JWT signature and jwtVersion, reloads/caches the user, and checks active bans.
4. Administrative routers additionally run requireAdmin, based on configured Discord IDs or verified email allowlists.
5. A router validates input (Zod for some shared shapes, manual checks elsewhere), runs Prisma queries and/or a domain utility, and returns hand-built JSON.
6. The frontend updates local state or refetches. There is no normalized client cache.

sequenceDiagram
    actor U as User
    participant F as Next client page
    participant E as Express middleware/router
    participant S as Domain utility
    participant D as PostgreSQL
    U->>F: click / submit
    F->>E: fetch API with auth cookie
    E->>D: resolve JWT user and ban state
    E->>S: validate and perform workflow
    S->>D: read/write domain rows
    D-->>S: result
    S-->>E: domain outcome
    E-->>F: JSON or SSE event
    F-->>U: local state/refetched UI

Coupling characteristics

• Frontend API paths, field names, string status values, and role expectations are manually duplicated. There is no shared OpenAPI schema or generated client.
• Campaign spend, submission acceptance, tracking, dashboard stats, and payouts all depend on shared-but-not-uniform interpretations of views, rate, caps, thresholds, and fees.
• Both server repositories implement Whop count and Roblox proxy routes; consumers select one by URL rather than a shared integration layer.
• Both legacy and current identity keys remain (Submission.userId/Discord ID and webUserId), and both legacy and delta payout models are active in source.
• Timers and caches are bound to process lifetime. Scaling API instances would duplicate scheduled work and split cache/rate-limit state unless coordinated externally.