Copy page

Microservices

Overview

Overview

Relevant source files

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

• .gitignore
• AGENTS.md
• LICENSE

The Primebrick v3 Microservices repository is an independent Git repository containing the distributed microservices that form part of the Primebrick v3 Backend AGENTS.md:8-9. It is designed to host highly decoupled, self-contained services that communicate via well-defined API contracts AGENTS.md:15-17.

The system prioritizes strict architectural isolation, type safety, and standardized workflows for both human developers and AI agents AGENTS.md:1-20.

System Purpose & Architectural Principles

The repository serves as the execution environment for microservices that require autonomy and scalability. The architecture is governed by several core principles:

• Isolation & Autonomy: Each microservice must be 100% self-contained. Hardcoded cross-service relative imports are strictly forbidden AGENTS.md:15.
• Strict Typing: The codebase utilizes strict TypeScript to ensure reliability, explicitly forbidding the use of any and requiring precise interfaces for DTOs, Requests, and Responses AGENTS.md:13-14.
• Asynchronous Communication: Services rely on async/await syntax for all non-blocking operations, with mandatory error handling via try/catch blocks AGENTS.md:18.
• Shared Logic: Common utilities, types, or SDKs are isolated into dedicated shared packages to maintain consistency without violating service boundaries AGENTS.md:16.

System Component Map

The following diagram illustrates how the architectural principles translate into the codebase structure and service interactions.

Diagram: Architectural Component Mapping

Code
graph TD
    subgraph "Repository Boundary [primebrick-v3-microservices]"
        direction TB
        
        subgraph "Shared Infrastructure"
            [Shared_Packages] --> |"Provides Utilities/Types"| [Microservices_Directory]
        end

        subgraph "Microservices_Directory"
            [EmailSender]
            [Future_Service_A]
            [Future_Service_B]
        end

        [EmailSender] -.-> |"Implements"| [API_Contracts]
        [EmailSender] -.-> |"Consumes"| [.env.example]
    end

    [External_Client] --> |"NATS/HTTP"| [EmailSender]

Sources: AGENTS.md:12-19, .gitignore:1-2

Technology Stack

The repository utilizes a modern JavaScript/TypeScript stack managed via a monorepo approach.

Component	Technology	Role
Runtime	Node.js	Primary execution environment AGENTS.md:13
Language	TypeScript	Strict typing and compilation AGENTS.md:13-14
Package Manager	pnpm	Dependency management and workspace orchestration AGENTS.md:13, 25
Web Framework	Fastify / Express	HTTP service layer AGENTS.md:13
Messaging	NATS	Inter-service communication (e.g., in EmailSender)
Configuration	Dotenv	Environment-based configuration via .env.example AGENTS.md:19

For a deep dive into the workspace configuration and package management, see Repository Structure & Tech Stack.

High-Level Workflow

Development in this repository follows a structured lifecycle, particularly regarding Git operations and AI agent interactions.

1. Environment Setup: Dependencies are managed via pnpm install AGENTS.md:25.
2. Development: Services are built using pnpm run build AGENTS.md:26.
3. Governance: AI agents operate under strict guardrails, including a "Never Commit Automatically" policy AGENTS.md:3-6.
4. Version Control: The repository follows the GitFlow branching model AGENTS.md:28-30.

Diagram: Development and Deployment Flow

Code
flowchart LR
    [pnpm_install] --> [pnpm_run_build]
    [pnpm_run_build] --> [Local_Testing]
    [Local_Testing] --> [GitFlow_Branching]
    [GitFlow_Branching] --> [User_Approval_Gate]
    [User_Approval_Gate] --> [git_commit]

Sources: AGENTS.md:3-6, AGENTS.md:21-30

To learn how to set up your environment and run services locally, see Getting Started & Local Development.

Child Pages

• Repository Structure & Tech Stack: Detailed breakdown of the pnpm workspace, TypeScript configuration, and service isolation rules.
• Getting Started & Local Development: Instructions for environment configuration, dependency installation, and running the development servers.

---