🗂 Project Structure
You don’t need to understand the entire repository. Here is the map of what a builder actually touches.
GoShipped is a monorepo. Most folders are infrastructure you will rarely open. A small set of files is where your product lives. Start there.
You
↓
Next.js (`apps/web`) what people see
↓
FastAPI (`apps/api`) chat, agents, billing, email
↓
Supabase Auth, Postgres, pgvector, Storage
↓
AI providers · Stripe · Resend only the ones you enableYou probably will not touch most of this on day one.
The mental model
Four things matter on day one:
| Piece | Path | What it is |
|---|---|---|
| Frontend | apps/web | Next.js 16 app: marketing site, auth, chat, settings |
| Backend | apps/api | FastAPI app: conversations, streaming, tools, billing APIs |
| Data | supabase | CLI config, migrations, Auth email templates |
| Product config | starter.config.json | Name, branding, feature flags |
Secrets live in env files next to each app. There is no root .env.
The repo also has docs/ — the in-product documentation that shipped with your checkout. Use it when you want a deeper dive. These public pages are the starting map.
What you will actually open
If a path is not in that list, you can probably ignore it until you have a reason.
I want to change…
| I want to change… | Look here |
|---|---|
| App name, logo, colors, feature flags | starter.config.json |
| Landing page copy and sections | apps/web/src/config/marketing.ts |
| Landing page layout | apps/web/src/components/marketing/ and apps/web/src/app/(marketing)/ |
| Chat UI | apps/web/src/components/chat/ and apps/web/src/app/chat/ |
| Auth screens | apps/web/src/components/auth/ plus login, register, forgot-password |
| Settings | apps/web/src/app/settings/ and apps/web/src/components/settings/ |
| AI models / providers | apps/api/app/llm/ |
| Agents, planner, built-in tools | apps/api/app/ai/ — see Agents |
| Add a custom AI tool | apps/api/app/ai/tools/tools/example_tool.py — see Tools |
| RAG / file uploads | apps/api/app/services/file_service.py, apps/api/app/services/embedding_service.py |
| Long-term memory | apps/api/app/services/memory_service.py |
| MCP servers | apps/api/config/mcp_servers.yaml (off by default) |
| Payments | apps/api/app/billing/ and apps/api/app/plans/ |
| Product emails | apps/api/app/email/ |
| Auth emails | supabase/templates/ |
| Database schema | supabase/migrations/ |
| Setup, doctor, deploy | scripts/setup/, scripts/deploy/ |
Frontend (apps/web)
This is the Next.js app people use.
Public marketing routes live in a route group so you can rebrand or delete the marketing site without touching chat:
src/app/(marketing)/—/,/pricing,/privacy,/termssrc/config/marketing.ts— copy, section flags, legal identity
The product itself:
/chat— the AI app/settings— profile, AI, billing, usage, account/login,/register,/forgot-password— auth UI
Product name, colors, and feature flags still come from starter.config.json, not from the marketing file.
Backend (apps/api)
This is FastAPI. The Next.js app never calls OpenAI or Anthropic directly.
Useful directories:
| Path | Role |
|---|---|
app/api/v1/ | REST routes |
app/llm/ | OpenAI and Anthropic providers |
app/ai/ | Planner, tools, Deep Research, web/stocks helpers |
app/services/ | Chat, files, memory, storage, users |
app/billing/ | Stripe Checkout, portal, webhooks |
app/email/ | Resend product emails |
app/db/ | SQLAlchemy models and the database session |
app/features.py | Server-side feature flags |
OpenAPI is at https://localhost:8000/docs when the API is running.
Supabase
supabase/ is the source of truth for schema and local Auth config.
| Path | Role |
|---|---|
supabase/migrations/ | Postgres + pgvector schema. Apply all of them, in filename order. |
supabase/config.toml | Local Auth, email templates, CLI project id |
supabase/templates/ | Confirmation and recovery emails for local Auth |
Hosted Auth URLs and SMTP are configured in the Supabase dashboard, not in this folder. See redirect URLs and custom SMTP when you get there.
Docker is only for local pnpm supabase:start. Linking and pushing a hosted project does not need Docker.
Config files
starter.config.json committed product config
apps/web/src/config/marketing.ts public website copy
apps/web/.env.local frontend secrets
apps/api/.env backend secretspnpm dev syncs starter.config.json into generated copies inside each app. Edit the root file, not the generated ones.
Next up: Configuration — what belongs in which file.