> ## Documentation Index
> Fetch the complete documentation index at: https://docs.manthan.systems/llms.txt
> Use this file to discover all available pages before exploring further.

# api

> @parmana/api — the Express server, and the only package that's a running application

`packages/api` is the composition root — the only package in the monorepo that's actually a running server rather than a library. It has no `index.ts`; its entry points are `app.ts` (the Express app) and `server.ts`.

## Composition

```
packages/api/src/application.ts
  policyRepository = new FilePolicyRepository(process.env.PARMANA_POLICY_DIR!)
  application = RuntimeFactory.create(
    businessTransactionRepository,   // from repositories.ts
    executionTrustRecordRepository,  // from repositories.ts
    policyRepository,
  )

packages/api/src/repositories.ts
  storage = StorageFactory.createFromEnvironment()   // PARMANA_STORAGE, default "memory"
  businessTransactionRepository = storage.businessTransactions
  executionTrustRecordRepository = storage.trustRecords
```

Every route handler imports the single `application` instance from `application.ts` — there's exactly one `ExecutionTrustApplication` per process, module-scoped.

## Routing

`app.ts` mounts eleven route modules under `packages/api/src/routes/`. See [REST API Overview](/docs/api/overview) for the full endpoint table, and [Verify](/docs/api/verify) / [Receipt](/docs/api/receipt) specifically for two mount paths that don't match their filenames' apparent intent (`/verification`, not `/verify/:id`; `/receipt/latest`, not `/receipt/:id`).

## Error handling

`packages/api/src/middleware/error-handler.ts` is registered last, after all routes. It special-cases, in order: `BusinessTransactionValidationError` / `PolicyValidationError` / `SignalValidationError` → `400`; `PolicyNotFoundError` → `404`; `DuplicateBusinessTransactionError` → `409`; any other `RuntimeError` (from `@parmana/runtime`) → `error.status` with `{ error, code }`; anything else → logged to `console.error` and `500 { "error": "Internal Server Error" }`.

<Note>
  This only runs for errors passed to Express's `next(error)`. Several routes (`execute.ts`, `verify.ts`, `replay.ts`, `receipt.ts`, `policies.ts`) return their own ad hoc `{ "error": string }` bodies directly for request-shape validation failures, before `errorHandler` ever sees them. See [REST API → Error Model](/docs/api/error-model) for the full accounting of which shape you get from where.
</Note>

## `BusinessTransactionMapper`

`packages/api/src/mappers/BusinessTransactionMapper.ts` defines `BusinessTransactionMapper.fromRequest()`, intended to map a raw request body into an immutable `BusinessTransaction` (setting `status: RECEIVED` and `createdAt: new Date()`). It isn't called anywhere — `execute.ts` passes `req.body` straight to `application.execute()` without going through this mapper.

## Related

<CardGroup cols={2}>
  <Card title="REST API Overview" href="/docs/api/overview">Every mounted endpoint.</Card>
  <Card title="Error Model" href="/docs/api/error-model">The full error-shape breakdown.</Card>
  <Card title="Authentication" href="/docs/api/authentication">Why there's no auth middleware here yet.</Card>
  <Card title="runtime" href="/docs/packages/runtime">What `RuntimeFactory.create` actually builds.</Card>
</CardGroup>