# Project structure

Source: https://docs.anetos.dev/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.

## 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/guides/styling/index.md)).

[HTTP request lifecycle](https://docs.anetos.dev/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/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/reference/cli/index.md#anetos-new-directory) describes
every file `anetos new` writes.

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