Controller Implementation Standard

Purpose

Controllers implement HTTP API boundaries for approved API specifications. They do not contain business rules.

Responsibilities

Responsibility	Standard
Request binding	Accept contract DTOs and request metadata.
Authentication context	Require Spring Security-authenticated caller context.
Tenant context	Extract and pass TenantId and OrganizationId where applicable.
Validation	Trigger boundary validation before application service execution.
Mapping	Map DTOs to commands or queries.
Response	Return the standard response envelope.
Error delegation	Let standard exception handling produce API errors.

Forbidden Logic

• Domain decisions.
• Repository access.
• Cross-module orchestration.
• Entitlement decisions.
• Manual token parsing outside approved security components.
• Raw provider or database error exposure.

Controller Flow

flowchart LR
    HTTP[HTTP Request]
    Security[Spring Security Context]
    Validate[DTO Validation]
    Mapper[DTO Mapper]
    App[Application Service]
    Envelope[Response Envelope]

    HTTP --> Security --> Validate --> Mapper --> App --> Envelope

Rules

• Controllers are thin.
• Controllers call owning application services only.
• Controllers must not expose aggregates or persistence entities.
• Controllers must include correlation and tenant context in downstream calls.
• Controller tests verify contracts, validation, authorization, and error mapping.