Three-Tier Architecture (Controller / Service / Manager)

Controller  → HTTP request/response, query binding, context extraction
Service     → Business logic, request/response transformation, validation, tracing
Manager     → Data fetching: DB calls, external gRPC calls

Data flow

flowchart TD
    A[HTTP Request] --> B["Controller<br/>bind params, extract context"]
    B --> C["Service<br/>business logic, model conversion, tracing"]
    C --> D["Manager<br/>DB calls, external gRPC calls"]
    D --> E[(Database)]
    D --> F[External gRPC Service]

External vs internal API mapping

External APIs are versioned (/api/v1/sessions); internal APIs aren’t (/internal/sessions). The difference in path structure means the protobuf go_package differs, requiring manual mapping between external and internal representations.

Trade-off: simpler internal APIs at the cost of extra conversion code in the service layer.

See also

• manager-vs-service — difference between the Service and Manager layers
• interface-dependency-pattern — how Manager and Service are wired with interfaces