# Solve a problem

> Start with the feature you need. Follow one workflow across the services it uses.

- Package: `@db3.ai/app`
- Canonical page: [https://db3.ai/docs/solve-a-problem](https://db3.ai/docs/solve-a-problem)
- Markdown: [https://db3.ai/docs/solve-a-problem.md](https://db3.ai/docs/solve-a-problem.md)
- Framework source of truth: `docs/framework-goals.md`

<a id="signed-in-notes"></a>

## Add a private feature behind login

Start with the generated Notes app. Trace its cookie session, validate a request, query by the trusted owner and test foreign-account access. The API walkthrough uses the real generated route source and test; publication and the integrated starter trial are separate release checks.

- [Login and sessions](https://db3.ai/docs/guide-auth.md)
- [Owned note API](https://db3.ai/docs/guide-api.md)

<a id="private-files"></a>

## Accept and serve a private file

Available as an installed-package lab. Use real Auth, Media and Storage through a small HTTP factory. Reject foreign reads, invalid uploads and oversized bodies, then delete both metadata and bytes. The matching test keeps all three services real.

- [Private-file walkthrough](https://db3.ai/docs/guide-files.md)
- [Cross-service testing](https://db3.ai/docs/guide-testing.md)

<a id="stream-export"></a>

## Build a large export safely

Stream a CSV into a private staging path and replace the final export only after success. Trigger a source failure, preserve the previous file and recover. This bounded-memory lab is separate from an HTTP download/disconnect policy.

- [Streamed exports](https://db3.ai/docs/cookbook-streams.md)

<a id="repair-flow"></a>

## Inspect and replay a failed workflow

Save a two-block definition, inspect its durable result and repair invalid input. Compare replay against the saved definition snapshot with replay against the latest definition; a graph snapshot is not a snapshot of deployed block code.

- [Durable flows](https://db3.ai/docs/flows.md)

<a id="queued-report"></a>

## Build a report and recover a failed job

Available as a pre-release package lab. Queue persists a report across App lifetimes, Storage supplies its input and output, and a SQL-backed worker retries, records failure and replays after repair. Repeated work replaces the same output. This is not exactly-once email delivery or a provider billing guarantee.

- [Run the queued-report walkthrough](https://db3.ai/docs/queue-overview.md#setup)

<a id="workspace-notes"></a>

## Keep workspace data separate

Available as a pre-release package lab. Create and edit notes without accepting ownership from request data. Covers App, ActiveRecord, field validation, scoped reads and transactions. It does not provide the authentication or membership layer.

- [Run the workspace notes walkthrough](https://db3.ai/docs/guide-workspace-notes.md)

<a id="ai-credits"></a>

## Charge credits for AI usage

TODO. This recipe will combine a credit ledger, atomic allowance reservations, tracked AI requests and idempotent settlement. The important case is not just a successful charge: two concurrent requests must not spend the same balance, and a retry must not charge twice.

It will also cover failed provider attempts, partial/unknown costs, refunds and a provider success followed by a settlement failure. Provider cost and the customer’s credit charge are different values.

The starter has optional server-side text generation, but reusable accounting and allowance APIs are not available yet. You can use ActiveRecord and transactions today; this billing walkthrough will follow when those contracts are ready.

- [Transaction foundations](https://db3.ai/docs/active-record.md#transactions)

<a id="file-processing"></a>

## Upload a file and process it in the background

TODO: the integrated processing/progress recipe. Private uploads and durable queued reports already have separate working labs. The remaining recipe must connect them and explain what happens if upload, dispatch or processing fails independently, without inventing atomicity between files and SQL.

- [Private upload foundation](https://db3.ai/docs/guide-files.md)
- [Background worker foundation](https://db3.ai/docs/guide-background.md)

<a id="delivery"></a>

## Send a scheduled report once

TODO. Combine Scheduler, Queue, Mail and ActiveRecord. Keep report history on an application model and use an explicit delivery identity. A queue retry does not by itself guarantee an email is sent once.

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

## 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.