Skip to content

Application services and adapters

Routes translate HTTP and establish the policy for a requested operation. Services own reusable identity, domain and provider behaviour below that boundary. Database functions own invariants that need one transaction. This division allows an API route, background worker or supported agent tool to reuse behaviour while retaining its own caller and resource obligations.

A service is not automatically safe for every caller. Its accepted actor/company/resource inputs and its own checks are part of the contract. Moving a privileged query out of a route does not remove the need to establish scope before it runs.

Owner Inspected responsibility Boundary
Route module HTTP parsing, dependencies, resource admission and response/error translation Avoid duplicating shared policy joins or provider semantics
auth_context Account/token verification and live membership model Identity foundation, not every domain operation’s permission
common Selected-company/capability helpers, scoped lookup and bounded reads Generic helpers do not infer portal relationships
Customer portal access service Discovery and exact admitted person/project context through SQL owners Stronger completion/recipient actions retain domain constraints
Contact profile service Company-local presentation and delivery addresses Presentation does not choose the authenticated person or change Auth identity
Domain transaction RPC Atomic state, revision and invariant checks It cannot atomically commit an unrelated provider result
Provider adapter/shared-service contract External vocabulary, identity and recoverable outcome Local receipt and remote acceptance remain distinct facts

route_security belongs to the declarative catalogue mechanism; it sets metadata rather than performing a reusable authorization check. Actual guard dependencies and admission helpers must still run.

services/auth_context.py is the low-level identity owner. The auth route re-exports the same objects for compatibility, preserving FastAPI dependency overrides. New code should import identity from the service rather than create a service-to-route dependency. The extraction tests check object identity and the absence of route imports below the service layer.

Customer access is a complete reference flow. Discovery and direct project admission call the same service-only SQL rule owners. The Python service returns small safe projections and verified context; it does not reproduce independent role joins or choose a contact by display order. Recipient edits and completion reuse admission while preserving their stronger rules.

Common pagination helpers solve a different shared concern. They require callers to supply filters and stable ordering. Reusing the helper cannot make an unscoped query tenant-safe. Runtime PostgREST shape helpers reject malformed payloads instead of silently converting provider failure into empty rows.

Provider-specific identifiers and error semantics stay behind the owning adapter where that interface exists. Toolora retains product behaviour and domain language. Estate originals, archive contracts and the Fortnox connector have explicit shared ownership described in integration ownership.

The shared-infrastructure adoption document is a proposal, not proof of a completed cutover. Toolora’s in-process invoice adapter still exists behind its provider-neutral accounting interface. Documentation reuse does not authorize a new direct provider call, copied legacy service or speculative replacement platform.

A synthetic customer project list and a direct detail URL must agree on admission. Both consume the shared SQL projection through the access service. The detail route can then add its own published presentation, while a recipient-write route additionally requires customer-wide authority. Copying a simplified staff/customer test into each route would risk different answers for the same person and project.

A background task uses a different entry policy: it acts on a claimed, scoped intent rather than pretending to hold a current browser session. It may reuse domain/provider behaviour, but must preserve the intent’s identity, worker claim and recovery rules.

The inspected sources establish these concrete owners and reference flows. Some existing route modules still contain substantial domain logic; the intended layering is not a claim that every module is already minimal. Focused tests and existing operation receipts establish specific behaviour. This article does not authorize a structural rewrite merely to make the diagram uniform.