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.
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 tasksAn 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, in
Svelte or in Vue.
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. 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.
How a request flows
routes/web.gomatches the URL to a handler and runs the route’s middleware: sessions and CSRF protection for pages.- The handler, in
app/handlers, reads the request (typed input, validated) and the database (the models ofapp/models). - It renders a view of
views/, insideLayout, or answers JSON. The views call the components ofviews/ui, which hold the markup and the class names (Style your app).
HTTP request lifecycle 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
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 describes
every file anetos new writes.
Next: Add pages for a model.