Backend Architecture

The backend is a Bun + Hono TypeScript API server with OpenAPI support, running on port 3000 behind nginx. Entry point: backend/src/index.ts.

Layered Architecture

  HTTP Request
       │
  ┌────▼─────┐
  │ Middleware │  security → cors → sanitization → rateLimiter → auth
  ├───────────┤
  │  Routes   │  OpenAPI-typed endpoint handlers (164 files)
  ├───────────┤
  │ Services  │  Business logic, orchestration (98 files)
  ├───────────┤
  │    DB     │  Drizzle ORM queries, schema (140 tables)
  └───────────┘

Routes delegate to services. Services contain business logic and database access. See Service Layer Pattern for conventions.

Dependency Injection

The backend uses a DI container pattern through Hono’s context variables. See Dependency Injection for full details.

// In route handlers — access services via c.var
const { documentRequests, portal } = c.var.services;
 
// Infrastructure and cross-cutting concerns
const { logger, cache } = c.var.container.infrastructure;

Container is initialized at startup and injected into every request via middleware. Service interfaces are defined in backend/src/interfaces/ (48 files).

Directory Structure

Directory	Files	Purpose
src/routes/	164	API endpoint handlers with OpenAPI schemas
src/services/	98	Business logic and data access
src/lib/	126	Shared utilities (auth, encryption, sanitization)
src/interfaces/	48	TypeScript interfaces for DI contracts
src/middleware/	10	Request processing pipeline
src/db/	—	Schema, seeds, shared schemas
src/test/	—	Unit and integration tests

Middleware Stack

Processing order defined in backend/src/index.ts. See Backend Middleware and Middleware Stack for details.

Middleware	File	Purpose
Security	middleware/security.ts	CSP, HSTS, X-Frame-Options headers
CORS	(Hono built-in)	Cross-origin request handling
Sanitization	middleware/sanitization.ts	DOMPurify XSS protection
Rate Limiter	middleware/rateLimiter.ts	Auth: 5/15min, API: 100/min
Auth	middleware/auth.ts	JWT verification, user context
Portal Auth	middleware/portal-auth.ts	External stakeholder auth
RBAC	middleware/rbac.ts	Role-based access control
Audit Logger	middleware/auditLogger.ts	Action audit trail
Error Handler	middleware/errorHandler.ts	Structured error responses
Timeout	middleware/timeout.ts	Request timeout enforcement

Key Libraries

Module	Path	Purpose
Auth	src/lib/auth.ts	JWT, argon2id password hashing via Bun.password
Encryption	src/lib/encryption.ts	AES-256-GCM for OAuth tokens, PII
Sanitization	src/lib/sanitization-helpers.ts	strictTextField, sanitizedLocalizedText
Ownership Guards	src/lib/ownership-guards.ts	verifyProjectAccess(), verifyBuildingAccess()
File Upload	src/lib/file-upload.ts	Tigris S3-compatible object storage

Testing

• Runner: Bun’s built-in test runner
• Unit tests: src/test/unit/ — no database required
• Integration tests: src/test/integration/ — full API route tests with test DB
• Helpers: setupTestServer(), resetTestDatabase(), createAuthenticatedTestUser(), apiRequest()
• Coverage: 70% threshold, enforced in CI

See Error Handling Pattern and Validation Pattern for request/response handling conventions.

Related Pages

• Architecture Overview — System-wide architecture
• Service Layer Pattern — How services are structured
• Dependency Injection — Container pattern details
• Middleware Stack — Full middleware pipeline
• Routes Overview — All API endpoints
• Services Overview — All service modules
• Backend Middleware — Middleware implementation details
• Library Utilities — Utility module catalog
• Database Architecture — ORM and schema
• RBAC Authorization — Permission model
• Authentication — JWT and password handling
• External Integrations — Third-party connectors