File map
Every top-level folder, what it is for, and which ones you are likely to touch.
An installation is one folder with about a dozen entries in it. This page is the map, so that a glance at the file tree is enough to know where something lives.
The folders, one at a time
app/, the routes
The App Router, grouped by who the visitor is rather than by feature.
| Group | Serves | Notes |
|---|---|---|
(marketing) | The public site | (site) for the pages with the footer, legal/ for the pages without |
(app) | The signed-in product | Chat, projects, code, library, images, billing, account settings |
(admin) | The panel | One route with a section parameter, and one panel component per screen |
(auth) | Sign in, sign up, reset | One screen that steps through its own states |
(docs) | This manual | Fumadocs, reading content/docs |
api/ | The routes the browser calls | Streaming, uploads, search, webhooks |
i/ | Public shares | /i/images/... and /i/files/... open without signing in |
s/ | Short links | Redirects, so a shared address stays short |
app/layout.tsx is the root: it reads the installation's appearance from the database before anything is
drawn, so the correct theme and motion policy are in place on the first paint. app/globals.css is the whole
design system: the tokens for both themes, the radii, the two accessibility settings, and the Fumadocs
stylesheet the documentation borrows.
components/, the interface
One folder per area of the app, plus:
ui/: the shadcn-style primitives, generated and then edited by hand where this product needs them.animate-ui/: the registry components this house prefers for motion, including the theme wipe.docs/: the two small pieces the documentation needs of its own, the wordmark and its theme switch.
content/docs/, this manual
Plain MDX files with frontmatter. Adding a page is adding a file, and the sidebar, the search index, the table
of contents and the previous/next links are all derived from that file. Ordering inside a folder comes from a
meta.json beside it.
convex/, the backend
The schema, the queries and mutations, the actions that call other people's APIs, the scheduled functions and
the migrations. This is a separate project with its own tsconfig.json, and it is deployed on its own with
npx convex deploy.
lib/, the rules
Small pure modules with tests beside them, kept out of components so they can be reasoned about and tested on their own. Two are worth knowing by name:
lib/environment.ts: the nineteen variable names, each with what it is for, where it comes from and which environment reads it. Both installers and the panel's Environment screen read this one file, so the three of them cannot disagree.lib/plans.tsandlib/entitlements.ts: what a plan is, and what each one unlocks.
installer/ and scripts/, the two ways in
installer/serve.ts is a small server that binds to the loopback address only, hands out one page, and accepts
a fixed list of actions. installer/index.html is that page. scripts/install.mjs is the command-line walk.
Both read lib/environment.ts and lib/setup.ts, which is why the browser installer and the terminal one ask
exactly the same questions.
public/, the files served as they are
The wordmarks and the smaller marks, the file-type icons, the payment and vendor brands used to label
integrations, and public/vendor/, which holds the WebAssembly bundler the in-browser editor needs. That last
one is written by scripts/vendor.mjs, which runs automatically before pnpm dev.
The files in the root, and why each is there
| File | What it is |
|---|---|
setup.command | The double-click for macOS |
setup.bat | The double-click for Windows |
setup.sh | The double-click for Linux |
README.md | The short version of this manual, for reading beside the folder |
.env.example | All nineteen names with a line about each, and no real values |
package.json | The commands and the dependencies |
next.config.ts | Next.js, plus the MDX plugin that gives this manual its pages |
wrangler.jsonc | The Cloudflare Worker this app deploys as, when you deploy it that way |
open-next.config.ts | What the Cloudflare adapter does beyond its defaults |
components.json | The shadcn configuration, so new primitives can be added the same way |
AGENTS.md | The note that tells an AI coding assistant the framework conventions to read first |
Two folders that are not in the tree above
.next/ is the build output and node_modules/ is the packages. Both are
generated, both are ignored by version control, and neither should be edited
or committed. If the app starts behaving in a way that contradicts the code,
deleting .next/ and building again is the first thing to try.