# aicoded framework > The open Go framework for company web apps that AI assistants build: type-checked server-rendered pages, building blocks for data, files and mail, and calls between apps, each app held to what its permission list allows. Start with the overview. `aicoded explain ` and the `howto` tool of `aicoded mcp` serve the same pages offline. ## Guides - [Access: rules, Guards and the order of checks](https://aicoded.dev/docs/guides/access.md): Every page is closed until an access rule on its path opens it. Access rules check the viewer's roles; a Guard checks what only the data can tell, such as who owns a record. Both run, root first, before anything else a page does. A page with an id in its URL also says whose records it shows. - [App types: what needs approval and what does not](https://aicoded.dev/docs/guides/app-types.md): Security approves what a kind of app may do, not each app's code. It does that with app types: an app type says who its apps may serve, the data they may hold, where their mail may go and which outside services they may call. When a publish passes the security checks, the platform compares the app's permission list with its app type and decides whether the release is *Pre-approved*, *Needs approval* or *Not allowed*. This guide covers app types, that decision, the group map, the source registry, and what `aicoded publish` shows. - [Scripts, styles and images](https://aicoded.dev/docs/guides/assets.md): A page's script is `index.ts` and its styles `index.css`, next to its template. `aicoded generate` builds them with esbuild, which is built into `aicoded`, copies the page's images, and embeds everything in the app, so there is no Node.js, npm or `node_modules` and no build step of your own. - [Calls between apps](https://aicoded.dev/docs/guides/calls-between-apps.md): An app can call Go functions of another app as if they were its own. The called app declares who may call each function; `aicoded generate` writes the code on both sides; and the runner carries each call, checks it against the permission lists of both apps, and passes the viewer on. - [aicoded dev: run apps on your computer](https://aicoded.dev/docs/guides/dev.md): `aicoded dev` is the runner on your computer. It generates, builds and starts every app in a folder, signs viewers in as test personas, gives the apps their database, file stores, caught mail and outside services, rebuilds an app when its files change, and serves a dev UI with the apps' logs, traces and mail. - [Expressions: the `{{ }}` language](https://aicoded.dev/docs/guides/expressions.md): Expressions are compiled to Go, not interpreted: what you write between the braces becomes a Go expression in the page's generated code, so the Go compiler checks its names and types. Each value is escaped for the place in the page where it lands. - [File stores](https://aicoded.dev/docs/guides/file-stores.md): A file store keeps the app's files, such as uploaded photos or documents. `filestore.Open(ctx, "photos")` returns the store the permission list declares as `filestore:photos`; the runner keeps the files, a store holds only this app's files, and no name can lead out of it. - [Forms](https://aicoded.dev/docs/guides/forms.md): A form is a plain HTML form that posts to its own page. The generated code reads each field into its Go type, checks required fields and select options, and checks the form token; you write two hooks, one that prepares the form and one that acts on it once every field is valid. - [Live values](https://aicoded.dev/docs/guides/live-values.md): A live value is rendered on the server like any other, then rendered again and sent to the open page whenever it changes, over the page's one live connection. The browser gets text or escaped markup, never a template, and an input can write a value back through a check you write. - [Mail](https://aicoded.dev/docs/guides/mail.md): `mailer.Send` sends a message from the app's one address to the domains its permission list allows, and `mailer.List` and `mailer.Get` read the app's mailbox. The runner checks every message against the mail rules, and every message carries an idempotency key, so a retried request does not mail again while the runner remembers the key: on the platform, the app's last 10 000 keys within 24 hours. - [MCP: the tools for your AI assistant](https://aicoded.dev/docs/guides/mcp.md): `aicoded mcp` gives your AI assistant the tools of `aicoded` over MCP: it creates apps, checks them, previews them in `aicoded dev`, reads what went wrong, publishes them, runs their previews on the platform, releases a publish held for preview, reads their logs and traces there, and reads these docs offline. No tool runs a shell command or takes a file path, and nothing a tool returns of `aicoded dev` holds a secret value. - [Outside services](https://aicoded.dev/docs/guides/outbound.md): `outbound.Client()` returns the `*http.Client` an app calls outside services with. Every request goes to the runner, which sends it only to a host that `egress` in the permission list names, over HTTPS, adds the key bound to that host, and bounds its size and time. The key never reaches the app's code. - [Overview: how an app works](https://aicoded.dev/docs/guides/overview.md): 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. - [Page calls: functions a page's script calls](https://aicoded.dev/docs/guides/page-calls.md): A page call lets the page's script ask its server for something without a reload or a separate API. The page declares the call with typed arguments and result, the data provider answers it, and the access rules and Guards of the page run again before every call. - [The permission list: aicoded.yaml](https://aicoded.dev/docs/guides/permission-list.md): `aicoded.yaml` declares who owns and uses the app and everything it reaches: its data, the outside services it calls, the address it mails from and the domains it mails to, its scheduled jobs, its settings and secrets, who may open each page, and the functions it calls and serves. Security reads it instead of the code, and the app itself never holds a password or a key. - [Project structure: the files of an app](https://aicoded.dev/docs/guides/project-structure.md): 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. - [Publishing: sending an app to the platform](https://aicoded.dev/docs/guides/publishing.md): `aicoded publish` sends a commit of an app to the platform's delivery pipeline, which checks it and writes a change record for it, and `aicoded status` shows the outcome. This guide covers signing in, the clean commit, what is sent, the waiting, reading the outcome, what the delivery pipeline checks, the preview every publish is held for until you ask for its release, publishing straight to production, and the codes. - [Quick start: create and run an app](https://aicoded.dev/docs/guides/quickstart.md): Install `aicoded`, create an app with one page, run it on your computer as a test persona, and change the page. You need Go and Chrome; there is no Node.js or npm to install. - [The request pipeline: what runs where](https://aicoded.dev/docs/guides/request-pipeline.md): A page talks to its server in four ways: the page loads, a form posts, the live connection opens and a script makes a page call. Each passes the runner first, then the same checks in the same order. This guide shows what runs for each, and what runs in the browser. - [Routing: folders, layouts, gates and parameters](https://aicoded.dev/docs/guides/routing.md): The addresses of an app are the folders under `pages/`: there is no route table. A folder can capture part of the URL, a page with pages below it is their layout or their gate, and a hook ends a request with an error page or a redirect by returning an error. - [Rules for app code](https://aicoded.dev/docs/guides/rules.md): The rules that `aicoded check` holds app code to: what an app must not do, what it does instead, and the error code of each rule. Lint runs once an app builds and passes `go vet`, and nothing in the code turns a finding off. - [Schema changes: the draft and the app's migrations](https://aicoded.dev/docs/guides/schema-changes.md): An app's tables come from its schema changes, never from its code: write the next change in the draft `.aicoded/migration.sql`, and `aicoded publish` sends it with the commit. - [Settings and secrets](https://aicoded.dev/docs/guides/settings-and-secrets.md): Settings are named values the app is configured with, such as the address of a team; secrets are values nobody may see, such as an API key. The permission list names both, the runner holds their values, and the app reads them with `config.String` and `secrets.Get`. - [Simulated attacks: how the delivery pipeline tests the running app](https://aicoded.dev/docs/guides/simulated-attacks.md): Once an app's tests pass, the delivery pipeline starts the program it built and attacks it, as the security checks of layer L7: requests without a session or without a role, another viewer who tries to see or change records that are not theirs, markup in every field, and a search of the app's log and telemetry for what people entered. This guide says how the app runs, who the test viewers are, what each attack does, what fails a publish and what is only a note, how to let the attacks reach every page, and what they cannot know. - [The SQL database](https://aicoded.dev/docs/guides/sql-database.md): `sqldb.Open(ctx)` returns the app's own MySQL database as a `*sql.DB`. There is no DSN and no password: the app talks to its runner, which logs in to the database as the app's own user, whose grants reach only the app's database. - [Telemetry: logs and traces](https://aicoded.dev/docs/guides/telemetry.md): An app logs with Go's `log/slog` and records trace spans with `telemetry.Start`. The framework already records a span for every request, statement, file, mail and call, and ties each log line to its trace. None of it may hold personal data. - [Template syntax: tags and attributes](https://aicoded.dev/docs/guides/template-syntax.md): A page's `index.html` is HTML with `ssr:` tags, `ssr:` attributes and `{{ }}` expressions. `aicoded generate` turns it into Go code, checks it, and refuses anything that could run code in the browser or write a value where escaping cannot make it safe. - [Tools: the aicoded commands](https://aicoded.dev/docs/guides/tools.md): `aicoded` creates apps, generates their code, checks them, describes them, explains its errors and docs, connects apps that call each other, signs you in to the platform, publishes apps to it and runs their previews there. Every problem it reports has a code, a `file:line` where there is one, a one-line fix and a docs link. - [TypeScript API: the ssr object](https://aicoded.dev/docs/guides/typescript-api.md): Live values and page calls work without any script. Write one in `index.ts` when a page needs more: showing why a value was refused, reacting to a lost connection, calling a page call, or writing a value that no input holds. The page's generated `reactive_gen.ts` gives the script a typed `ssr` object. - [The web API: what a data provider uses](https://aicoded.dev/docs/guides/web-api.md): A page's data provider uses a small part of three packages: `web` for the request, errors, redirects and safe markup, `web/form` for form fields, and `web/reactive` for the hubs that wake live pages. The rest of these packages is there for the generated code. ## Tasks - [Add a form](https://aicoded.dev/docs/tasks/add-form.md): Add a form whose values the server checks before the page acts on them. The example is the contact form of the people example, at `/contact`: it mails the team, then shows a banner. - [Add a live value](https://aicoded.dev/docs/tasks/add-live-value.md): Show a value that changes while the page is open, without reloading it, and let the page send back a value that the server checks. The examples are from the people example: how many users there are, when a user last opened a page, how many home pages are open, and the display name that the home page writes. - [Add a page](https://aicoded.dev/docs/tasks/add-page.md): Add a page to an app: a folder under `pages/` with a template that declares its values, an access rule on its path, and a data provider that fills the values. The example is the info tab of a user's card in the people example, at `/users//info`. - [Call an outside service](https://aicoded.dev/docs/tasks/call-an-outside-service.md): Call a service on the internet over HTTPS, with a key the runner adds so that the app never reads it. The example asks a weather service for a city's weather, from a method of the app's `Deps`. - [Call another app](https://aicoded.dev/docs/tasks/call-another-app.md): Let one app call Go functions of another, on behalf of the viewer, with the runner and both apps checking each call. The example is the contacts tab of the people example, which asks the contacts app for a user's phones and emails. - [Send mail after a write](https://aicoded.dev/docs/tasks/email-after-a-write.md): Mail someone once a change is saved, and only once: commit the change first, then send the mail with an idempotency key that names what it is about. The example adds a user in the people example and mails the team. - [Find why a published app fails](https://aicoded.dev/docs/tasks/find-why-a-published-app-fails.md): Read a published app's logs and traces on the platform with `aicoded logs` and `aicoded traces`, or the `logs`, `traces` and `trace` tools of `aicoded mcp`, follow a failed request through its trace, and fix the code. Read production only when the developer asks: its logs hold what the app logged while people used it. - [List own records, or all of them for a role](https://aicoded.dev/docs/tasks/list-by-role.md): Show each viewer only the records they own, and a viewer with a role every record, with SQL that stays a constant: one statement for each case, chosen in Go. The example is the list of tickets in the room-maintenance example, at `/tickets`: an employee sees the tickets they reported, and `hotel-ops` see every ticket. - [List rows from the database](https://aicoded.dev/docs/tasks/list-from-database.md): Show a list read from the app's own SQL database. The example is the list of users in the people example, at `/users`: its `deps` package holds the table and the queries, and the page shows the rows. - [Start a new app](https://aicoded.dev/docs/tasks/new-app.md): 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. - [Check who owns a record](https://aicoded.dev/docs/tasks/ownership-check.md): Let a viewer open only their own records, and a viewer with a stronger role anyone's. The access rule admits the role, a `Guard` on the page checks the owner, and the app that holds the data checks again. The example is the contacts tab of a user in the people example, at `/users//contacts`, whose data the contacts app holds. - [Take a file upload](https://aicoded.dev/docs/tasks/upload-a-file.md): Take files in a form, check them, and keep them in a file store. The example is the photos of a new user in the people example, which it keeps in its store `photos` as `/`. ## Errors - [Error catalogue](https://aicoded.dev/docs/errors/README.md): Every error the framework, the generator, the CLI or a runner reports on purpose has a code `E--`, a one-line fix and a page here named after the code. ## Optional - [Changelog for AI assistants](https://aicoded.dev/docs/changelog-agents.md): Changes to the API that AI assistants build apps with. Newest first. - [Examples](https://github.com/AiCoded-Dev/framework/blob/f46741f7ef06688e8b1c606b047e7dbbb1b410c5/examples/README.md): Three reference apps built with the framework: people, a staff directory with pages; contacts, which serves people's phone numbers and email addresses to it; and room-maintenance, where hotel staff report problems in rooms, each of them sees only their own tickets, and hotel-ops see all. - [Room maintenance](https://github.com/AiCoded-Dev/framework/blob/f46741f7ef06688e8b1c606b047e7dbbb1b410c5/examples/room-maintenance/README.md): The reference app for records with an owner: hotel staff report problems in rooms, each of them sees and edits only their own tickets, and hotel-ops see every ticket and change its status, which shows at once in every open list that holds the ticket.