Services Overview

148 service files in backend/src/services/ (as of 2026-06, excluding co-located tests; 183 with tests), with matching interfaces in backend/src/interfaces/ (71 files). Each service encapsulates business logic for a domain entity, injected into routes via the DI container.

Under the persistence topology (I#2013), services add no new persistence: new Drizzle access lives in domain modules (currently lib/billing/, lib/file-operations/), which services and job processors consume. Existing direct DB access is allowlisted (ratcheted by scripts/check-persistence-topology.sh) and migrates on touch. See Persistence Topology and Service Layer Pattern.

DI Container

Services are created and wired in backend/src/services/create-services.ts (createProductionContainer()), then attached to the Hono context as c.var.services. The ServiceContainer (defined in interfaces/service-container.ts) has four slices: infrastructure, crossCutting, domain (domain modules), and services. Job processors receive a ProcessorContainer — a Pick of domain/infrastructure/crossCutting without the services slice (processors are peer clients of services, not callers). See Dependency Injection.

Key Services by Domain

Core Business

Service	File	Purpose
BuildingsService	buildings-service.ts	Building CRUD, geometry, metadata
BuildingTechnologyService	building-technology-service.ts	Building technology data
ProjectService	project-service.ts	Projects lifecycle
PhaseService	phase-service.ts	Project phases
WorkflowPackageService	workflow-package-service.ts + workflow-package/	Workflow packages (Auftragsübergabe)
SiteProtocolService	site-protocol-service.ts, site-protocol-pdf.ts	Site protocols + PDF export (PR#1994)

Scenarios, measures, and building components no longer have dedicated service files — their routes (scenarios.ts, scenario-measures.ts, measures.ts, building-components.ts) are served through the project/building stack.

CRM

Service	File	Purpose
ContactService	contact-service.ts	Contacts CRUD, claiming
CompanyService	company-service.ts	Companies management
ActivityService / TimelineService	activity-service.ts, timeline-service.ts	Activity + timeline

Leads have no dedicated service — they mirror HubSpot Leads into hubspot_leads via the sync engine.

Finance & Billing

Service	File	Purpose
QuoteService	quote-service.ts	Quotes CRUD
QuoteFinanceService	quote-finance-service.ts	Financial Calculations for quotes
InvoiceService	invoice-service.ts	Invoices generation
FinanceService	finance-service.ts	Finance operations
Billing suite	billing/ (14 files: invoices, operations, accounting, templates, settings, email, CAMT import)	Billing domain (persistence in lib/billing/)
SevDesk suite	sevdesk/	sevDesk accounting bridge
RevenueService	revenue/	Revenue reporting
CatalogService	catalog-service.ts	Products catalog
FundingApplicationService	funding-application-service.ts	Funding Applications
CommissionCalculator	commission-calculator.ts	Contractor commissions

Documents & Files

Service	File	Purpose
DocumentRequestService	document-request-service.ts, document-request-batch-service.ts	Documents request workflow
DocumentObtainingService	document-obtaining/	Document Obtaining collection
DocumentTemplateService	document-template-service.ts + document-template/	Document templates
FileService	file-service.ts, bulk-file-service.ts	Files CAS upload/download (streams)
Collections	collection-service.ts, file-collections-service.ts, file-collection-members-service.ts, entity-collection-links-service.ts, entity-file-link-service.ts, file-label-service.ts	Collection-canonical file linkage (PR#1752)
PDF suite	pdf-export-service.ts, pdf-template-service.ts, pdf-session-service.ts, pdf-combined-field-service.ts	PDF Templates generation

Auth & Users

Service	File	Purpose
AuthService	auth-service.ts	Authentication, 2FA, password reset
UserService	user-service.ts	Users management
TokenService	token-service.ts	Token operations
PortalService	portal-service.ts + portal/ (access, downloads, forms, fulfillment, notifications, PDF)	Portal

Automation & Scheduling

Service	File	Purpose
WorkflowStateMachine	workflow-state-machine.ts	Workflows state transitions
Workflow config/templates	workflow-config-service.ts, workflow-template-service.ts	Workflow configuration
TaskService	task-service.ts	Task management
EngagementTaskTemplateService	engagement-task-template-service.ts	Engagement task templates
AppointmentService	appointment-service.ts	Appointments scheduling
FulfillmentService	fulfillment-service.ts	Fulfillment chains
ResponsibilitiesService	responsibilities-service.ts	Responsibility assignment

External Integrations & Dashboards

Service	File(s)	Purpose
HubSpot suite	hubspot/ (33 files incl. sync-engine/, event-handlers/, mapping/)	HubSpot Integration sync
Entra suite	entra/ (auth, groups, sync)	Azure Entra SSO + department/employee sync
FeedbackService	feedback/	Feedback System
Dashboards	dashboard-service.ts, dashboard/, admin-dashboard-service.ts, document-obtaining-dashboard-service.ts	Dashboards

Notifications dispatch lives in lib/notifications/ (with the BullMQ processor in lib/jobs/processors/notifications.ts); audit logging and departments are handled by middleware + the Entra sync rather than dedicated services.

Interface Pattern

Each service has a matching interface in backend/src/interfaces/ (same basename, no .interface suffix):

backend/src/interfaces/buildings-service.ts
backend/src/services/buildings-service.ts

The interface defines the contract; the service implements it. Routes depend on interfaces, not implementations.

Related

• Service Layer Pattern — Detailed pattern documentation
• Persistence Topology — Domain modules own Drizzle access
• Dependency Injection — How services are wired and injected
• Routes Overview — Routes that consume services
• Backend Architecture — Layered architecture overview
• External Integrations — Third-party service connectors