# Project structure

> An annotated tour of a Strutvane project, showing what each folder and file is for and which ones you edit.

Source: https://vishwajit-vm.github.io/strutvane-docs/docs/0.1.x/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

> **Pre-release (0.1.0-next): APIs may still change**
> This is the layout `create-strutvane` `0.1.0-next.0` writes for a **full** project. Only the folders your choices need are created, and every folder in `app/` has a short README.

## The tour

- app/ **your application code**
  - models/ what your data looks like (start here)
    - invoice.model.ts
  - resources/ optional extra behaviour per model (hooks, actions)
  - policies/ who may do what (authorization rules)
  - services/ your business logic
  - http/
    - routes/api.ts your own custom endpoints
    - middleware/ code that runs on every request
  - jobs/ background tasks (Planned: the queue isn't built yet)
  - providers/app.provider.ts start-up wiring for your app
- config/ **settings**, readable and typed
  - app.ts
  - database.ts
  - auth.ts
  - …
- database/
  - migrations/ database changes, generated and committed to Git
  - seeders/ fills the database with starting or fake data
  - factories/ recipes for fake records, used in tests
- web/ **the screens** (a Vite + React shell around @strutvane/ui; only if you use the UI)
- tests/ feature, unit and end-to-end tests
- storage/ logs and uploads (not committed)
- docker/ local services (local only, not committed)
- .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

| 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?

| 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) |

> **Tip**
> Run `pnpm sv routes` at any time to list every endpoint and the permission it needs.

## Next steps

  - [Environment variables](https://vishwajit-vm.github.io/strutvane-docs/docs/0.1.x/configuration/): What goes in .env and .env.example.
  - [CLI commands](https://vishwajit-vm.github.io/strutvane-docs/docs/0.1.x/cli-reference/): The make:* commands that create these files.
