# Project structure

Source: https://docs.anetos.dev/main/getting-started/project-structure/

A project is a Go module. Its folders follow what each part of the app
does; the generators (`make:crud`, `make:auth`…) add their files in the
same places.

```text
blog/
├── main.go               setup: the database, cache, queue, mail, server, routes…
├── main_test.go          tests of the home page and the 404 page
├── plugins.go            the plugins (anetos add)
├── app/
│   ├── handlers/         HTTP handlers: a request in, a page or JSON out
│   └── models/           models: Go structs for tables, and their typed columns
├── database/
│   ├── migrations/       changes to the tables, in Go, in order
│   └── factories/        test data
├── routes/
│   └── web.go            URLs to handlers, with their middleware
├── views/
│   ├── layout.templ      the page shell: the header, the flash message
│   ├── home.templ        the home page
│   ├── errors.templ      error pages (404, 500…) in the layout
│   └── ui/               the components the pages are made of: cards, forms, buttons, tables…
├── locales/en/app.yaml   the pages' text
├── public/               the web root: robots.txt, served at /robots.txt
│   └── static/           CSS (app.css, the starter theme), the icon (favicon.svg) and other files, at /assets/
├── deploy/               a systemd unit and the production settings
├── Dockerfile            a container image
├── .env                  settings for your machine (not in git)
├── .env.example          the settings, without secrets (in git)
├── AGENTS.md             instructions for coding agents (CLAUDE.md and GEMINI.md import it)
└── .agents/, .claude/    skills: coding agents' guides to common tasks
```

An API project (`anetos new --stack=api`) has `routes/api.go` instead
of `routes/web.go`, `app/handlers/welcome.go` (the answer to
`GET /api/v1`) instead of the home page, and no `views/` or `public/`;
`locales/en/app.yaml` holds its messages, and `main_test.go` tests the
welcome and a 404's JSON.

A react, svelte or vue project (`--stack=react`…) has the web
project's Go side, and its pages in `frontend/`: `src/pages/` (`Home`,
`Error`), `src/Layout`, `src/components/ui`, `src/i18n.ts` and
`src/types/` (written by `go run . types`). Instead of `views/layout.templ`,
`home.templ`, `errors.templ` and `ui/`, `views/` has `app.templ`, the
root view; `app/handlers/pages.go` declares the pages and the props
every page shares, and `public/` has `favicon.svg` and the build in
`public/build`. See [Build pages in React](https://docs.anetos.dev/main/guides/react/index.md), [in
Svelte](https://docs.anetos.dev/main/guides/svelte/index.md) or [in Vue](https://docs.anetos.dev/main/guides/vue/index.md).

A web project made with `--vite` (or `go tool anetos vite:install`) also
has `frontend/`: the scripts and styles Vite builds into `public/build`,
which the layout loads with `@vite.Tags`. See [Bundle JavaScript and CSS
with Vite](https://docs.anetos.dev/main/guides/vite/index.md). In an API project, `frontend/` is a
single-page app, which Vite builds into `public/spa` and the app serves
at `/`: see [Build a single-page app](https://docs.anetos.dev/main/guides/spa/index.md).

## How a request flows

1. `routes/web.go` matches the URL to a handler and runs the route's
   middleware: sessions and CSRF protection for pages.
2. The handler, in `app/handlers`, reads the request (typed input,
   validated) and the database (the models of `app/models`).
3. It renders a view of `views/`, inside `Layout`, or answers JSON.
   The views call the components of `views/ui`, which hold the markup
   and the class names ([Style your app](https://docs.anetos.dev/main/guides/styling/index.md)).

[HTTP request lifecycle](https://docs.anetos.dev/main/concepts/http-request-lifecycle/index.md)
explains each step.

## Settings

Settings come from the environment, and in development from `.env`:
`APP_KEY` (made fresh for each project), `DB_*`, `MAIL_*` and the rest.
Tests read `.env.testing` instead (or nothing, for SQLite: an in-memory
database). The [configuration reference](https://docs.anetos.dev/main/reference/configuration/index.md)
lists every key.

## Generated files

`*_templ.go` (from the `.templ` files) and `app/models/models_gen.go`
(the models' typed columns) are written by `templ generate` and
`anetos generate`; `anetos dev` and `anetos build` run both. Commit them, but
don't edit them.

The [CLI reference](https://docs.anetos.dev/main/reference/cli/index.md#anetos-new-directory) describes
every file `anetos new` writes.

Next: [Add pages for a model](https://docs.anetos.dev/main/getting-started/crud/index.md).
