Project structure
What you’ll learn
- What every folder in a Strutvane project is for
- Which files you edit, and which are generated for you
- Where to put your own code
The tour
Section titled “The tour”Directoryapp/ your application code
Directorymodels/ what your data looks like (start here)
- invoice.model.ts
Directoryresources/ optional extra behaviour per model (hooks, actions)
- …
Directorypolicies/ who may do what (authorization rules)
- …
Directoryservices/ your business logic
- …
Directoryhttp/
- routes/api.ts your own custom endpoints
Directorymiddleware/ code that runs on every request
- …
Directoryjobs/ background tasks (Planned: the queue isn’t built yet)
- …
- providers/app.provider.ts start-up wiring for your app
Directoryconfig/ settings, readable and typed
- app.ts
- database.ts
- auth.ts
- …
Directorydatabase/
Directorymigrations/ database changes, generated and committed to Git
- …
Directoryseeders/ fills the database with starting or fake data
- …
Directoryfactories/ recipes for fake records, used in tests
- …
Directoryweb/ the screens (a Vite + React shell around @strutvane/ui; only if you use the UI)
- …
Directorytests/ feature, unit and end-to-end tests
- …
Directorystorage/ logs and uploads (not committed)
- …
Directorydocker/ local services (local only, not committed)
- …
Directory.strutvane/ generated by Strutvane (not committed, rebuilt automatically)
- …
- .env your local settings and secrets (never committed)
- .env.example every setting, documented (committed)
- env.ts, env.schema.ts every environment variable, validated at start-up
- strutvane.config.ts which Strutvane packages are switched on
- package.json
- CLAUDE.md notes for AI coding assistants
What you edit vs. what’s generated
Section titled “What you edit vs. what’s generated”| You edit | Generated for you (don’t edit) |
|---|---|
app/**, config/**, web/** |
.strutvane/** (the typed registry, rebuilt by pnpm sv registry:build) |
database/seeders, database/factories |
database/migrations/*.sql (generated once, then committed and never changed) |
.env (your machine only), .env.example |
Where should my code go?
Section titled “Where should my code go?”| I want to… | Put it in |
|---|---|
| Add a new kind of data | app/models/ (use pnpm sv make:model) |
| Run code before or after saving a record | app/resources/<model>.resource.ts (hooks) |
| Add a button like “Approve” | app/resources/<model>.resource.ts (actions, Planned) |
| Write business logic used in several places | app/services/ |
| Add an endpoint that isn’t about one model | app/http/routes/api.ts |
| Do something slow without making users wait | app/jobs/ (Planned) |
| Change how a column or input looks | UI overrides in web/ (see The UI) |
Next steps
Section titled “Next steps”Environment variablesWhat goes in .env and .env.example.
CLI commandsThe make:* commands that create these files.