aicoded.dev

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

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
.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 lists what each one holds.

A page's folder

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.

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:

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

See also

Markdown · Source on GitHub · framework f46741f