Copy page

Backend

Infrastructure and DevOps

Infrastructure and DevOps

Relevant source files

The following files were used as context for generating this wiki page:

• AGENTS.md
• README.md
• docs/gitflow.md
• infra/docker-compose.postgres.yml
• src/modules/auth/avatar-svg-generator.ts
• src/modules/customers/list-config.ts
• src/openapi/openapi.ts

This section provides a high-level overview of the infrastructure stack, deployment orchestration, and the development lifecycle management for the Primebrick backend. The system relies on Docker for service isolation, a strict GitFlow branching model for stability, and automated version synchronization to ensure consistency between the codebase and git tags.

Infrastructure Stack

The Primebrick backend utilizes a containerized infrastructure managed via Docker Compose. The stack is designed for local development and consistent staging environments, providing the necessary data persistence and service discovery for the API.

Service Overview

The primary infrastructure components are defined in infra/docker-compose.postgres.yml:

• PostgreSQL 18: The primary relational database. It includes a custom entrypoint to install pg_partman for partition management infra/docker-compose.postgres.yml:30-52.
• Casdoor: An open-source Identity and Access Management (IAM) solution. It handles authentication and OIDC discovery infra/docker-compose.postgres.yml:60-84.
• NATS: A high-performance messaging system used for internal communication and JetStream persistence infra/docker-compose.postgres.yml:86-100.

Component Relationship Diagram

The following diagram illustrates how the infrastructure services interact with the API and the persistence layers.

Infrastructure Service Map

Code
graph TD
    subgraph "Docker Compose Stack"
        [primebrick-postgres-18] --> |"Volume: primebrick_pg18_data"| DB_VOL[("PostgreSQL Storage")]
        [primebrick-casdoor] --> |"Depends On"| [primebrick-postgres-18]
        [primebrick-casdoor] --> |"Volume: primebrick_casdoor_data"| CD_VOL[("Casdoor Config")]
        [primebrick-nats] --> |"Volume: primebrick_nats_data"| NATS_VOL[("NATS JetStream")]
    end

    subgraph "Primebrick API (App Space)"
        API["Express Server"]
        API --> |"pg-pool"| [primebrick-postgres-18]
        API --> |"JWT/OIDC"| [primebrick-casdoor]
        API --> |"NATS Client"| [primebrick-nats]
    end

Sources: infra/docker-compose.postgres.yml:29-112, AGENTS.md:30-31

For details on service configuration, named volumes, and the Casdoor bootstrap process, see Docker Infrastructure and Casdoor Setup.

DevOps and Development Lifecycle

The project follows a disciplined DevOps approach to ensure code quality and versioning integrity. This includes a strict branching strategy and automated hooks that maintain the database state and package versions.

GitFlow and Versioning

The repository adheres to the GitFlow model docs/gitflow.md:1-4.

• Feature Branches: feature/<slug> branched from develop docs/gitflow.md:19.
• Release Branches: release/<version> branched from develop for version bumps docs/gitflow.md:20.
• Hotfix Branches: hotfix/<version> branched from main for critical fixes docs/gitflow.md:21.

Version management is automated via version-sync.mjs, which ensures that package.json reflects the branch name and latest git tags docs/gitflow.md:48-54.

Automation Hooks

• Post-Merge Hook: Automatically triggers pnpm run db:migrate to keep the local database schema aligned with the latest patches AGENTS.md:63-64.
• Pre-Commit Constraints: AI agents are strictly prohibited from committing automatically without explicit user instruction AGENTS.md:3-9.

Workflow State Diagram

Code
stateDiagram-v2
    [*] --> develop
    develop --> feature/task : "git checkout -b"
    feature/task --> develop : "git merge --no-ff"
    develop --> release/x.y.z : "version-sync.mjs triggers"
    release/x.y.z --> main : "Final Tag"
    main --> develop : "Back-merge"
    main --> hotfix/x.y.z : "Emergency"
    hotfix/x.y.z --> main : "Patch Tag"

Sources: docs/gitflow.md:16-45, AGENTS.md:65-70

For details on the branching rules, versioning logic, and operational constraints for AI agents, see GitFlow, Versioning, and CI Hooks.

API Documentation

The backend exposes its capabilities through an OpenAPI 3.0.3 specification. This documentation is served dynamically and provides a contract for frontend integration and external client development.

• Endpoint: The specification is typically served via the openApiRouter.
• Scope: Covers all entity operations (Customer, Organization) and Authentication endpoints src/openapi/openapi.ts:7-203.

For details on the OpenAPI schema, available routes, and integration patterns, see OpenAPI Documentation.

---

Child Pages

• Docker Infrastructure and Casdoor Setup: Deep dive into the docker-compose services and the setup-casdoor.ts automation.
• GitFlow, Versioning, and CI Hooks: Comprehensive guide to the branching strategy, version-sync.mjs, and git hooks.
• OpenAPI Documentation: Technical reference for the OpenAPI spec and its implementation in the codebase.

---