# db3.ai Framework

> Typed application framework documentation for @db3.ai/app 0.1.0, generated from the public documentation registry, package-owned source, executable examples, and behavioural tests.

Use these documents as the canonical learning context for the db3.ai Framework.

Learn APIs from public package subpaths and exported TypeScript contracts. Learn behaviour from executable framework-owned examples, their deterministic output, and the tests that execute them. Do not invent methods from prose or rely on source-relative internal imports.

## Recommended learning order
1. Read the introduction, installation, and first-application guides.
2. Read the service page for the capability being used.
3. Confirm names and payloads against the typed public API pages.
4. Follow verified examples and their behavioural tests for runtime semantics, failures, retries, and cleanup.
5. Use the complete context export only when broad framework knowledge is required.

## Complete learning context
- [llms-full.txt](https://db3.ai/llms-full.txt): Combined Markdown for every registered framework article, publish-shaped declaration entry points, exact selected behavioural tests, code examples, and deterministic output.

## Start
Install the framework and build a first application.
- [Build an app with db3.ai](https://db3.ai/docs/welcome.md): A TypeScript application framework for getting useful features built: models, authentication, files, background work and server-side AI. Public import: `@db3.ai/app`.
- [Install the framework](https://db3.ai/docs/installation.md): Install one runtime package, then build a small HTTP app. Add a database and other services when your feature needs them. Public import: `@db3.ai/app`.
- [Build your first app](https://db3.ai/docs/starter-app.md): Create an account, save a private note and summarise it with AI. Start with working application code you can change. Public import: `@db3.ai/create`.
- [Create your first app](https://db3.ai/docs/create-app.md): Start an HTTP server, return a JSON response, reject invalid input and test it without opening a port. Public import: `@db3.ai/app/server`.
- [Configure the application runtime](https://db3.ai/docs/app-config.md): Keep application settings explicit. Boot one App, give each service its options and leave HTTP and worker startup to the host. Public import: `@db3.ai/app/server`.
- [Your application structure](https://db3.ai/docs/project-structure.md): Keep the generated app independent. Add product code and tests in your app; import shared services from the framework package. Public import: `@db3.ai/app`.

## Guides
Follow complete workflows from request to result.
- [Keep one workspace’s notes separate from another’s](https://db3.ai/docs/guide-workspace-notes.md): Run a small database workflow: create a note, protect ownership, list the right records, reject invalid input and roll back a failed write. Public import: `@db3.ai/app/db`.
- [Build an owned-note JSON API](https://db3.ai/docs/guide-api.md): Keep HTTP validation, field conversion and authorization at their own boundaries. Use the starter’s real note routes as the example. Public import: `@db3.ai/create`.
- [Take a note from input to stored data](https://db3.ai/docs/guide-model-data.md): Choose fields, protect ownership, persist the model and return its public shape. Public import: `@db3.ai/app/db`.
- [Move a report out of the request](https://db3.ai/docs/guide-background.md): Accept the work quickly, persist its identity and let a registered worker produce the result. Keep access and progress in the application. Public import: `@db3.ai/app/queue`.
- [Upload and download private files](https://db3.ai/docs/guide-files.md): A file ID is not permission to read it. Start with a small, authenticated text-file endpoint and keep the policy visible. Public import: `@db3.ai/app/media`.
- [Trace login from browser to database](https://db3.ai/docs/guide-auth.md): Use the starter’s existing login, then understand the session boundary before adding another provider. Public import: `@db3.ai/create`.
- [Test an application workflow across services](https://db3.ai/docs/guide-testing.md): Use private file access to test authentication, persistence, validation and cleanup together. Public import: `@db3.ai/app/media`.

## Services
Explore every reusable framework service.
- [App](https://db3.ai/docs/app.md): Create one application at boot. Configure its services, use request-local state and close the resources you own. Public import: `@db3.ai/app/server`.
- [Configuration](https://db3.ai/docs/config.md): Read settings once at boot. Parse environment values, validate the bits your application needs and pass them into the services that use them. Public import: `@db3.ai/app/config`.
- [Validate application input](https://db3.ai/docs/validation.md): Check a note request, return useful field errors and make the boundary between validation, conversion and authorization explicit. Public import: `@db3.ai/app/validation`.
- [ActiveRecord](https://db3.ai/docs/active-record.md): Define your fields once. Create, validate, query and save records without repeating database conversion in every endpoint. Public import: `@db3.ai/app/db`.
- [Keep conversion in the field](https://db3.ai/docs/fields.md): Define a reusable value once, from input and validation through storage and public output. Public import: `@db3.ai/app/db`.
- [Query with logical fields](https://db3.ai/docs/queries.md): Scope private data, select what you need and keep the database work visible. Public import: `@db3.ai/app/db`.
- [Change the schema without losing the data](https://db3.ai/docs/migrations.md): Generate a reviewable migration, apply it and check that models, files and the database agree. Public import: `@db3.ai/app/db/migrations`.
- [Auth](https://db3.ai/docs/auth.md): Give an account one or more login methods. Issue bearer sessions, reset passwords and revoke access without mixing identity with credentials. Public import: `@db3.ai/app/auth`.
- [Cache an expensive lookup](https://db3.ai/docs/cache.md): Cache a note summary, keep account keys separate and invalidate it after a write. Public import: `@db3.ai/app/cache`.
- [React to a saved note](https://db3.ai/docs/events.md): Use typed, in-process events for small reactions while keeping delivery and failure behavior visible. Public import: `@db3.ai/app/events`.
- [Queue](https://db3.ai/docs/queue-overview.md): Create durable background jobs, run named workers, understand every attempt, compose chains and batches, and recover failures through one complete service guide. Public import: `@db3.ai/app/queue`.
- [Scheduler](https://db3.ai/docs/scheduler.md): Decide when a daily task is due, claim its occurrence and hand expensive work to Queue. Inspect what happened without hiding schedule definitions in a database. Public import: `@db3.ai/app/scheduler`.
- [Run a durable flow](https://db3.ai/docs/flows.md): Use a flow when the steps, values and replay history matter. Start with a small sequential graph, not an arbitrary execution engine. Public import: `@db3.ai/app/flows`.
- [Storage](https://db3.ai/docs/storage.md): Write files to a named disk, stream large payloads and keep paths relative to storage. Add Media when files need durable identities and ownership metadata. Public import: `@db3.ai/app/storage`.
- [Media](https://db3.ai/docs/media.md): Give files durable IDs and project-scoped libraries. Keep storage paths, browser folders and permission checks separate. Public import: `@db3.ai/app/media`.
- [Mail](https://db3.ai/docs/mail.md): Build and preview an application email locally, then select a transport when you are ready to send it. Public import: `@db3.ai/app/mail`.
- [Write useful, safe logs](https://db3.ai/docs/logging.md): Record what happened with enough context to investigate it, without copying secrets into your logs. Public import: `@db3.ai/app/logging`.
- [Encrypt a secret you need to read later](https://db3.ai/docs/security.md): Keep reversible secrets encrypted with an application-owned key and explicit ownership context. Public import: `@db3.ai/app/security`.
- [Application URLs](https://db3.ai/docs/url.md): Give email, workers and HTTP routes one trusted application address. A URL resolver is not a redirect policy. Public import: `@db3.ai/app/url`.
- [Restore durable application objects](https://db3.ai/docs/serialization.md): Save the state needed to call one registered constructor again. Keep services and connections out of the payload. Public import: `@db3.ai/app/serialization`.
- [Render public HTML](https://db3.ai/docs/ssr.md): SSR owns the document and request boundary. Your application owns the pages, router, data and client hydration. Public import: `@db3.ai/app/ssr`.
- [Add a bounded AI text feature](https://db3.ai/docs/ai.md): Start with one useful task: summarise an owned note. Keep the key, permissions and limits on the server. Public import: `@db3.ai/app/ai`.
- [Test the feature a developer will use](https://db3.ai/docs/testing.md): Run real framework components through their public boundary. Make failure, recovery and cleanup part of the test. Public import: `@db3.ai/app`.
- [Find a public contract](https://db3.ai/docs/api-reference.md): Start with a working guide. Use the emitted TypeScript reference when you need an option, method or return type. Public import: `@db3.ai/app`.

## Cookbook
Solve common application and operations problems.
- [Solve a problem](https://db3.ai/docs/solve-a-problem.md): Start with the feature you need. Follow one workflow across the services it uses. Public import: `@db3.ai/app`.
- [Save related records together or not at all](https://db3.ai/docs/cookbook-transactions.md): Use the active database transaction without adding database parameters to every model and feature function. Public import: `@db3.ai/app/db`.
- [Retry later without using an attempt](https://db3.ai/docs/cookbook-retries.md): A busy provider is not always a broken job. Defer deliberately, but give the work a deadline so it cannot wait forever. Public import: `@db3.ai/app/queue`.
- [Stream an export and clean up failure](https://db3.ai/docs/cookbook-streams.md): Write incrementally, publish only a completed file, and leave the last successful export available when generation fails. Public import: `@db3.ai/app/storage`.
- [Store an integration secret safely](https://db3.ai/docs/cookbook-secrets.md): Persist an encrypted model value, load it only in authorized server code and keep it out of public JSON. Public import: `@db3.ai/app/db`.

## Examples
Inspect tested, source-backed framework examples.
- [Build and operate queued work](https://db3.ai/docs/example-queue.md): Follow the complete imported Queue example set: define durable data, register and process a job, compose chains and batches, configure retry policy, defer backpressure, and replay terminal failures. Public import: `@db3.ai/app/queue`.

## API
Browse package contracts and public exports.
- [@db3.ai/app](https://db3.ai/docs/package-app.md): The backend runtime: application services, field-aware records, durable work and optional web delivery. Public import: `@db3.ai/app`.
- [@db3.ai/pure](https://db3.ai/docs/package-pure.md): Small portable helpers for ordinary application data. They do not create an App or replace validation and authorization. Public import: `@db3.ai/pure`.
- [App API reference](https://db3.ai/docs/app-api.md): Current emitted signatures and options for @db3.ai/app/server. Public import: `@db3.ai/app/server`.
- [AI text API reference](https://db3.ai/docs/ai-api.md): Current emitted signatures and options for @db3.ai/app/ai. Public import: `@db3.ai/app/ai`.
- [ActiveRecord API reference](https://db3.ai/docs/active-record-api.md): Look up record, query and field methods, options and return types. Start with the guide for the normal workflow. Public import: `@db3.ai/app`.
- [Queue API reference](https://db3.ai/docs/queue-api.md): Current emitted Queue contracts: options, job payloads, attempts, retries, workers, drivers and console integration. Public import: `@db3.ai/app/queue`.
- [Config API reference](https://db3.ai/docs/config-api.md): Current emitted signatures and options for @db3.ai/app/config. Public import: `@db3.ai/app/config`.
- [Mail API reference](https://db3.ai/docs/mail-api.md): Current emitted signatures and options for @db3.ai/app/mail. Public import: `@db3.ai/app/mail`.
- [Validation API reference](https://db3.ai/docs/validation-api.md): Current emitted signatures and options for @db3.ai/app/validation. Public import: `@db3.ai/app/validation`.
- [Cache API reference](https://db3.ai/docs/cache-api.md): Current emitted signatures and options for @db3.ai/app/cache. Public import: `@db3.ai/app/cache`.
- [Events API reference](https://db3.ai/docs/events-api.md): Current emitted signatures and options for @db3.ai/app/events. Public import: `@db3.ai/app/events`.
- [Logging API reference](https://db3.ai/docs/logging-api.md): Current emitted signatures and options for @db3.ai/app/logging. Public import: `@db3.ai/app/logging`.
- [Security API reference](https://db3.ai/docs/security-api.md): Current emitted signatures and options for @db3.ai/app/security. Public import: `@db3.ai/app/security`.
- [Fields API reference](https://db3.ai/docs/fields-api.md): Current emitted signatures and options for @db3.ai/app/db. Public import: `@db3.ai/app/db`.
- [Migrations API reference](https://db3.ai/docs/migrations-api.md): Current emitted signatures and options for @db3.ai/app/db/migrations. Public import: `@db3.ai/app/db/migrations`.
- [Storage API reference](https://db3.ai/docs/storage-api.md): Current emitted signatures and options for @db3.ai/app/storage. Public import: `@db3.ai/app/storage`.
- [Media API reference](https://db3.ai/docs/media-api.md): Current emitted signatures and options for @db3.ai/app/media. Public import: `@db3.ai/app/media`.
- [URL API reference](https://db3.ai/docs/url-api.md): Current emitted signatures and options for @db3.ai/app/url. Public import: `@db3.ai/app/url`.
- [Serialization API reference](https://db3.ai/docs/serialization-api.md): Current emitted signatures and options for @db3.ai/app/serialization. Public import: `@db3.ai/app/serialization`.
- [SSR API reference](https://db3.ai/docs/ssr-api.md): Current emitted signatures and options for @db3.ai/app/ssr. Public import: `@db3.ai/app/ssr`.
- [Flows API reference](https://db3.ai/docs/flows-api.md): Current emitted signatures and options for @db3.ai/app/flows. Public import: `@db3.ai/app/flows`.
- [Scheduler API reference](https://db3.ai/docs/scheduler-api.md): Current emitted signatures and options for @db3.ai/app/scheduler. Public import: `@db3.ai/app/scheduler`.
- [Auth API reference](https://db3.ai/docs/auth-api.md): Current emitted signatures and options for @db3.ai/app/auth. Public import: `@db3.ai/app/auth`.

## Executable evidence
Prefer these pages when learning runtime behaviour because their displayed examples are tied to framework-owned tests.
- [Build your first app](https://db3.ai/docs/starter-app.md): behavioural evidence in `packages/create/template/tests/app.test.ts`.
- [Create your first app](https://db3.ai/docs/create-app.md): behavioural evidence in `packages/app/src/server/tests/examples/firstApplication.test.ts`.
- [Your application structure](https://db3.ai/docs/project-structure.md): behavioural evidence in `packages/app/src/queue/tests/examples/createAndProcessReportJob.test.ts`.
- [Keep one workspace’s notes separate from another’s](https://db3.ai/docs/guide-workspace-notes.md): behavioural evidence in `packages/app/src/db/tests/examples/workspaceNotes.test.ts`.
- [Build an owned-note JSON API](https://db3.ai/docs/guide-api.md): behavioural evidence in `packages/create/template/tests/app.test.ts`.
- [Take a note from input to stored data](https://db3.ai/docs/guide-model-data.md): behavioural evidence in `packages/app/src/db/tests/examples/workspaceNotes.test.ts`.
- [Move a report out of the request](https://db3.ai/docs/guide-background.md): behavioural evidence in `packages/app/src/queue/tests/examples/runQueueReports.test.ts`.
- [Upload and download private files](https://db3.ai/docs/guide-files.md): behavioural evidence in `packages/app/src/media/tests/examples/runPrivateFiles.test.ts`.
- [Trace login from browser to database](https://db3.ai/docs/guide-auth.md): behavioural evidence in `packages/create/template/tests/app.test.ts`.
- [Test an application workflow across services](https://db3.ai/docs/guide-testing.md): behavioural evidence in `packages/app/src/media/tests/examples/runPrivateFiles.test.ts`.
- [Configuration](https://db3.ai/docs/config.md): behavioural evidence in `packages/app/src/config/tests/examples/runConfig.test.ts`.
- [Validate application input](https://db3.ai/docs/validation.md): behavioural evidence in `packages/app/src/validation/tests/examples/runNoteValidation.test.ts`.
- [ActiveRecord](https://db3.ai/docs/active-record.md): behavioural evidence in `packages/app/src/db/tests/examples/workspaceNotes.test.ts`.
- [Keep conversion in the field](https://db3.ai/docs/fields.md): behavioural evidence in `packages/app/src/db/tests/examples/runFieldNotes.test.ts`.
- [Query with logical fields](https://db3.ai/docs/queries.md): behavioural evidence in `packages/app/src/db/tests/examples/runFieldNotes.test.ts`.
- [Change the schema without losing the data](https://db3.ai/docs/migrations.md): behavioural evidence in `packages/app/src/db/tests/examples/runNoteMigrations.test.ts`.
- [Auth](https://db3.ai/docs/auth.md): behavioural evidence in `packages/app/src/auth/tests/examples/runPasswordAuth.test.ts`.
- [Cache an expensive lookup](https://db3.ai/docs/cache.md): behavioural evidence in `packages/app/src/cache/tests/examples/runNoteCache.test.ts`.
- [React to a saved note](https://db3.ai/docs/events.md): behavioural evidence in `packages/app/src/events/tests/examples/runNoteEvents.test.ts`.
- [Queue](https://db3.ai/docs/queue-overview.md): behavioural evidence in `packages/app/src/queue/tests/examples/runQueueReports.test.ts`.
- [Scheduler](https://db3.ai/docs/scheduler.md): behavioural evidence in `packages/app/src/scheduler/tests/examples/runDailySummary.test.ts`.
- [Run a durable flow](https://db3.ai/docs/flows.md): behavioural evidence in `packages/app/src/flows/tests/examples/runTextFlow.test.ts`.
- [Storage](https://db3.ai/docs/storage.md): behavioural evidence in `packages/app/src/storage/tests/examples/runStorage.test.ts`.
- [Media](https://db3.ai/docs/media.md): behavioural evidence in `packages/app/src/media/tests/examples/runProjectMedia.test.ts`.
- [Mail](https://db3.ai/docs/mail.md): behavioural evidence in `packages/app/src/mail/tests/examples/runMailPreview.test.ts`.
- [Write useful, safe logs](https://db3.ai/docs/logging.md): behavioural evidence in `packages/app/src/logging/tests/examples/runNoteLogs.test.ts`.
- [Encrypt a secret you need to read later](https://db3.ai/docs/security.md): behavioural evidence in `packages/app/src/security/tests/examples/runSecretRoundTrip.test.ts`.
- [Application URLs](https://db3.ai/docs/url.md): behavioural evidence in `packages/app/src/url/tests/examples/runApplicationLinks.test.ts`.
- [Restore durable application objects](https://db3.ai/docs/serialization.md): behavioural evidence in `packages/app/src/serialization/tests/examples/runExportSerialization.test.ts`.
- [Render public HTML](https://db3.ai/docs/ssr.md): behavioural evidence in `packages/app/src/ssr/tests/examples/runPublicPages.test.ts`.
- [Add a bounded AI text feature](https://db3.ai/docs/ai.md): behavioural evidence in `packages/app/src/ai/tests/OpenAIText.test.ts`.
- [Save related records together or not at all](https://db3.ai/docs/cookbook-transactions.md): behavioural evidence in `packages/app/src/db/tests/examples/workspaceNotes.test.ts`.
- [Retry later without using an attempt](https://db3.ai/docs/cookbook-retries.md): behavioural evidence in `packages/app/src/queue/tests/examples/runBackpressure.test.ts`.
- [Stream an export and clean up failure](https://db3.ai/docs/cookbook-streams.md): behavioural evidence in `packages/app/src/storage/tests/examples/runStreamExport.test.ts`.
- [Store an integration secret safely](https://db3.ai/docs/cookbook-secrets.md): behavioural evidence in `packages/app/src/db/tests/examples/runFieldNotes.test.ts`.
- [Build and operate queued work](https://db3.ai/docs/example-queue.md): behavioural evidence in `packages/app/src/queue/tests/examples/runQueueWorkflows.test.ts`.
- [@db3.ai/pure](https://db3.ai/docs/package-pure.md): behavioural evidence in `packages/pure/tests/noteTags.test.ts`.