# Build an app with db3.ai

> A TypeScript application framework for getting useful features built: models, authentication, files, background work and server-side AI.

- Package: `@db3.ai/app`
- Canonical page: [https://db3.ai/docs/welcome](https://db3.ai/docs/welcome)
- Markdown: [https://db3.ai/docs/welcome.md](https://db3.ai/docs/welcome.md)
- Framework source of truth: `packages/app/README.md`

<a id="start"></a>

## Start with an app that already does something

The Notes + AI starter gives you a Vue and DOM Studio shell, a landing page, password login and private notes. Add your own OpenAI key on the server to enable note summaries. The app still works without a key.

Start with the starter guide. It covers MariaDB, migrations, running locally, tests and your first model change. You do not need Scout or the private development monorepo.

- [Create the Notes + AI starter](https://db3.ai/docs/starter-app.md)

<a id="availability"></a>

## Current preview and the one-command goal

The framework and creator are not published to npm yet. The starter guide has a working path using maintainer-supplied package tarballs. The command below is the intended public entry point after publication, not a command that works today.

That command creates an application. Running database-backed features still requires a database and the documented app configuration. Docker is optional; local MariaDB is supported.

### After npm publication only

```bash
npm create @db3.ai@latest my-app
```

<a id="smaller"></a>

## Start smaller if you prefer

Install the runtime and build a minimal HTTP app, or use one service in a script. The first HTTP example needs no database, Vue or cloud credentials. It includes runnable requests, validation, shutdown and tests.

- [Install the runtime](https://db3.ai/docs/installation.md)
- [Run your first HTTP app](https://db3.ai/docs/create-app.md)

<a id="model"></a>

## Keep the database visible

ActiveRecord is a useful way to organise an application and move quickly. Fields own conversion and validation so the same rules can be reused across models. The framework does not remove the need to understand queries, transactions or indexes.

Use the normal model API for normal work and the database escape hatch when the problem needs it. Application permissions and business rules remain in your app.

- [ActiveRecord and the field-first model](https://db3.ai/docs/active-record.md)

<a id="features"></a>

## Build the next feature

Use Auth for accounts, Storage and Media for files, Queue for durable background work and Scheduler for recurring jobs. Each service guide separates the first useful result from advanced options and operational limits.

The current AI service is a bounded server-only text client. Generic agents, embeddings, usage accounting, billing credits and installable mini-apps are planned work, not features this preview already provides.

- [Configure your application](https://db3.ai/docs/app-config.md)
- [Queue a real report](https://db3.ai/docs/queue-overview.md)
- [Find a guide by problem](https://db3.ai/docs/solve-a-problem.md)

<a id="testing"></a>

## Use the examples as working code

Service examples ship with the package. The website renders their source, expected output and copyable tests. A passing example proves that workflow; it does not mean every provider or production deployment has been tested.

Keep the example test when you change a feature. Advanced references show emitted public signatures, and the source-backed Markdown and AI documentation use the same registered content.

## Related documentation
- [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.
- [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.
- [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.
- [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.

## Guidance for AI tools
Use the documented public import `@db3.ai/app` and its exported types. Prefer the source-backed examples and behavioural outcomes above over invented APIs or source-relative internal imports.