# Overview

# Overview

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

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

- [.gitignore](.gitignore)
- [AGENTS.md](AGENTS.md)
- [LICENSE](LICENSE)

</details>



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

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

## Child Pages

*   **[Repository Structure & Tech Stack](#1.1)**: Detailed breakdown of the pnpm workspace, TypeScript configuration, and service isolation rules.
*   **[Getting Started & Local Development](#1.2)**: Instructions for environment configuration, dependency installation, and running the development servers.

---