System overview

High-level architecture (Next.js app, API routes, Supabase, Stripe, external APIs), core concepts (notebooks, auth, audit pipeline).

The app is a Next.js App Router project: marketing and dashboard UI live under src/app, business logic under src/lib, and persistence in Supabase. Notebooks scope most customer data; organizations carry billing and trial state.

docs/how-it-works/00-SYSTEM-OVERVIEW.md

API routes

All API routes grouped by domain: notebooks, auth, audit, billing, MCP gateway, visibility, prompts, integrations, and cron.

Routes follow REST-style paths under src/app/api. Notebook-scoped handlers typically resolve slug or UUID, then apply org/notebook guards. Cron and webhook routes are documented for operators deploying to Vercel or similar.

docs/how-it-works/01-API-ROUTES.md

Backend and audit

Map of src/lib/ modules: agents, orchestrator, visibility, integrations, billing.

Agents encapsulate LLM and heuristic steps; the orchestrator advances audit runs through discrete states; billing modules enforce credits and plans. When debugging, start from the API route then jump into the lib module named in the handler.

docs/how-it-works/02-BACKEND-LIB.md

Audit state machine (PENDING → CRAWLING → SEO_FETCH → AEO_PROBES → SCORING → TASKS → COMPLETE), step flow, and resume behavior.

Runs are resumable: failures mid-pipeline can be retried without always restarting from zero. Dashboard and API consumers poll run status until completion, then read scores and generated fix tasks.

docs/how-it-works/03-AUDIT-PIPELINE.md

MCP and data flow

MCP server (npm agent3opt-mcp) proxies to /api/mcp/* with Bearer auth; tools map to gateway endpoints for notebooks.

Stdio mode runs locally with env-based credentials. Hosted Streamable HTTP uses /api/mcp/sse with per-request token injection. For user-facing setup steps, read the in-product guide at MCP and AI agents. Tool names are namespaced (e.g. agent3opt.ping, seo.run_crawl).

docs/how-it-works/04-MCP-INTEGRATION.md

Mock vs real data, Supabase tables, and how the dashboard reads data.

Production uses live Supabase data only. Understanding table relationships (notebooks, runs, issues, integrations) helps when extending APIs or writing MCP tools that aggregate multiple endpoints.

docs/how-it-works/05-DATA-FLOW.md

How to merge this system into another Next.js project or use it as reference.

Use the merge doc when porting components or the MCP package into another codebase; expect to reconcile env vars, Supabase schema, and Stripe webhooks.

docs/how-it-works/06-MERGE-GUIDE.md