# Application productivity kit

WrNexus applications should declare infrastructure once and keep only domain decisions locally.

## Included foundations

1. HTTP routes: `defineApiRoute`, `authorized`, `requireUser`, `requirePermission`, `requireParam`, `requireJson`, and `json`.
2. CRUD resources: `defineResource` generates owned list/create/get/update/delete handlers.
3. Seed data: `addSeedData`, `upsertSeedData`, `seedIfMissing`, `defineSeed`, `removeSeedData`, and `runSeedQuery`.
4. Transactional delivery: `withOutbox`, `drainOutbox`, and `installOutboxSchema`.
5. Job state transitions: `defineJobStateMachine`.
6. SQLite/PostgreSQL/MySQL queue tables: configured storage plus `databaseQueueStore`.
7. Queue operations: success/failed hooks, dashboard handler and queue CLI.
8. Queue testing: `testQueue` with deterministic `runNext`/`runAll`.
9. Workflows and compensation: durable workflows and `defineSaga`.
10. Mail: `defineMail`, `defineMailTemplate`, sandbox allowlists and `queuedMail`.
11. Encrypted settings: `defineSecretResource`.
12. Ledgers: `defineLedger` with atomic debit and audit entries.
13. Forms: `useForm` for values, errors, dirty/submitting state, validation and submission.
14. Typed HTTP calls: `createApiClient`; generated OpenAPI/SDK clients remain available through `wrnexus api generate`.
15. Full-stack testing: `createTestApp`, database rollback/factories, and queue test controls.
16. Package migrations: queue/auth/authz packages contribute migrations through the plugin lifecycle.
17. Auth/OAuth: auth and authz plugins own routes, middleware, roles and provider lifecycle.
18. Code generation: `wrnexus generate resource <name>`.
19. Incremental features: `wrnexus add queue|mail|seed|testing|resource`.
20. Starter presets: `wrnexus create app --preset=saas|email` and `--features=...`.

## Recommended new-project flow

```sh
wrnexus create acme --preset=saas
cd acme && bun install
wrnexus generate resource projects
wrnexus add mail
wrnexus db migrate
wrnexus db seed
wrnexus dev
```

Use generated resources for ordinary owned CRUD. Use the outbox for business operations that
change data and enqueue work together. Use sagas only when a workflow crosses systems that cannot
share a transaction. Application code should retain product-specific policy; framework code owns
storage, validation, lifecycle, retries, diagnostics and scaffolding.