README
¶
aicoded framework
Open Go framework for building company web apps with AI assistants. Pages are rendered on the server from templates that compile to type-checked Go, and every page has an access rule. Building blocks give an app the viewer's identity, its own SQL database, file stores, mail, settings, secrets, telemetry and calls to other apps, with no password or key in the app. A CLI, a local runner and a local MCP server come with it; queues, schedules, outbound HTTP and a test kit come later.
Module: aicoded.dev/framework
Status: pre-release. No API is stable and nothing here is ready for use yet.
Quick start
You need Go 1.25 or later and Chrome. make install puts aicoded in $(go env GOPATH)/bin,
which must be on your PATH. In a checkout of this repository:
make install # installs aicoded from this checkout
aicoded init hello # creates the app hello in a new folder
cd hello
aicoded dev # runs it on your computer
Open http://hello.localhost:8080/ and switch test personas at
http://hello.localhost:8080/_aicoded/persona. aicoded dev also prints a login link to its dev
UI, where you start and stop the apps and read their logs, traces and caught mail.
The quick start guide goes on from there: what the new app holds, how to change its page and how to check it.
Docs
The docs live in docs/ and are built into aicoded: aicoded explain <topic> prints one
offline, and the howto tool of aicoded mcp gives the same pages to your AI assistant.
llms.txt lists them all.
- Guides, starting with the overview of how an app works:
- pages: the quick start, project structure, template syntax, expressions, routing, access, forms, live values, page calls, assets, the TypeScript API, the web API and the request pipeline;
- building blocks, calls and tools: the permission list, the SQL database, file stores, mail,
settings and secrets, telemetry, calls between apps,
aicoded dev, the tools, MCP and publishing.
- Error catalogue: every error code, with its fix.
- Examples: people, a staff directory; contacts, the app it calls; and room-maintenance, a list of tickets with an ownership check.
- Changelog for AI assistants: changes to the API, newest first.
Requirements
Go 1.25 or later. An app that keeps data in its SQL database needs a MySQL 8 server on your
computer to run under aicoded dev.
Checks
make tools # installs golangci-lint, govulncheck, gitleaks, buf and the protobuf plugins
make check # checks the generated protobuf code, in every module runs go test -race,
# golangci-lint run and govulncheck, and runs make secrets
- Tests that need MySQL read the admin DSN of a MySQL 8 server from
AICODED_TEST_MYSQL_DSNand skip without it;AICODED_E2E_MYSQL=requiredmakes them fail instead. The browser tests need Chrome, andAICODED_E2E_BROWSER=requiredmakes them fail without it. make docsrewritesllms.txtand the code the docs quote from the examples;go test ./docs/fails until both are current.make secretslooks for leaked passwords and keys with gitleaks and its default rules: in every commit reachable fromHEAD, and in every file git tracks or would track, so other branches, the stash and ignored folders are not scanned. An inlinegitleaks:allowhas no effect. A finding is fixed at its source; one that stays in an old commit is listed by its commit fingerprint,<commit>:<file>:<rule>:<line>, in.gitleaksignore, with a comment saying what it is.make secretsrefuses any other line in that file, and any file path with a colon.
License
Apache License 2.0 — see LICENSE.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package app runs an app under its runner.
|
Package app runs an app under its runner. |
|
Package auth tells who is viewing: the person the company login verified, whom the runner forwards with every request.
|
Package auth tells who is viewing: the person the company login verified, whom the runner forwards with every request. |
|
Package config reads the app's settings: named text values that the permission list declares and the runner supplies, such as the address of a team or the day a report goes out:
|
Package config reads the app's settings: named text values that the permission list declares and the runner supplies, such as the address of a team or the day a report goes out: |
|
Package docs holds the pages aicoded shows: the guides, the task recipes, the error catalogue and the changelog for agents.
|
Package docs holds the pages aicoded shows: the guides, the task recipes, the error catalogue and the changelog for agents. |
|
Package filestore reads and writes the app's file stores.
|
Package filestore reads and writes the app's file stores. |
|
internal
|
|
|
errs
Package errs formats coded errors: every "must not" in the framework is reported with a code, an optional file:line, a one-line fix and a link to its docs page.
|
Package errs formats coded errors: every "must not" in the framework is reported with a code, an optional file:line, a one-line fix and a link to its docs page. |
|
exporter
Package exporter batches spans and sends them to the runner without ever blocking the caller.
|
Package exporter batches spans and sends them to the runner without ever blocking the caller. |
|
identity
Package identity carries the verified viewer of a request in its context, with the viewer's token and, while serving a call from another app, that app.
|
Package identity carries the verified viewer of a request in its context, with the viewer's token and, while serving a call from another app, that app. |
|
logging
Package logging builds the framework's logger: JSON lines on the given writer, with the trace and span IDs of the context added at the top level of every record, also when the logger has groups.
|
Package logging builds the framework's logger: JSON lines on the given writer, with the trace and span IDs of the context added at the top level of every record, also when the logger has groups. |
|
redact
Package redact describes errors and panic values by their kinds and codes, never their text, for the logs and spans the framework records anywhere but under aicoded dev in environment `dev`.
|
Package redact describes errors and panic values by their kinds and codes, never their text, for the logs and spans the framework records anywhere but under aicoded dev in environment `dev`. |
|
runner
Package runner carries what the runner handed this app process, through contexts.
|
Package runner carries what the runner handed this app process, through contexts. |
|
tracectx
Package tracectx holds W3C trace context: it parses and formats traceparent headers and carries the current span in a context.
|
Package tracectx holds W3C trace context: it parses and formats traceparent headers and carries the current span in a context. |
|
viewerauth
Package viewerauth admits only requests that carry a valid viewer token from the runner.
|
Package viewerauth admits only requests that carry a valid viewer token from the runner. |
|
yamldoc
Package yamldoc reads the one YAML document of a permission list, and source lines out of YAML errors.
|
Package yamldoc reads the one YAML document of a permission list, and source lines out of YAML errors. |
|
Package lint holds the rules that aicoded check applies to an app's code after go vet, and that the delivery pipeline will apply too, such as which packages and names app code may use and which files an app may hold.
|
Package lint holds the rules that aicoded check applies to an app's code after go vet, and that the delivery pipeline will apply too, such as which packages and names app code may use and which files an app may hold. |
|
Package mailer sends the app's mail and reads its mailbox.
|
Package mailer sends the app's mail and reads its mailbox. |
|
Package manifest reads and checks aicoded.yaml, the app's permission list.
|
Package manifest reads and checks aicoded.yaml, the app's permission list. |
|
Package rpc lets one app call functions of another.
|
Package rpc lets one app call functions of another. |
|
wire
Package wire encodes and decodes the protobuf wire format for the code aicoded generate writes for calls between apps.
|
Package wire encodes and decodes the protobuf wire format for the code aicoded generate writes for calls between apps. |
|
Package runnerproto defines the protocol between an app and the runner that hosts it.
|
Package runnerproto defines the protocol between an app and the runner that hosts it. |
|
mailrules
Package mailrules holds the rules every message must follow before a runner sends it: the idempotency key, plain addresses, header fields without line breaks or control characters, the allowed headers, sizes, mailbox folders and the pages of a mailbox list.
|
Package mailrules holds the rules every message must follow before a runner sends it: the idempotency key, plain addresses, header fields without line breaks or control characters, the allowed headers, sizes, mailbox folders and the pages of a mailbox list. |
|
socket
Package socket connects apps and runners over Unix sockets using HTTP/2 without TLS.
|
Package socket connects apps and runners over Unix sockets using HTTP/2 without TLS. |
|
viewer
Package viewer signs and verifies the short-lived viewer tokens a runner attaches to every request it forwards to an app.
|
Package viewer signs and verifies the short-lived viewer tokens a runner attaches to every request it forwards to an app. |
|
Package secrets reads secret values that the runner holds for the app, such as a key to sign links with.
|
Package secrets reads secret values that the runner holds for the app, such as a key to sign links with. |
|
Package sqldb opens the app's SQL database, a MySQL database of its own.
|
Package sqldb opens the app's SQL database, a MySQL database of its own. |
|
Package telemetry records trace spans.
|
Package telemetry records trace spans. |
|
Package web serves an app's pages.
|
Package web serves an app's pages. |
|
form
Package form holds the typed fields of a page's forms.
|
Package form holds the typed fields of a page's forms. |
|
reactive
Package reactive carries live page values between the server and the browser over one WebSocket per page.
|
Package reactive carries live page values between the server and the browser over one WebSocket per page. |
|
reactive/client
Package client holds the browser side of live pages as TypeScript.
|
Package client holds the browser side of live pages as TypeScript. |
|
render
Package render writes template values into a page, each with the escaper of the HTML context it lands in.
|
Package render writes template values into a page, each with the escaper of the HTML context it lands in. |
Click to show internal directories.
Click to hide internal directories.