Copy page

Microservices

Getting Started & Local Development

Getting Started & Local Development

Relevant source files

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

• .devin/config.local.json
• .devin/rules/dev-server.md
• emailsender/.env
• emailsender/.env.example

This page provides a comprehensive guide for setting up the Primebrick v3 Microservices development environment. It covers dependency management, environment configuration, and the specific operational constraints for managing microservice dev servers on Windows.

1. Environment Prerequisites

The repository is structured as a monorepo using pnpm workspaces. Before starting, ensure the following tools are installed and configured:

• Node.js: LTS version.
• pnpm: Used for dependency management and workspace orchestration.
• PostgreSQL: Local instance for microservice data layers.
• NATS Server: Required for the messaging backbone.
• PowerShell: The primary shell used for administrative and diagnostic commands.

The environment is configured to allow specific execution permissions for development tools such as npx, pnpm, and git .devin/config.local.json:1-12.

2. Initial Setup

2.1. Installing Dependencies

From the root of the repository, run the following command to install dependencies for all microservices and shared packages:

Code
pnpm install

2.2. Environment Configuration

Each microservice is self-contained and requires its own .env file. You must copy the .env.example file in each service directory to a new file named .env and update the values accordingly.

Variable	Description	Example Value
DATABASE_URL	PostgreSQL connection string	postgresql://primebrick:primebrick_dev@127.0.0.1:5432/primebrick
DB_SCHEMA	The specific schema for the microservice	emailsender
NATS_URL	Connection URL for the NATS cluster	nats://127.0.0.1:4222
SERVICE_BASE_URL	The local URL where the service listens	http://localhost:3003
BREVO_API_KEY	External provider API key	your_brevo_api_key_here

Sources: emailsender/.env.example:1-9, emailsender/.env:1-9

3. Local Development Workflow

The development workflow relies on high-fidelity local environments where each service runs its own HTTP server and background workers.

3.1. Starting Dev Servers

Microservices typically provide a dev script in their package.json. However, because the repository is designed for high availability and concurrent development, specific rules apply to process management.

3.2. Windows-Specific Dev Server Management

To prevent port conflicts and redundant process execution, developers (and AI agents) must follow a strict "Check-Before-Start" protocol. This is particularly important on Windows environments where process locking can occur.

Dev Server Discovery & Validation Flow

The following diagram illustrates the logic for determining if a microservice dev server should be started.

Title: Dev Server Management Logic

Code
graph TD
    A["Start: Need to run Microservice"] --> B["Identify Default Port from .env or package.json"]
    B --> C["Check listening ports: netstat -ano"]
    C --> D{{"Is port in use?"}}
    D -- "No" --> E["Verify with user and start: pnpm dev"]
    D -- "Yes" --> F["Get PID and Command Line via PowerShell"]
    F --> G{{"Does PID belong to this Microservice?"}}
    G -- "Yes" --> H["Reuse existing process (HMR active)"]
    G -- "No" --> I["ERROR: Port conflict with other app"]
    H --> J["Access existing terminal for logs"]

Sources: .devin/rules/dev-server.md:17-40

Key Diagnostic Commands

When managing local servers, use these commands to inspect the state of the environment:

1. Identify Listening Port: netstat -ano | findstr "LISTENING" | findstr ":<port>" .devin/rules/dev-server.md:24-24
2. Resolve PID to Service: powershell -Command "Get-CimInstance Win32_Process -Filter 'ProcessId=<pid>' | Select-Object ProcessId, CommandLine | Format-List" .devin/rules/dev-server.md:27-27

4. Operational Guardrails

To maintain stability in the monorepo, the following rules are enforced:

• Zero Kill Policy: Never kill a PID holding a microservice port without explicit instruction. The dev servers utilize Hot Module Replacement (HMR) or watch mode, meaning the process already reflects the latest code changes .devin/rules/dev-server.md:12-15.
• Port Fidelity: Microservices must use their assigned default ports (e.g., 3003 for EmailSender) as defined in their configuration .devin/rules/dev-server.md:19-22.
• Cleanup: If a dev server was started specifically for a verification task, it must be stopped upon completion to free resources .devin/rules/dev-server.md:47-48.

5. System Interaction Map

The following diagram bridges the high-level setup tasks with the specific code entities and configurations involved in the local development lifecycle.

Title: Development Environment Entity Map

Code
classDiagram
    class DeveloperEnvironment {
        <<System>>
        +pnpm_workspace
        +nats_server
        +postgres_db
    }

    class MicroserviceConfig {
        <<File>>
        +DATABASE_URL
        +NATS_URL
        +SERVICE_CODE
    }

    class DevServerRules {
        <<Policy>>
        +checkPort()
        +getProcessInfo()
        +noKillPolicy()
    }

    class ExecutionPermissions {
        <<Config>>
        +allow_pnpm
        +allow_powershell
        +allow_git
    }

    DeveloperEnvironment --> MicroserviceConfig : "Reads .env"
    DeveloperEnvironment --> ExecutionPermissions : "Consults config.local.json"
    MicroserviceConfig --* "emailsender/.env" : "defines"
    DevServerRules --* ".devin/rules/dev-server.md" : "defines"
    ExecutionPermissions --* ".devin/config.local.json" : "defines"

Sources: .devin/rules/dev-server.md:5-15, .devin/config.local.json:1-12, emailsender/.env:1-8

---