Routes Overview

199 route files in backend/src/routes/ (as of 2026-06, excluding co-located tests), organized by API path prefix. All routes use OpenAPIHono for automatic OpenAPI spec generation with Zod schema validation on inputs and outputs.

Route Organization

Selected mounts from backend/src/index.ts:

Path Prefix	Route File(s)	Entity/Feature
/api/auth	auth.ts, entra-auth.ts	Authentication, Azure Entra
/api/users	users.ts, user-groups.ts	Users
/api/buildings	buildings/ + buildingRoles.ts, site-protocols.ts, portal-audience.ts	Buildings, Building Components
/api/projects	projects.ts, projectRoles.ts, scenarios.ts, scenario-measures.ts, project-phases.ts, document-requests.ts, funding-applications.ts	Projects, Scenarios, Funding Applications
/api/measures, /api/building-components, /api/building-technology	dedicated files	Measures, Building Components
/api/contacts	contacts.ts	Contacts
/api/companies	companies.ts	Companies
/api/quotes	quotes.ts	Quotes
/api/invoices	invoices.ts	Invoices
/api/billing	billing*.ts (operations, items, accounting, templates, settings, email)	Billing
/api/sevdesk	sevdesk.ts	sevDesk accounting bridge
/api/funding-programs	funding-programs.ts	Funding Programs
/api/document-obtaining	document-obtaining/ (directory)	Document Obtaining
/api/files, /api/file-collections, /api/file-collection-members, /api/file-labels, /api/entity-file-links, /api/entity-collection-links	files.ts, files-bulk.ts, collection/link files	Files (CAS, collection-canonical)
/api/pdf-export, /api/pdf-data-field-definitions, /api/pdf-combined-fields, /api/pdf-document-sessions	pdf-*.ts	PDF Templates
/api/workflow	workflow/ (directory) + workflow-package-extras.ts	Workflows
/api/flow-definitions, /api/form-submissions	dedicated files	Forms
/api/portal	portal/ (directory)	Portal
/api/admin/*	admin/ (directory: users, departments, products, finance, hubspot config, templates, …)	Admin Dashboard
/api/hubspot	hubspot/ (directory)	HubSpot Integration
/api/dashboard, /api/admin-dashboard, /api/document-obtaining-dashboard	dashboard/, admin-dashboard.ts, document-obtaining-dashboard.ts	Dashboards
/api/engagement-tasks, /api/custom-timeline-items, /api/sync-history	dedicated files	Tasks, timeline, sync history
/api/config	config/ (directory)	System configuration
/api/health	health.ts, health/	Health checks (mounted before global middleware)
/api/feedback	feedback.ts	Feedback System
/api/audit-logs	auditLogs.ts	Audit Logs
/api/version, /api/performance	version.ts, performance.ts	Diagnostics

There is no /api/leads route — leads sync from HubSpot into hubspot_leads and surface through HubSpot/sync routes.

Route Pattern

const route = createRoute({
  method: 'get',
  path: '/api/buildings/:id',
  request: { params: BuildingParamsSchema },
  responses: { 200: { content: { 'application/json': { schema: BuildingResponseSchema } } } },
});
 
app.openapi(route, async (c) => {
  const { buildings } = c.var.services;  // Destructure from DI
  const result = await buildings.getById(c.req.valid('param').id);
  return c.json(result);
});

Service Access Rule

Always destructure services from c.var.services — never alias:

// Correct
const { documentRequests, portal } = c.var.services;
 
// Wrong -- never alias
const requestService = c.var.services.documentRequests;

See Service Layer Pattern, Dependency Injection.

Persistence Rule (NEW code)

Routes are presentation layer and never import @/db (I#2013): persistence flows route → service → domain module. Legacy direct DB access sits on a ratcheted allowlist (scripts/check-persistence-topology.sh) and migrates on touch; quick-lint.sh flags new violations. See Persistence Topology.

Related

• Backend Architecture — Overall backend structure
• Services Overview — Business logic called by routes
• Persistence Topology — Layering rules for DB access
• Backend Middleware — Middleware pipeline before routes
• Middleware Stack — Security and auth middleware order
• Validation Pattern — Zod schema validation on all inputs