Code map
This page orients an engineer on day one: what the top-level directories are, what each one owns, and which directories talk to which. For the why behind these boundaries, see Architecture overview.
Repo structure
src/app renders src/components; both call into src/lib, which is the shared server-side core — auth, RBAC, tenancy, the two data clients, and the domain subfolders (marketing, checks, clickup, and so on). src/inngest (background jobs) and src/mcp (the reporting MCP server) both call src/lib rather than duplicating logic. src/vendor is checked-in third-party source the team intends to modify directly. clickhouse/migrations and supabase/migrations are the schema definitions for the two data stores src/lib reaches.
The platform, at a glance
This mirrors the ingestion, analytics/ledger, configuration, creative-QC, and delivery planes in Architecture overview. It is a map of territory, not a file listing; for file-level detail use the directory table below.
Directory table
Each folder may also carry its own short folder guide (AGENTS.md) next to the code.
| Path | What lives here |
|---|---|
src/app | Next.js App Router root: the global gate, one directory per user-facing surface, and api/. |
src/app/admin | The operator/management surface: clients, users/roles, brands, ad-account bindings, ClickUp audit, sync health, issues, spend guards, MCP guide, and System Settings. |
src/app/api | HTTP Route Handlers serving browser dashboards, MCP, Inngest, webhooks, and governed automation callers. Avoid hard-coded route counts; use the live tree. |
src/app/marketing | The main reporting surface: Dashboard, Ads, Campaigns, Platforms, Insights, Attribution, Settings, and the Performance compatibility redirect. |
src/components | Shared UI root. |
src/components/admin | Admin-surface client components: the app shell, client-detail workspace, sync/ingestion health panels, ClickUp ad-binding tooling, and user/role management. |
src/components/marketing | The reporting UI: every client-facing analytics surface renders from here. |
src/inngest | All durable background jobs (Inngest). |
src/lib | Shared server-side logic: the security spine (auth, RBAC, tenancy), the two data clients, integration clients, and domain subfolders. |
src/lib/checks | The Creative QC check framework. |
src/lib/marketing | The reporting, attribution, and paid-ads ingestion core. Use the live tree rather than hand-maintained file or line counts. |
src/lib/spend-guards | Spend Guards: the check engine, platform spend and pause clients, scope (agency name prefix) rule, Slack posting, and daily summary. |
src/lib/budgets, src/lib/campaign-actions | Daily budget edits (with the $500-per-edit rule) and campaign / ad set pause and resume, both Super Admin only and audited. |
src/lib/export, src/lib/marketing/report-export.ts | Export file builders and the report export model (CSV, JSON, HTML), plus shared export templates. |
src/mcp | Read-mostly MCP server exposing Launchpad V2 reporting data to AI clients over Streamable HTTP at /api/mcp. |
src/vendor | Checked-in third-party source the team intends to modify. |
clickhouse/migrations | Numbered SQL migrations for the ClickHouse analytics store — facts, attribution, sales, creative metadata, rollup views. |
supabase/migrations | Numbered SQL migrations for the Supabase config-and-tenancy plane — clients, users, RBAC, bindings, credential vault, and more. |
scripts | Operational CLI scripts run with tsx. |
e2e | Playwright QA suite. It defaults to the configured deployed URL and accepts PLAYWRIGHT_BASE_URL for another authorized target. |
tests | Cross-cutting integration tests; many unit and contract tests also live beside source files. |
parity | V1-vs-V2 parity comparison tooling. |
docker | Container build files. |
docs | This documentation site. |
Where to go next
For per-folder detail beyond this table, read the folder guide (AGENTS.md) in the app repo. For the reasoning behind the subsystem boundaries, see Architecture overview.