Project structure

A new app from the app kit looks like this. Folders appear as you add packages, so a blank app has fewer.

my-app/
├── app/
│   ├── routes/            # one file per page
│   │   ├── __root.tsx     # the layout around every page
│   │   └── index.tsx      # the home page, at /
│   ├── features/          # code grouped by feature: queries, forms, components
│   ├── components/ui/     # components copied in by `kitr ui add`; yours to edit
│   ├── stores/            # app-wide state (kitr add state)
│   ├── app.ts             # creates the app from kitrrc.ts and config/
│   ├── env.ts             # environment variables, validated at startup
│   ├── router.tsx         # creates the router
│   └── routeTree.gen.ts   # generated from app/routes; never edit
├── config/                # one file per package that has options
├── kitrrc.ts              # which packages are installed and wired
├── AGENTS.md              # conventions for coding assistants, kept up to date by kitr add
└── vite.config.ts         # one line: plugins: [kitr()]

The three files that wire everything

kitrrc.ts lists the kitr packages in the project and their providers. Nothing is discovered by magic: if a package affects your app at startup, it's in this list.

config/<package>.ts holds one package's options, typed by that package's defineConfig. config/query.ts configures Query, config/http.ts configures HTTP, and so on.

app/env.ts declares your environment variables. Public ones (prefixed VITE_) reach the browser; server ones throw if browser code reads them. A missing or malformed variable stops the app at startup with a clear message, not halfway through a request.

Features, not file types

Group code by what it does for the user rather than what kind of file it is:

app/features/projects/
├── queries.ts        # defineQuery / defineMutation for projects
├── project-form.tsx
└── project-list.tsx

The generators follow this: kitr make:queries projects writes app/features/projects/queries.ts.

Full-stack and backend apps

A fullstack app adds server code beside the client:

app/
├── api/routes.ts       # API routes (kitr add api)
├── controllers/        # one class per resource
├── actions/            # server actions (kitr add actions)
└── channels/           # realtime channels (kitr add realtime)

A server app has no app/routes or React at all. See A backend without React.