# Infrastructure and DevOps

# Infrastructure and DevOps

<details>
<summary>Relevant source files</summary>

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

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

</details>



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**
```mermaid
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](#8.1)**.

## 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**
```mermaid
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](#8.2)**.

## 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](#8.3)**.

***

## Child Pages
- **[Docker Infrastructure and Casdoor Setup](#8.1)**: Deep dive into the `docker-compose` services and the `setup-casdoor.ts` automation.
- **[GitFlow, Versioning, and CI Hooks](#8.2)**: Comprehensive guide to the branching strategy, `version-sync.mjs`, and git hooks.
- **[OpenAPI Documentation](#8.3)**: Technical reference for the OpenAPI spec and its implementation in the codebase.

---