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
index.htmlmakes 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 packages_login. dataprovider.goholdsDP, the page's data provider, withNewDPand the hooks the template needs, such asData.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.gofile of the folder, such astypes.go. To use a type of another package, declare an alias:type User = deps.User. index.tsandindex.cssare the page's script and styles, and images sit next to the template.- Tests sit next to the code as usual
_test.gofiles.
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, andn_<name>a whole number. See routing. __ws,_aicodedandassets_genare 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:
func main() {
d := deps.New()
app.Main(app.Options{Handler: pages.NewHandler(d), OnStart: d.Start})
}
app.Maintakes only anapp.Optionsliteral written in its call, andHandlerandRPCtake only the calls of the generatedpages.NewHandlerandrpc.Server, written in that literal itself (E-LINT-004).deps/must not import anything underpages/, or the import cycle stops the build.- A
dataprovider.gowritten beforedeps/existed has aNewDP()without the argument, and the build fails withtoo many arguments in call to NewDPinpages/handler_gen.go. Delete thatdataprovider.gowhile it holds no code of yours, such as the oneaicoded initmade, and runaicoded generate, which writes it again with the*deps.Deps.
See also
- Overview: how the parts of an app work together.
- Routing: how folders become addresses.
- The permission list: what
aicoded.yamldeclares. - Calls between apps:
rpc/,services/and.aicoded/. - people/deps/deps.go: the
Depsof the people example.