Skip to content

Backend Implementation Blueprint

Purpose

The Backend Implementation Blueprint translates the Modulith, API, Database, Security, and Event standards into implementation guidance for the Algosure backend.

This is implementation guidance, not Java code. It defines the backend shape future implementation work must follow.

Scope

Area Standard
Implementation style Spring Boot Modulith as the primary backend style.
Project layout Clear source, test, module, migration, and documentation boundaries.
Packages Domain-aligned package conventions under com.algoza.algosure.
APIs Controllers expose contract DTOs and call owning application services.
Application layer Use-case orchestration, transactions, authorization context, events, and persistence.
Domain layer Aggregates, entities, value objects, policies, domain services, and domain events.
Persistence PostgreSQL, module-owned repositories, Liquibase migrations, read models, and outbox.
Security Keycloak, Spring Security, Identity decisions, Billing entitlements, tenant context.
Validation and exceptions Boundary validation, domain validation, standard API errors, and correlation.
Testing Modulith boundaries, security, tenant isolation, database, events, and API contracts.

Backend Flow

flowchart LR
    API[Controller]
    DTO[Request DTO]
    App[Application Service]
    Domain[Domain Model]
    Repo[Module Repository]
    Events[Internal Events and Outbox]
    DB[(PostgreSQL)]

    API --> DTO
    DTO --> App
    App --> Domain
    App --> Repo
    Domain --> Events
    Repo --> DB

Non-Negotiables

  • Spring Boot Modulith remains the implementation style.
  • One approved Domain maps to one module where practical.
  • Modules do not directly mutate another module's owned data.
  • APIs do not expose aggregates or persistence entities.
  • Repositories remain module-private.
  • Keycloak authenticates; Identity authorizes business access.
  • Billing owns entitlement facts.
  • PostgreSQL is the operational store and Liquibase owns migrations.
  • Internal events are past-tense facts and use outbox where reliability matters.
  • Tenant and organization context are explicit, validated, and auditable.