aicoded.dev

Overview: how an app works

An app is a Go module with a permission list, aicoded.yaml, and a main that calls app.Main. Its pages are HTML templates that aicoded generate turns into type-checked Go code. It runs under a runner, which signs in its viewers and gives it its building blocks.

The parts of an app

notes/
  go.mod
  aicoded.yaml     the permission list: what the app may reach, and who may open each page
  main.go          app.Main(app.Options{Handler: pages.NewHandler(d), OnStart: d.Start})
  deps/deps.go     optional: type Deps, what every page shares, such as the database
  pages/           the pages, one folder each
  rpc/             optional: the functions other apps may call

The pages folder

Each folder under pages/ that holds an index.html is a page at that path. A page with pages below it is their layout or their gate:

pages/
  index.html                  /                layout of every page: the nav and <ssr:content default="notes"/>
  notes/index.html            /notes           gate: the viewer's notes, each linking to its page
  notes/n_id/index.html       /notes/42        one note
  admin/index.html            /admin           layout of the admin pages: <ssr:content default="settings"/>
  admin/settings/index.html   /admin/settings

Generated files

aicoded dev and aicoded check run aicoded generate first. Never edit what it writes: change the templates, the permission list or the rpc/ package, and generate again.

File Written for What it holds
route_gen.go in a page's folder every page the page's rendering, the RouteData struct of its values, its form types, its live state, and the RouteDataProvider interface of its hooks
reactive_gen.ts in a page's folder a page with live values or page calls the typed ssr object that the page's index.ts imports
pages/handler_gen.go an app with pages NewHandler, which serves every page
pages/assets_gen.go, pages/assets_gen/ an app with pages the pages' scripts, styles and images, built and embedded in the app
rpc/server_gen.go, .aicoded/rpc.json an app that serves calls the server of its functions, and the snapshot of their types
services/<app>/client_gen.go an app that calls <app> the typed client of <app>'s functions
the access section of aicoded.yaml every app the access rules of every page
the services section of aicoded.yaml an app that calls or serves the calls the app makes and serves

aicoded generate also writes a dataprovider.go in a page folder that has none. That file is yours to edit. It implements every hook the template needs, and the hooks that guard something fail closed until you write them:

The stub holds var _ RouteDataProvider = &DP{}, so when a template needs a new hook, such as one for a new form, the Go compiler names the method that is missing.

What happens on a request

The runner forwards each request with a short-lived viewer token that it signs, and the app answers only requests that carry a valid one. Then the app's pages:

  1. Match the path folder by folder. A path that matches no page answers 404.
  2. Check the access rule of every page on the path, root first. A path with no rule is refused.
  3. Run the Guard of every page on the path that declares one, root first.
  4. For a POST, check the form token, and refuse a form without a valid one (403).
  5. Run Init<Form> for the forms of the layouts and the page, root first. For a POST, then run Process<Form> for the posted form, only when every field is valid.
  6. Run Data for each layout on the path and for the page, root first.
  7. Render the page into a buffer, and send it only when it renders whole.

So a check in a layout or a gate always runs before anything a page below it does. A page with live values or page calls also opens one live connection. It runs the same access rules and Guards first, and every page call runs them again.

Safe by default

The aicoded command

Command What it does
aicoded init <name> creates an app in a new folder
aicoded dev [dir] runs every app in the folder on a local runner, and rebuilds an app when its files change
aicoded generate [dir] writes the generated files of one app
aicoded check [dir] generates, builds, vets, lints and tests every app, and lists every problem with its fix
aicoded describe [dir] summarises what every app serves, calls and reaches, and its size
aicoded explain [topic] prints a page of the docs, such as this guide or the page of an error code, or lists them
aicoded rpc add <app> lets the app in this folder call the functions of <app>
aicoded mcp [dir] gives your AI assistant these tools over MCP
aicoded version prints the version of aicoded

Pages

Building blocks, calls and tools

Tasks

Recipes for common changes, with the code of the example apps:

Markdown · Source on GitHub · framework f46741f