# Project structure: the files of an app

An app is one Go module whose folder holds its permission list, its `main.go` and its pages.
Some files are yours to write; the others are written by `aicoded generate`, committed with the
app and never edited by hand.

## The folders

```text
people/
  go.mod                    module people
  aicoded.yaml              the permission list
  main.go                   app.Main(app.Options{Handler: pages.NewHandler(d), OnStart: d.Start})
  deps/                     optional: type Deps, what every page shares
  pages/                    the pages, one folder each
    index.html              the page at /
    dataprovider.go         its data provider
    index.css               its styles
    route_gen.go            generated
    handler_gen.go          generated: NewHandler, which serves every page
    assets_gen.go           generated: embeds assets_gen/
    assets_gen/             generated: the built scripts, styles and images
    users/                  the page at /users
      s_login/              the page at /users/<login>
        info/               the page at /users/<login>/info
  assets/                   optional: images any page shows as /assets/<file>
  rpc/                      optional: the functions other apps may call
  services/contacts/        generated: the client of the app contacts
  .aicoded/                 generated: snapshots of the functions served and called
    migration.sql           yours, not committed: the draft of the next schema change
    migrations.json         not committed: the cache of the migrations the app published
```

`aicoded` finds an app by its `aicoded.yaml`: commands that work on several apps, such as
`aicoded dev` and `aicoded check`, take every folder below them that holds one. The app is built
as a Go module, so its `go.mod` sits next to `aicoded.yaml` (E-GEN-037).

## Who writes which file

| File | Written by |
|---|---|
| `go.mod`, `main.go`, `deps/`, your `.go` files in `rpc/` | you |
| `aicoded.yaml` | you, except its `access` and `services` sections |
| `index.html`, `index.ts`, `index.css`, images and other `.go` files in a page's folder | you |
| `dataprovider.go` | `aicoded generate`, once, in a page folder that has none; then you |
| `*_gen.go`, `*_gen.ts`, `pages/assets_gen/`, `services/<app>/`, the rest of `.aicoded/` | `aicoded generate`, and `aicoded rpc add` for `.aicoded/services/` |
| `.aicoded/migration.sql`, the draft of the next schema change | you; never committed, and sent by `aicoded publish`, see [schema changes](schema-changes.md) |
| `.aicoded/migrations.json` | `aicoded dev`, `aicoded check`, and the `aicoded` commands and MCP tools that publish or show a publish's outcome: `aicoded publish`, `aicoded status`, `publish` and `release_status`; never committed |

Generated Go files start with `// Code generated by aicoded. DO NOT EDIT.` Change their source
instead: a template, the permission list or `rpc/`, and generate again. `aicoded dev` and
`aicoded check` generate first, so a saved change is picked up. Commit the generated files:
`aicoded check --frozen` generates the app again and reports each generated file that differs
(E-CHK-001), and the security checks will refuse such an app. The [overview](overview.md) lists
what each one holds.

## A page's folder

- `index.html` makes the folder a page. A folder without one is not a page, but the folders
  below it can be.
- The folder is a Go package named after the folder: `pages/users/s_login/` is package
  `s_login`.
- `dataprovider.go` holds `DP`, the page's data provider, with `NewDP` and the hooks the
  template needs, such as `Data`. `var _ RouteDataProvider = &DP{}` makes the Go compiler name
  any hook that is missing.
- A type that the template names, in `<ssr:var type>` or `<ssr:call in out>`, is declared in a
  `.go` file of the folder, such as `types.go`. To use a type of another package, declare an
  alias: `type User = deps.User`.
- `index.ts` and `index.css` are the page's script and styles, and images sit next to the
  template.
- Tests sit next to the code as usual `_test.go` files.

## Folder names

Every folder on a page's path becomes Go code, so its name is ASCII letters, digits and `_`,
starts with a letter, and is not `main`, `testdata` or a Go keyword such as `type` or `map`
(E-GEN-043). No folder under `pages/` starts with `_` or `.`: Go tools skip such folders, so the
security checks would never see them. The folder name is also the page's part of the URL.

- A folder named `s_<name>` takes any one part of the URL, and `n_<name>` a whole number. See
  [routing](routing.md).
- `__ws`, `_aicoded` and `assets_gen` are reserved at any depth (E-GEN-016).

## The deps package

When the app has a `deps/` package that declares `type Deps`, `pages.NewHandler` and every
`NewDP` take a `*deps.Deps`. Put there what pages share: the database, a file store, settings
read once, the hubs of live values. `main` makes it and passes its `Start` to `app.Main` as
`OnStart`, which runs once the runner is connected and before the app serves:

```go
func main() {
	d := deps.New()
	app.Main(app.Options{Handler: pages.NewHandler(d), OnStart: d.Start})
}
```

- `app.Main` takes only an `app.Options` literal written in its call, and `Handler` and `RPC`
  take only the calls of the generated `pages.NewHandler` and `rpc.Server`, written in that
  literal itself (E-LINT-004).
- `deps/` must not import anything under `pages/`, or the import cycle stops the build.
- A `dataprovider.go` written before `deps/` existed has a `NewDP()` without the argument, and
  the build fails with `too many arguments in call to NewDP` in `pages/handler_gen.go`. Delete
  that `dataprovider.go` while it holds no code of yours, such as the one `aicoded init` made, and
  run `aicoded generate`, which writes it again with the `*deps.Deps`.

## See also

- [Overview](overview.md): how the parts of an app work together.
- [Routing](routing.md): how folders become addresses.
- [The permission list](permission-list.md): what `aicoded.yaml` declares.
- [Calls between apps](calls-between-apps.md): `rpc/`, `services/` and `.aicoded/`.
- [people/deps/deps.go](https://github.com/AiCoded-Dev/framework/blob/f46741f7ef06688e8b1c606b047e7dbbb1b410c5/examples/people/deps/deps.go): the `Deps` of the people example.
