Skip to content

Architecture

This document describes the current technical architecture of The Self Service Hub (SSH) monorepo.

It focuses on deployable services, adapters, and runtime interaction patterns.

Overview Diagram

Architecture Overview

System Scope

The repository is a monorepo that contains multiple independently deployable services.

Current product flows:

  • Seats Management flow
    1. User -> Self Service Hub Frontend
    2. Self Service Hub Frontend -> Seats Allocation Service
    3. Seats Allocation Service -> UserDB Adapter -> UserDB Database
    4. Seats Allocation Service -> Seats Allocation Database (AWS Aurora PostgreSQL)
  • Billing Management flow
    1. User -> Self Service Hub Frontend
    2. Self Service Hub Frontend -> Billing Management Service
    3. Billing Management Service -> Keylight

Architecture Style

SSH follows a service-oriented architecture with explicit network boundaries.

  • Separate deployables: frontend, services, and adapters are versioned and deployed independently.
  • Adapter boundary: adapters isolate selected integrations behind service APIs.
  • Policy enforcement at edge: an authorizer sidecar can enforce pre-shared-secret access before traffic reaches internal services.

Main Services and Adapters

Service/Adapter Path Primary role
Self Service Hub Frontend seats-allocation/frontend/ User-facing application for seat management and billing use cases
Seats Allocation Service services/seats-allocation/ Seat allocation business logic and APIs
UserDB Adapter adapters/userdb/ API layer used by Seats Allocation Service for user DB access
Billing Management Service services/billing-management/ Billing and subscription APIs
Authorizer Sidecar Service services/authorizer-sidecar/ Reverse proxy that validates pre-shared secrets

Data Stores and External Systems

Datastore/System Type Used by
Seats Allocation Database AWS Aurora PostgreSQL Seats Allocation Service
UserDB Database MySQL UserDB Adapter
Keylight External billing system/API Billing Management Service

Service Interaction Flows

Seats Management Flow

  1. User interacts with the Self Service Hub Frontend.
  2. Self Service Hub Frontend calls Seats Allocation Service.
  3. Seats Allocation Service calls UserDB Adapter for user-related data.
  4. UserDB Adapter reads/writes UserDB Database.
  5. Seats Allocation Service also reads/writes Seats Allocation Database.

Billing Management Flow

  1. User interacts with the Self Service Hub Frontend.
  2. Self Service Hub Frontend calls Billing Management Service.
  3. Billing Management Service calls Keylight directly.

There is no dedicated Keylight adapter in the current SSH architecture.

Security Model (Current)

  • Edge protection: the authorizer sidecar validates pre-shared secrets before forwarding traffic.
  • Application authentication: services/seats-allocation/ validates JWTs for /me/** endpoints and resolves identity/context via filters.
  • Network isolation: direct access to internal services is restricted by network boundaries between edge and internal services.

Operational Notes

  • Datadog APM is enabled in multiple services (see service-level READMEs).
  • Deployable units have service-local build and test pipelines.
Last updated: March 31, 2026 at 15:17
By: Rafael Robles