# Getting Started & Local Development

# Getting Started & Local Development

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

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

- [.devin/config.local.json](.devin/config.local.json)
- [.devin/rules/dev-server.md](.devin/rules/dev-server.md)
- [emailsender/.env](emailsender/.env)
- [emailsender/.env.example](emailsender/.env.example)

</details>



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:

```bash
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**
```mermaid
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**
```mermaid
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]()

---