Copy page

Microservices

Repository Structure & Tech Stack

Repository Structure & Tech Stack

Relevant source files

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

• .gitignore
• AGENTS.md
• emailsender/package.json
• emailsender/pnpm-lock.yaml
• emailsender/tsconfig.json

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

Code
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

Code
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

---