# Repository Structure & Tech Stack

# Repository Structure & Tech Stack

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

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

- [.gitignore](.gitignore)
- [AGENTS.md](AGENTS.md)
- [emailsender/package.json](emailsender/package.json)
- [emailsender/pnpm-lock.yaml](emailsender/pnpm-lock.yaml)
- [emailsender/tsconfig.json](emailsender/tsconfig.json)

</details>



This page describes the organizational layout and foundational technology stack of the Primebrick v3 Microservices repository. The architecture emphasizes service autonomy, strict type safety, and a standardized environment across the monorepo.

## Monorepo Layout & Principles

The repository is structured as a collection of independent microservices. While managed within a single Git repository, each service is designed to be 100% self-contained to prevent tight coupling and "distributed monolith" patterns [AGENTS.md:15-15]().

### Architectural Constraints
*   **Isolation**: Services must not use hardcoded relative imports to access code in other services [AGENTS.md:15-15]().
*   **Shared Code**: Common utilities, types, or SDKs are isolated into dedicated shared packages within the repository, managed via `pnpm` workspaces [AGENTS.md:16-16]().
*   **Self-Containment**: Each service directory (e.g., `emailsender/`) contains its own `package.json`, `tsconfig.json`, and `pnpm-lock.yaml`, ensuring it can be built and deployed independently [emailsender/package.json:1-25](), [emailsender/tsconfig.json:1-24]().

### Directory Structure
The following diagram maps the high-level repository structure to its functional roles:

**Repository Organization**
```mermaid
graph TD
    subgraph "Root Workspace"
        ROOT_GIT[".gitignore"]
        ROOT_AGENTS["AGENTS.md"]
    end

    subgraph "Microservices"
        EMAIL_SENDER["emailsender/"]
        EMAIL_SRC["emailsender/src/"]
        EMAIL_PKG["emailsender/package.json"]
        EMAIL_TS["emailsender/tsconfig.json"]
    end

    subgraph "Governance & Rules"
        DEVIN[".devin/"]
        PLANS["ai-plans/"]
    end

    ROOT_GIT --> EMAIL_SENDER
    EMAIL_SENDER --> EMAIL_SRC
    EMAIL_SENDER --> EMAIL_PKG
    EMAIL_SENDER --> EMAIL_TS
```
Sources: [.gitignore:1-4](), [AGENTS.md:8-16](), [emailsender/package.json:1-11]()

## Technology Stack

The repository utilizes a modern Node.js stack focused on performance and developer velocity.

### Core Stack Components
| Component | Implementation | Purpose |
| :--- | :--- | :--- |
| **Runtime** | Node.js (ES Modules) | Primary execution environment [`"type": "module"` in emailsender/package.json:5-5]() |
| **Language** | TypeScript | Strict typing and modern syntax [AGENTS.md:13-14]() |
| **Package Manager** | pnpm | Efficient dependency management and workspace support [AGENTS.md:13-13]() |
| **Messaging** | NATS | Inter-service communication [emailsender/package.json:13-13]() |
| **Database** | PostgreSQL | Relational data storage via `pg` driver [emailsender/package.json:14-14]() |
| **Development** | tsx | Fast execution of TypeScript without manual transpilation [emailsender/package.json:7-7]() |

### TypeScript Configuration
Services use a standardized `tsconfig.json` that targets `ES2022` and enforces strict type checking.

*   **Target**: `ES2022` [emailsender/tsconfig.json:3-3]()
*   **Module System**: `ESNext` with `bundler` resolution [emailsender/tsconfig.json:4-5]()
*   **Decorators**: Enabled via `experimentalDecorators` and `emitDecoratorMetadata` to support the custom ORM/Entity system [emailsender/tsconfig.json:17-18]()
*   **Strictness**: `strict: true` is mandatory to avoid `any` types [emailsender/tsconfig.json:9-9](), [AGENTS.md:14-14]()

Sources: [emailsender/package.json:12-24](), [emailsender/tsconfig.json:1-23](), [AGENTS.md:13-14]()

## Dependency Management

The repository uses `pnpm` for managing dependencies. Each microservice maintains its own `pnpm-lock.yaml` to ensure reproducible builds [emailsender/pnpm-lock.yaml:1-7]().

### Common Scripts
Standardized scripts are defined in each service's `package.json`:
*   `pnpm run dev`: Uses `tsx watch` for hot-reloading during development [emailsender/package.json:7-7]().
*   `pnpm run build`: Compiles TypeScript to JavaScript in the `dist/` folder [emailsender/package.json:8-8]().
*   `pnpm start`: Runs the compiled service using `node` [emailsender/package.json:10-10]().

### Dependency Isolation
The `.gitignore` at the root ensures that `node_modules` are not committed, maintaining the cleanliness of the monorepo [ .gitignore:1-2]().

**Service Dependency Flow**
```mermaid
graph LR
    subgraph "emailsender/package.json"
        DEP_NATS["nats"]
        DEP_PG["pg"]
        DEP_META["reflect-metadata"]
        DEP_DOTENV["dotenv"]
    end

    subgraph "Development Tools"
        DEV_TSX["tsx"]
        DEV_TS["typescript"]
    end

    DEP_NATS -->|"Messaging"| EMAIL_SERVICE["EmailSender Logic"]
    DEP_PG -->|"Persistence"| EMAIL_SERVICE
    DEP_META -->|"Entity Decorators"| EMAIL_SERVICE
    DEV_TSX -.->|"Dev Loop"| EMAIL_SERVICE
```
Sources: [emailsender/package.json:12-24](), [emailsender/pnpm-lock.yaml:9-39]()

## Configuration & Environment

### Environment Variables
Services must never commit `.env` files. Instead, they provide a `.env.example` file to document required configuration [AGENTS.md:19-19](). Loading is typically handled via the `dotenv` package [emailsender/package.json:15-15]().

### AI Agent Governance
The repository includes specific instructions for AI agents in `AGENTS.md`. Key rules include:
*   **No Auto-Commits**: Agents must wait for explicit user instruction before committing [AGENTS.md:3-6]().
*   **GitFlow**: Mandatory adherence to the GitFlow branching and tagging model [AGENTS.md:28-30]().
*   **Documentation**: All technical prose must be in English [AGENTS.md:10-10]().

Sources: [AGENTS.md:1-31]()

---