# Project structure
> Every special file in a Koze app and what it's for
Package: Koze
Canonical: https://kuratchi.dev/docs/koze/project-structure
Markdown: https://kuratchi.dev/docs/koze/project-structure.md
Koze is convention-driven. Drop a file in the right place with the right name and the compiler wires it into the Worker automatically — no explicit registration.
## Canonical project shape
```text
my-app/
├─ package.json
├─ vite.config.ts plugin install point + plugin options
├─ wrangler.jsonc Cloudflare deployment config (auto-synced)
├─ tsconfig.json
└─ src/
├─ worker.ts one-line re-export of koze:worker
├─ middleware.ts request/route/response/error hooks
├─ app.koze document shell (, , )
├─ app.css global stylesheet (optional; auto-linked)
├─ assets/ static files served verbatim at the URL root
├─ routes/
│ ├─ layout.koze shared fragment wrapping every page
│ ├─ index.koze /
│ └─ blog/[slug]/index.koze /blog/:slug
├─ server/
│ ├─ *.ts private server-only modules
│ ├─ *.do.ts Durable Object classes
│ ├─ *.workflow.ts Workflow classes
│ ├─ *.queue.ts Queue consumers
│ ├─ *.sandbox.ts Sandbox classes
│ ├─ *.container.ts Container classes
│ ├─ *.agent.ts Agent classes
│ └─ schemas/ ORM schema modules
└─ lib/ shared browser-safe utilities and components (imported via $lib/*)
```
There is **no project-level config file**. Build-time options (security headers, directory overrides) are passed to the `koze()` Vite plugin in `vite.config.ts`. Request-time concerns (auth, ORM auto-migration, custom steps) live in `src/middleware.ts`. Anything generated (the `.koze/` directory, `dist/`) is build output. Never commit edits there.
## Route files
### `src/app.koze` — document shell
The outer HTML document. Owns ``, ``, ``, and ``. Exactly one `` where the layout+page stream renders.
```html
My App
```
- Optional. When absent, the framework synthesizes a minimal default shell.
- A top `
```
- Fragment, not a document. Think "wrapper component".
- Works like any other route file: top `
Items ({items.length})
for (const item of items) {
- {item.title}
}
```
- `index.koze` is the default file per segment.
- Dynamic segments use `[brackets]`: `[slug]` → `:slug`, `[...rest]` → catchall.
- See [Routing](/docs/koze/routing) for the full template syntax.
### Render chain
When a user hits `/blog/hello`:
```text
app.render(data,
layout.render(data,
page.render(data)))
```
All three files use the same `
```
### `src/server/schemas/`
ORM schema modules. Imported by `src/middleware.ts` and passed to `autoMigrate({ DB: schema })` to keep the live database in sync with the declared schema. Same modules feed `kunii(env.DB, schema)` for query-time type safety.
### `.koze/` (generated)
Build output — compiled routes, Worker module, DO proxies, transformed server modules, public asset mirror. Add it to `.gitignore`. Never edit.
## Virtual modules
Imported as `'koze:*'`. The Vite plugin synthesizes them at build time — they are not real files.
| Module | What it provides |
| --- | --- |
| `koze:request` | `url`, `pathname`, `searchParams`, `params`, `slug`, `method` for the current request |
| `koze:environment` | `dev` (compiled to a literal boolean) |
| `koze:workflow` | `workflowStatus()` and typed workflow helpers |
| `koze:pipeline` | `pipelines`, `pipeline()`, and `sendPipeline()` for discovered Pipeline bindings |
| `koze:content` | `content..list()` and `content..render(id)` for Markdown under `src/content/` |
| `koze:navigation` | `redirect()` and related helpers |
| `koze:worker` | The full Worker module (`fetch` + `queue` + DO exports) |
| `koze:middleware` | Resolves your `src/middleware.ts` |
| `koze:app`, `koze:layout` | Compiled app shell + layout renderers |
You rarely need to import the last two directly — the compiler wires them into every route.