Start a new app
Create an app with aicoded init, declare in its permission list what it reaches, open its
building blocks once in a deps package that every page shares, and run it under
aicoded dev. The code is that of the people example, a staff directory, and of contacts, an
app with no pages.
Steps
-
In the folder that holds your apps, run
aicoded init people. It makes the folderpeople/withgo.mod, the permission listaicoded.yaml,main.go, one page,pages/index.html,AGENTS.md, the rules for AI assistants that build the app, and a.gitignorethat keeps the draft of schema changes,.aicoded/migration.sql, out of git. It then runsaicoded generateandgo mod tidy. The name is 2 to 63 lowercase letters, digits and dashes, starting with a letter and ending with a letter or digit (E-CLI-002). -
Write in
aicoded.yamlwhat the app reaches. The finished people app has its own SQL database, a file store namedphotos, mail to its company's domain, and one setting, the team's address:app: people audience: internal: [everyone] data: - source: sqldb classes: [internal] - source: filestore:photos classes: [internal] email: from: people@acme.example to_domains: [acme.example] settings: [team_address] # access is written by aicoded generate from <ssr:access>; do not edit it access: "/contact": require: ["*"] "/home": require: ["*"] "/users/add": require: ["staff", "hr"] "/users/{login}/contacts": require: ["staff"] guard: true "/users/{login}/info": require: ["staff"] shared: true # services is written by aicoded generate from rpc/ and the clients in services/; do not edit it services: calls: "contacts": ["Contacts"]You write
app,data,email,settingsandsecrets, so copy only those sections.aicoded generatewrites theaccesssection from the pages and theservicessection from the calls between apps; never edit those two. When the person says who owns and uses the app, writeownerandaudiencetoo, as the permission list describes. -
Make
deps/deps.go, packagedeps, with a typeDepsfor what every page shares and aStartthat opens the building blocks before the app serves:// Deps is made by New and filled by Start before the app serves. type Deps struct { DB *sql.DB Photos *filestore.Store // TeamAddress is the setting team_address, where the app mails the team. TeamAddress string // HomePages has one subscription per open home page, and a signal whenever one opens or // closes. HomePages *reactive.Broadcast[struct{}] // UsersAdded signals that a user was added. UsersAdded *reactive.Broadcast[struct{}] // Seen records when each viewer last opened a page. Seen *LastSeen }// New returns Deps with its hubs. func New() *Deps { return &Deps{ HomePages: reactive.NewBroadcast[struct{}](), UsersAdded: reactive.NewBroadcast[struct{}](), Seen: NewLastSeen(), } }// Start opens the database and the photo store, fills the users table when it is empty and reads // the team's address. func (d *Deps) Start(ctx context.Context) error { db, err := sqldb.Open(ctx) if err != nil { return err } if err := fill(ctx, db); err != nil { return err } photos, err := filestore.Open(ctx, "photos") if err != nil { return err } team, err := config.String(ctx, "team_address") if err != nil { return err } d.DB, d.Photos, d.TeamAddress = db, photos, team return nil }fillcomes from List rows from the database, andLastSeenandNewLastSeenfrom Add a live value: leave them and the live hubs,HomePages,UsersAddedandSeen, out until you need them.Startcreates no table: the app's tables come from its draft of schema changes,.aicoded/migration.sql, whichaicoded devapplies before the app starts andaicoded publishsends with the commit. App code that changes the schema is refused (E-LINT-013). See Schema changes.There is no DSN and no password.
sqldb.Open,filestore.Openandconfig.Stringreach, through the runner, only what the permission list declares, and refuse anything else (E-MAN-010, E-MAN-011, E-MAN-001). -
In
main.go, passStarttoapp.MainasOnStart, and theDepsto the pages:// People is a staff directory: staff look up their colleagues, and hr adds new ones. package main import ( "aicoded.dev/framework/app" "people/deps" "people/pages" ) func main() { d := deps.New() app.Main(app.Options{Handler: pages.NewHandler(d), OnStart: d.Start}) } -
Once
depsdeclaresDeps, thepages.NewHandlerthataicoded generatewrites takes a*deps.Depsand passes it to theNewDPof every page. The page thataicoded initmade still hasNewDP(): deletepages/dataprovider.go, which holds no code of yours yet, and runaicoded generate, which writes it again with the*deps.Deps. -
Give
aicoded devthe local values indev.yaml, in your user configuration directory (~/.config/aicoded/dev.yamlon Linux,~/Library/Application Support/aicoded/dev.yamlon macOS), with mode 600. The workspace is the absolute path of the folder you runaicoded devin. An app withsqldbneeds the admin DSN of a MySQL 8 server on this machine, and every setting needs a test value:workspaces: /absolute/path/to/apps: mysql: root:<password>@unix(/run/mysqld/mysqld.sock)/ personas: - {name: alice, roles: [staff]} - {name: bob, roles: [staff, hr]} - {name: carol} apps: people: settings: {team_address: team@acme.example} -
Run
aicoded devin that folder and openhttp://people.localhost:8080/in Chrome. Switch personas athttp://people.localhost:8080/_aicoded/persona.
An app with no pages
contacts serves a function to people and has no pages. Its main passes only the generated
server of its rpc/ package, and its Start is a plain function:
// Contacts serves the phone numbers and email addresses of people to the people app.
package main
import (
"aicoded.dev/framework/app"
"contacts/deps"
"contacts/rpc"
)
func main() {
app.Main(app.Options{RPC: rpc.Server(), OnStart: deps.Start})
}
// Start opens the app's database and fills the contacts table when it is empty.
func Start(ctx context.Context) error {
conn, err := sqldb.Open(ctx)
if err != nil {
return err
}
if err := fill(ctx, conn); err != nil {
return err
}
db = conn
return nil
}
Its table, contacts, comes from its draft, .aicoded/migration.sql, as people's does. Its
permission list declares only its database. aicoded generate adds access: {} and the
function it serves:
app: contacts
audience:
internal: [everyone]
data:
- source: sqldb
classes: [internal]
# access is written by aicoded generate from <ssr:access>; do not edit it
access: {}
# services is written by aicoded generate from rpc/ and the clients in services/; do not edit it
services:
serves:
"Contacts":
callers: ["people"]
require: ["staff"]
Check it
aicoded checkin the folder that holds your apps generates, builds, vets, lints and tests every app, and ends withaicoded check: ok. Each problem comes with its code,file:lineand fix.aicoded devprints a login link to its dev UI. Its Apps page shows peoplerunning, orfailedwith its problems: withoutteam_addressindev.yaml, people fails with E-DEV-003.