@parmana/api

The Express server and its bootstrap composition root. For the REST surface itself, see the API Reference section.

[AVAILABLE]. packages/api. Not a library other packages import, it’s the running server. No public exports (src/index.ts is empty).

Purpose

Composes every other package into one running Express process: policy loading, the gateway, credential isolation, caller authentication, and 14 HTTP routes. For the routes themselves, request/response shapes, and verified error codes, see REST API Introduction, this page covers the server’s internal structure.

Install

Not installed as a dependency, this package is the deployable server itself. See Deploy patterns.

Structure

Path	Purpose
src/server.ts	Entry point. Builds the execution system, the application, then the Express app, and listens on port 3000.
src/app.ts	Mounts the caller-auth middleware (every route except /health), all 14 routes, and the error handler, in order, the error handler must be registered last.
src/application.ts	createApplication(executionSystem), wires RuntimeFactory.create() with the repositories and policy repository.
src/routes/*.ts	One file per route (or router factory), see REST API Introduction for each one’s behavior.
src/middleware/error-handler.ts	Maps thrown errors to HTTP status codes by instanceof, falls through to an unstructured 500 for anything unrecognized.
src/middleware/caller-auth.ts	Bearer-key caller authentication, see Authentication.
src/mappers/BusinessTransactionMapper.ts	fromRequest(body), forces status: RECEIVED and createdAt: now regardless of client input.
src/bootstrap/*.ts	The composition root: createExecutionSystem, createExecutionGateway, createExecutionControl, createConnectorRegistry, createConnectorRoute, createConnectorAuthenticator, createCallerAuthenticator, createHubSpotCredentialProvider, createGatewayKeyPair, createGatewayPublicKey, createGatewayIdentity, createNonceStore, createSessionStore, createExecutionAuditSink. Every bootstrap decision described on The gateway and Credential isolation lives here.

One file in src/bootstrap/ is dead code, not wired into anything: ConnectorCatalog.ts lists connectors (including disabled stubs like stripe/sap) but is not imported anywhere in packages/api/src. The real, running connector registration path is createConnectorRegistry.ts, see The gateway. Two other files, scripts/generate-keys.ts (repo root) and packages/api/src/bootstrap/createVendorPaymentSecureConnector.ts, are empty, 0-byte stub files, also unused.

ExecutionControlComposition.ts and ConnectorFactory.ts (a different, class-based composition root for the same responsibility as createExecutionControl.ts — not the ConnectorFactory interface from @parmana/connector-sdk described on this page) previously sat alongside the real path with zero callers anywhere in the repository. Removed in Phase 2I (docs/architecture/phase2i-composition-root-cleanup.md) after independent verification confirmed they were never wired into production, tests, or any published surface.

Minimal example

npm run generate:gateway-keys
NODE_ENV=test PARMANA_STORAGE=memory PARMANA_POLICY_DIR=/absolute/path/to/policies \
  npm run dev

Full walkthrough: Quickstart.

Next

REST API Introduction

Every route’s request, response, and verified error codes.

Deploy patterns

Storage, keys, and the full environment checklist for running this server.