Copy page

Backend

Project Structure

Project Structure

Relevant source files

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

• .devin/rules/code-guardrails.md
• .devin/rules/file-operations.md
• .devin/rules/temp-files.md
• .devin/rules/workflow.md
• package.json
• src/domain/entities/registry.ts
• src/index.ts
• src/modules/system/service_registry_entity.ts

This page documents the directory layout and architectural conventions of the Primebrick v3 backend. The project follows a modular monolith approach, separating domain logic, infrastructure, and feature modules to ensure maintainability and type safety.

Directory Overview

The codebase is organized into functional areas that separate infrastructure, shared domain logic, and feature-specific modules.

Directory	Purpose	Key Contents
src/modules	Feature-based vertical slices	Routers, DALs, and Entities for Customers, Auth, etc.
src/domain	Shared domain infrastructure	Entity decorators, the global registry, and core interfaces.
src/db	Database infrastructure	Connection pooling and migration management logic.
src/http	Cross-cutting HTTP concerns	Global error handlers and protected router factories.
src/lib	Shared utility libraries	Export engines, delta calculators, and audit services.
scripts	Maintenance & Dev tooling	Database migration runners, seeding scripts, and Casdoor setup.
infra	DevOps & Environment	Docker Compose configurations for local development.
templates	File generation assets	Export templates (XLSX/CSV) and Handlebars files.

Sources: src/index.ts:4-17, src/domain/entities/registry.ts:8-12, package.json:14-18

---

The Module System (src/modules)

Each directory within src/modules represents a self-contained feature area. A standard module typically contains:

• Router: Defines REST endpoints and applies RBAC middleware src/modules/customers/router.ts.
• DAL (Data Access Layer): Handles SQL generation and database interactions.
• Entity: Defines the TypeScript class and PostgreSQL table mapping using decorators src/modules/customers/customer_entity.ts.

Data Flow within a Module

The following diagram illustrates how a request flows through a typical module (e.g., customers).

Request Processing Pipeline

Code
graph TD
    subgraph "Express Layer"
        A["Client Request"] --> B["app.use('/api/v1', ...)"]
        B --> C["rbacHandler(Permission)"]
    end

    subgraph "Module: Customers"
        C --> D["customersRouter"]
        D --> E["CustomersDal"]
        E --> F["Repository<CustomerEntity>"]
    end

    subgraph "Database"
        F --> G[("PostgreSQL")]
    end

    E -.-> H["AuditService"]
    H -.-> G

Sources: src/index.ts:163-181, src/modules/auth/rbac.middleware.js:15

---

Shared Domain & Registry (src/domain)

The src/domain directory contains the core metadata system. The backend uses a decorator-based approach to define database schemas directly in TypeScript classes.

• ENTITY_REGISTRY: A centralized array in src/domain/entities/registry.ts that must include every @Entity class. This registry is consumed by the database patch tooling to compare the code-defined schema against the live database src/domain/entities/registry.ts:1-21.
• Decorators: Located in src/domain/entities/entity-meta.js, these include @Entity, @Column, @Key, and @AuditableField src/modules/system/service_registry_entity.ts:2-9.

Entity-to-Database Mapping

Code
classDiagram
    class ENTITY_REGISTRY {
        +CustomerEntity
        +UserProfileEntity
        +OrganizationEntity
    }
    class EntityDecorator {
        +tableName: string
    }
    class ColumnDecorator {
        +pgType: string
        +nullable: boolean
    }
    ENTITY_REGISTRY ..> EntityDecorator : defines
    EntityDecorator ..> ColumnDecorator : contains

Sources: src/domain/entities/registry.ts:14-20, src/modules/system/service_registry_entity.ts:11-42

---

Database Infrastructure (src/db & db-meta)

Database management is split between runtime connection handling and build-time metadata comparison.

• src/db/pool.js: Manages the pg.Pool instance used by the entire application src/index.ts:12.
• db-meta: (Implicitly referenced via scripts) Stores JSON snapshots of the database schema.
• Scripts:
  • db:meta:compare: Compares ENTITY_REGISTRY against the current DB state package.json:14.
  • db:migrate: Applies SQL patches to synchronize the schema package.json:15.

---

Entry Point and Middleware Pipeline

The application entry point is src/index.ts. It initializes the Express server and mounts global middleware before attaching module routers.

Initialization Sequence

1. Middleware Setup: CORS, JSON parsing, and Cookie Parser are applied src/index.ts:27-29.
2. Health Check: A public /api/v1/health endpoint is mounted to verify Database and IDP (Casdoor) status src/index.ts:154-156.
3. OpenAPI: The openApiRouter is mounted to serve documentation src/index.ts:161.
4. Auth & RBAC: The authRouter handles logins, while makeProtectedRouter provides a guarded space for feature modules src/index.ts:164-180.
5. Role Mapping: On startup, loadRoleMappings() is called to cache RBAC configurations from the database src/index.ts:184.

Sources: src/index.ts:24-189

---

Utility Scripts (scripts/)

The scripts directory contains essential operational tools:

• IDP Setup: setup-casdoor.ts bootstraps the authentication provider package.json:18.
• Data Seeding: seed-customers.ts and truncate-customers.ts manage test data for the CRM module package.json:16-17.
• Dev Ops: kill-port-3001.mjs handles cleanup of hung dev processes package.json:8.

Sources: package.json:6-19

---