AppKit reference

Create one AppKit instance per platform app. It binds service calls to the app's slug and supplies the router mounted by the platform.

from at import AppKit
kit = AppKit(__name__)
router = kit.router

Interfaces

Interface	Responsibility	Important behavior
`kit.router`	App HTTP routes	Define routes under `/api/…`; the app prefix is added automatically
`kit.store`	PostgreSQL JSON documents	App-scoped; use `for_owner(user.id)` for private records
`kit.kv`	Optional DynamoDB documents	Explicit owner binding; create-only or compare-and-swap writes
`kit.files`	S3 objects and upload primitives	Bind the owner; large media bytes stay out of SQL
`kit.enable_files()`	Shared HTTP file workflow	Installs authenticated upload, list, download, and delete routes
`kit.auth`	Verified human identity	`require(request)` rejects unauthenticated callers
`kit.ai`	Model calls and usage accounting	Uses the shared model catalog and request settings
`kit.jobs`	Background work	Bind an owner for private job status and cancellation
`kit.config`	App-scoped SSM settings	Read secrets without embedding values in code or manifests
`kit.track`	App analytics	Records events with the app namespace
`kit.data_dir`	Local app files	Persistent on this VM, but not a multi-instance object store
`kit.on_startup` / `kit.on_shutdown`	Lifecycle hooks	App-specific initialization and cleanup

Ownership

user = await kit.auth.require(request)
store = kit.store.for_owner(user.id)
files = kit.files.for_owner(user.id)
jobs = kit.jobs.for_owner(user.id)
kv = kit.kv.for_owner(user.id)

Use the identity returned by the authentication helper. A client must not choose another user's owner ID. App-scoped calls without an owner are for deliberate app-wide state; they do not automatically authorize access to private records.

Routing and manifests

The manifest supplies name, path, access, requires, required_env, and required_secrets. Frontend routing can be a single-page app or static multi-page site (spa = false).

/admin, /_at, and /health belong to the platform. An app cannot claim those prefixes. The documentation app uses server-rendered pages for stable links; ordinary interactive apps use the frontend convention.

Lifecycle and concurrency

Startup hooks run after the platform database is ready, for apps that are live. Shutdown hooks should cancel local tasks and close resources.

A hook is not a distributed scheduler. If the same app is started in multiple processes, the hook can run more than once. Use durable jobs or an explicit lease when work must have one owner.

Error handling

Surface authorization errors as 401/403, missing owned resources as 404, stale DynamoDB writes as 409, and admission limits as an appropriate application error. Never return secret values or raw connection strings in errors.

Every shared-platform HTTP response normally includes an X-Request-ID. Use that ID when correlating a reported problem with server logs.

The repository platform reference contains implementation-level details. The public guides separate storage, identity, AI and jobs, and operations.