Backend

Getting Started

Relevant source files

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

This page provides a step-by-step guide for setting up the Primebrick backend development environment. It covers prerequisites, infrastructure orchestration via Docker, environment configuration, and database initialization.

Prerequisites

Before starting, ensure the following tools are installed on your system:

Node.js: Version 20 or higher (recommended).
pnpm: Fast, disk space efficient package manager.
Docker & Docker Compose: Required for running PostgreSQL, Casdoor, and NATS.
Git: For version control and managing the GitFlow workflow docs/gitflow.md:1-4.

1. Infrastructure Setup

The project uses Docker Compose to manage the local infrastructure stack. This includes PostgreSQL 18, Casdoor (Identity Provider), and NATS (Message Broker).

Start the Stack

From the repository root, run:

Code
docker compose -f infra/docker-compose.postgres.yml up -d

Services Overview

Service	Image	Internal Port	External Port	Role
`postgres`	`postgres:18-bookworm`	`5432`	`5432`	Primary database with `pg_partman` infra/docker-compose.postgres.yml:31-52
`casdoor`	`casbin/casdoor:3.75.0`	`8000`	`8000`	OIDC Identity Provider infra/docker-compose.postgres.yml:61-70
`nats`	`nats:latest`	`4222`	`4222`	Message broker with JetStream infra/docker-compose.postgres.yml:86-93

Persistence

Data is persisted in Docker named volumes to survive container restarts:

primebrick_pg18_data: PostgreSQL data infra/docker-compose.postgres.yml:103-105.
primebrick_casdoor_data: Casdoor configurations and uploads infra/docker-compose.postgres.yml:106-108.
primebrick_nats_data: NATS JetStream state infra/docker-compose.postgres.yml:109-111.

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

2. Environment Configuration

Create a .env file in the root directory. You can use the following default values for local development:

Code
DATABASE_URL=postgresql://primebrick:primebrick_dev@127.0.0.1:5432/primebrick
CASDOOR_ENDPOINT=http://127.0.0.1:8000
PORT=3001

Note: If port 5432 is occupied by a local PostgreSQL instance, set PG_HOST_PORT=5433 in your .env and recreate the containers infra/docker-compose.postgres.yml:39-40.

Sources: infra/docker-compose.postgres.yml:33-40, AGENTS.md:42

3. Installation and Initialization

Follow these steps to prepare the application and database:

Install Dependencies

Code
pnpm install

Setup Casdoor

Bootstrap the Identity Provider with necessary organizations, applications, and roles:

Code
pnpm run setup:casdoor

This script initializes the Casdoor instance defined in the Docker stack package.json:18.

Database Migrations

The project uses a patch-based migration system. Apply the latest patches to the database:

Code
pnpm run db:migrate

This command checks the public.primebrick_database_patch table and applies missing .sql files AGENTS.md:53-54.

Seed Demo Data

To populate the database with sample customers:

Code
pnpm run db:seed:customers

Sources: package.json:15-18, AGENTS.md:19-26

4. Running the Development Server

The backend uses tsx watch for hot-reloading during development.

Code
pnpm run dev

The API will be available at http://localhost:3001.

Port Management

If you encounter EADDRINUSE on port 3001, you can use the utility script to kill the existing process:

Code
pnpm run dev:kill

Sources: package.json:7-8, AGENTS.md:33-35

Development Workflow and Data Flow

The following diagram illustrates the relationship between local development commands and the resulting infrastructure state.

Infrastructure Initialization Flow

This diagram bridges the "Natural Language Space" of setup tasks to the "Code Entity Space" of scripts and configurations.

Code
graph TD
    subgraph "Local_Commands"
        A["pnpm install"] --> B["docker compose up"]
        B --> C["pnpm run setup:casdoor"]
        C --> D["pnpm run db:migrate"]
        D --> E["pnpm run dev"]
    end

    subgraph "Code_Entities"
        B -- "uses" --> CFG["infra/docker-compose.postgres.yml"]
        C -- "executes" --> S1["scripts/setup-casdoor.ts"]
        D -- "executes" --> S2["scripts/database-patch-apply.ts"]
        E -- "executes" --> S3["src/index.ts"]
    end

    subgraph "Infrastructure_State"
        CFG -- "spawns" --> DB["primebrick-postgres-18"]
        CFG -- "spawns" --> IDP["primebrick-casdoor"]
        S2 -- "updates" --> TBL["public.primebrick_database_patch"]
    end

Sources: package.json:6-18, infra/docker-compose.postgres.yml:29-62, AGENTS.md:51-54

Request Flow Overview

When the dev server is running, requests flow through the following layers:

Code
sequenceDiagram
    participant Client as "Client (Browser/Postman)"
    participant Express as "Express Server (src/index.ts)"
    participant Auth as "Auth Middleware (src/modules/auth/)"
    participant Router as "Module Router (e.g., src/modules/customers/)"
    participant DB as "PostgreSQL (Port 5432)"

    Client->>Express: HTTP Request
    Express->>Auth: Validate JWT / RBAC
    Auth->>Express: User Context (req.user)
    Express->>Router: Route Handler
    Router->>DB: SQL Query
    DB-->>Router: Result Set
    Router-->>Client: JSON Response

Sources: package.json:7, AGENTS.md:75-138, src/openapi/openapi.ts:7-22

GitFlow and Versioning

This repository strictly follows GitFlow. AI agents and developers must adhere to the following:

Branching: Never work on main or develop. Create feature/<slug>, release/<version>, or hotfix/<version> branches docs/gitflow.md:18-21.
Version Sync: The package.json version is automatically updated by scripts/version-sync.mjs during the prebuild hook and pre-commit hook package.json:10, .githooks/pre-commit:5.
Commits: AI agents must never commit without explicit user instruction AGENTS.md:5-9.

Sources: docs/gitflow.md:1-21, scripts/version-sync.mjs:69-91, .githooks/pre-commit:1-10

Last modified on July 13, 2026

Export Library GitFlow, Versioning, and CI Hooks