Project layout
Kata locks the folder layout — the named files below and the shape of every module. Every route, service, schema, and test lives at a path you can predict from its domain name — nothing floats, and nothing is wired together by a config file. This is convention-over-configuration taken literally: a file's name and location are data the tooling reads, not just tidiness for humans. The layout is the contract kata verify checks, and the reason an agent — or you — can find the file it needs without searching.
The tree
src/
├── app.ts # createApp({ modules, middlewares? }) — optional
├── context.ts # defineContext({ ... }) — the DI registry
├── main.ts # boot: serve(app.fetch, ...)
├── middlewares/ # cross-cutting middleware (auth, tx, ...)
└── modules/
└── <domain>/
├── <domain>.route.ts # defineRoute calls only
├── <domain>.service.ts # pure functions
├── <domain>.schema.ts # Zod schemas (DTOs)
├── <domain>.hurl # API E2E (Hurl)
└── <domain>.test.ts # unit testsThe tree is normative, not exhaustive. The named files are fixed and modules/ is constrained, but the src/ root also takes files of your own — a config.ts, a store.ts. The src/ root below states the rule.
context.ts is special. It holds your one defineContext({...}) call and re-exports defineRoute, defineMiddleware, and createApp already bound to the registry. The verify harness reads this exact file to learn which keys c.get(...) may use — so it has to be src/context.ts, not renamed and not split. Move it and the DI checks have nothing to read.
A domain is a folder under src/modules/. Its files share the domain prefix: the users domain is users.route.ts, users.service.ts, users.schema.ts, and so on. One folder, one prefix, no exceptions.
Why findability matters
Here is the load-bearing idea: the suffix is the type of the file. A file named users.route.ts contains route declarations; users.schema.ts contains Zod DTOs; users.service.ts contains pure functions. Because the suffix carries that meaning, both tooling and people can locate any file from its name alone:
# every route in the app
ls src/modules/*/*.route.ts
# every DTO
ls src/modules/*/*.schema.ts
# the service for one domain
cat src/modules/users/users.service.tskata verify walks src/ and dispatches rules by suffix — no glob library, no config. The walk skips the node_modules, dist, build, coverage, data, and .git directories, and drops *.test.ts, *.d.ts, and *.schema.ts files before any rule runs. Each remaining file is routed by its name:
*.route.ts→ checked for mandatoryinput/output, inline schemas, and unregistered or unprovided context keys.*.service.ts→ checked for inline schemas (a service is the other place a strayz.object(...)is rejected).*.schema.ts→ the one place a Zod schema may live, so it is excluded from the walk; no rule reads it.
If you inline a schema in a .route.ts, or put a route in a misnamed file, the checks key off the wrong suffix and the harness reports it. The layout is what makes the rules cheap and exact. See The harness for the full rule set.
Dropping *.test.ts means a route declared in a test has zero rule coverage
The drop is deliberate — test files are not published surface — but it has a consequence worth stating, because one of our own recipes lands in it. The error-boundary recipe tells you to call defineRoute inside the test file, and a route declared there is invisible to every rule: an inline z.object(...), a scoped slot read without a provider, a missing output — all pass kata verify clean, including under --strict-coverage, which will not even report a suppression, because the file was dropped before any rule ran.
That is the right trade-off for a throwaway route whose only job is to throw. It is the wrong place for logic you actually rely on: anything you want the harness to check belongs in a .route.ts or .service.ts, where it is checked.
One prefix per file
users.route.ts is correct. routes/users.ts, user-routes.ts, or a UsersController are not — the suffix carries the meaning, and the harness matches on it. Renaming context.ts breaks DI checks the same way.
The src/ root
The lock is asymmetric, and the rule is worth stating outright rather than leaving it to be discovered:
- The
src/root is open. Shared non-HTTP infrastructure lives here: aconfig.ts, astore.tsor connection pool, a logger, a typed RPCclient.ts, cross-module test helpers. Any filename passes — no naming rule applies at the root. The worked examples all use this:examples/hellokeepsJWT_SECRETinsrc/config.ts,examples/shophassrc/store.ts, andexamples/hello-clienthassrc/client.ts. - Module directories stay locked. Inside
src/modules/<domain>/every file is<domain>.route.ts,<domain>.service.ts,<domain>.schema.ts,<domain>.test.ts, or<domain>.hurl— nothing else.
Cross-module and process-level test suites
A <domain>.test.ts proves one module. Some suites cannot be scoped to a single domain — an HTTP flow that crosses module boundaries, the graceful-shutdown drain sequence (which has to spawn main.ts as a child process; see Testing graceful shutdown), or the typed RPC client exercised against the running app. None of these has a domain folder to live in, so they belong beside app.ts, context.ts, and main.ts, at the src/ root: src/e2e.test.ts, src/main.shutdown.test.ts, src/client.test.ts. A shared fixture such as a test-server.ts helper that boots the app once for several suites is exactly the kind of root file the previous section already allows — name each file for what it proves; vitest's default glob (**/*.test.ts) picks it up regardless of where under src/ it sits.
Why the src/ root and not a top-level tests/ or e2e/ directory: the generated tsconfig.json scopes "include" to ["src"] — nothing outside src/ is type-checked. A suite placed in a sibling tests/ folder would still run under vitest, but tsc would never see it, silently losing any type-level proof the suite carries (the RPC client worked example's @ts-expect-error fixtures are exactly this kind of proof — see Typed RPC client). Widening include would fix that, but tsconfig.json is a protected config (ADR-0010): an agent may not edit it, and a human editing it away defeats the same scoping that keeps kata verify's walk — and tsc's — cheap and exact. Keeping every suite inside src/, cross-module or not, is what keeps it both type-checked and inside the one directory the harness actually looks at.
These root-level suites are still just files under src/: kata verify drops *.test.ts before dispatching any naming or schema rule (see Why findability matters above), so nothing about placement or naming at the root is enforced beyond the .test.ts suffix vitest itself relies on.
Enforcement matches the rule exactly: kata/schema-file-naming inspects only paths of the form src/modules/<domain>/<file> — a file at the src/ root is never checked for its name. Root files are still code under src/, so the code-level rules (kata/no-class, kata/no-decorator, …) apply to them like any other file; only the naming constraint stops at the module boundary.
The asymmetry is the point. Inside a module the suffix is the file's type — that is what lets kata verify dispatch rules mechanically and lets anyone find a file by name alone. A root file has no HTTP surface, so there is no suffix contract to enforce: keep route, service, and schema code out of it and name it whatever reads best.
app.ts vs. folding it into main.ts
app.ts builds the application — one createApp({ modules, middlewares? }) call — and exports it. main.ts is the runtime entrypoint: it imports the app and hands app.fetch to a server.
// src/app.ts
import { createApp } from './context'
import * as users from './modules/users/users.route'
export const app = createApp({ modules: [users] })
export type AppType = typeof app // the type your RPC client imports// src/main.ts
import { serve } from '@hono/node-server'
import { app } from './app'
import { k } from './context'
const port = Number(process.env['PORT'] ?? 3000)
serve({ fetch: app.fetch, port }, (info) => {
k.resolve('logger').info(`listening on http://localhost:${info.port}`)
})Why split them? Because it keeps the app constructible in isolation — your tests and the typed RPC client import AppType from app.ts without booting a server, while main.ts stays a thin boot script that owns the socket.
For a small service you may fold app.ts into main.ts — call createApp inline and serve it in one file. Both worked examples do exactly this:
// src/main.ts — examples/hello
import { serve } from '@hono/node-server'
import { bodyLimit, cors, secureHeaders } from '@katajs-framework/core'
import { createApp, k } from './context'
import * as auth from './modules/auth/auth.route'
import * as diag from './modules/diag/diag.route'
import * as echo from './modules/echo/echo.route'
import * as users from './modules/users/users.route'
const app = createApp({
modules: [users, auth, echo, diag],
middlewares: [cors(), secureHeaders(), bodyLimit({ maxSize: 8 * 1024 })],
})
const port = Number(process.env['PORT'] ?? 3000)
serve({ fetch: app.fetch, port }, (info) => {
k.resolve('logger').info(`listening on http://localhost:${info.port}`)
})app.ts is the only optional file in the tree. Splitting is the right default once you have an RPC client or want the app importable from tests; the fold is fine while the app is one file. context.ts and the module files are never optional.
Inside a module
Each <domain>/ folder is self-contained, with one responsibility per file:
<domain>.schema.ts— Zod schemas and their inferred types. DTOs live here and nowhere else (defineRoute, ADR-0005). A route imports itsinput/outputschemas from this file.<domain>.service.ts— pure functions. No framework imports, noc. Trivial to unit-test in isolation. A service reports failure by returning a result, not a response — the route maps that result onto the wire.<domain>.route.ts—defineRoutecalls only. The handler validatesc.input, calls services, and returns a value (checked againstoutput) orc.json(...)/c.error(...). See Routes & schemas.<domain>.test.ts— unit tests, typically over the service.<domain>.hurl— Hurl requests that exercise the live HTTP surface end to end.
A real domain from examples/hello:
src/modules/users/
├── users.route.ts
├── users.schema.ts
├── users.service.ts
├── users.test.ts
└── users.hurlCross-cutting middleware
Middleware that more than one domain uses — JWT auth, a transaction slot — belongs in src/middlewares/, not inside a module. Each declares the scoped slots it provides; see Middleware and App-level middleware. Shared non-HTTP infrastructure (a store.ts, a connection pool) sits at the src/ root, as in examples/shop — the rule is in The src/ root above.
Scaffolding
kata init writes this locked layout for you — src/app.ts, src/context.ts, src/main.ts, a middlewares/ folder, and two worked modules (health and greetings), each with the full route / service / schema / test / hurl set — so a new project starts in the shape the harness expects. Add more with kata new <domain>. See Bootstrap CLI.