Directory structure
Where each kind of code goes in a Caldera app.
A new starter app looks like this. Every folder has one job, and the generators (caldera make:*) put files where they belong.
This is the Inertia version. In a Next.js app, src/ is the same, and Next's app/ takes the place of resources/.
app.ts
auth.ts
env.ts
http.ts
inertia.ts
middleware.ts
server.ts
app.tsx
app.css
AGENTS.md
.env
The server: src/
| What | Where | Generator |
|---|---|---|
| Environment variables, validated with Zod | src/env.ts | |
Config: the only place env is read | src/config/*.ts | make:config |
| Tables | src/db/tables/*.ts (and src/db/schema.ts) | make:model |
| Relations: every table is registered here | src/db/relations.ts | |
| Models | src/models/*.ts | make:model |
| Policies: who may do what | src/policies/*.ts | make:policy |
| Routes | src/routes/*.ts | make:routes |
Middleware, by name (mw.auth()) | src/middleware.ts | |
| Queued jobs | src/jobs/*.ts | make:job |
| Events and listeners | src/events/*.ts, src/listeners/*.ts | make:event, make:listener |
| Schedules | src/schedules/*.ts | make:schedule |
| Mails (React Email) | src/mail/*.tsx | make:mail |
| Notifications | src/notifications/*.ts | make:notification |
| Realtime channels | src/channels/*.ts | make:channel |
| Factories and seeders | src/db/factories/, src/db/seeders/ | make:factory, make:seeder |
src/app.ts puts the app together from its providers (database, auth, queue, mail…), src/http.ts is the HTTP stack (security headers, the session, pages, your routes, error pages), and src/server.ts starts it on Node. Routes, policies, jobs, mails and channels are found by caldera generate: there's no list to keep up to date.
The pages: resources/
| What | Where |
|---|---|
Pages, rendered with c.render('Posts/Index', props) | resources/pages/**/*.tsx (make:page) |
| Layouts, picked per page | resources/layout.ts, resources/layouts/ |
| UI components (coss ui: Base UI and Tailwind) | resources/components/ui/ |
| The theme: colours, fonts, radius | resources/app.css |
| Navigation | resources/components/navigation.ts |
The components are your own code, copied into the app. Add more with npx shadcn add @coss/<name>.
Everything else
lang/: translations, one folder per locale (lang/enis the reference).drizzle/: migrations, committed with the code (caldera db:generate).tests/: Vitest tests, and Playwright browser tests intests/browser/.public/: files served as they are, including the production build of the pages..caldera/: generated types and registries. Don't edit them;caldera devandcaldera generaterewrite them.AGENTS.md: how the app is laid out and what's in it, for people and coding agents. Its lists of routes, models, jobs and channels are regenerated as you work.