# Microservices Overview


The `primebrick-us-v3` repository contains the distributed microservices that
make up the Primebrick v3 backend. Each microservice is a self-contained
sub-folder with its own `src/`, `package.json`, `Dockerfile`, `db-meta/`, and
`terraform/` configuration.

## Tech stack

- **Runtime:** Bun (dev with `--hot` reload, prod with `bun dist/index.js`)
- **Language:** TypeScript® (strict mode)
- **HTTP:** Node.js® HTTP server via `@primebrick/sdk`'s `createHttpServer`
- **Messaging:** NATS™ (via `@primebrick/sdk`'s `NatsClient`)
- **Database:** PostgreSQL® (via `@primebrick/dal-pg`)
- **Package manager:** pnpm
- **Templates:** Handlebars (where applicable)

## Service catalog

| Service | Code | Port | Description |
|---------|------|------|-------------|
| [EmailSender](/microservices/dev/services/emailsender) | `emailsender` | 3003 | Email provider configuration, template rendering, and email dispatch via Brevo™ |
| [AI](/microservices/dev/services/ai) | `ai` | 3004 | AI assistant — chat streaming (SSE), conversation lifecycle, docs knowledge-base search, embeddings, `ai_model`/`ai_cerebellum` entity catalog |
| [Webhook](/microservices/dev/services/webhook) | `webhook` | 3005 | Inbound webhook ingress — forwards requests verbatim to the target microservice via JetStream, registry-driven routing |
| [JobHandler](/microservices/dev/services/job-handler) | `job` | 3006 | Job scheduling, governance, and execution observability — NATS JetStream native scheduler, business `job_rules`, run history |
| [CRM](/microservices/dev/services/crm) | `crm` | 3007 | CRM module — module-ownership case study: nav, route census and translations declared at service registration |

> **Port source of truth**: ports are seeded in each service's own
> `db-meta/patches/` (`config_entries` key `http_port`) — the table above
> mirrors those seeds. There is no env var or config file for ports.

New microservices are added as new top-level sub-folders. Each must contain
a `package.json` with a `name` starting with `primebrick-` and a `src/index.ts`
entry point.

## Architecture at a glance

<Mermaid chart={`flowchart TB
  subgraph "Frontend"
    FE[primebrick-fe-v3]
  end
  subgraph "Backend"
    BE[primebrick-be-v3]
    MCP[MCP Server]
  end
  subgraph "Microservices (this repo)"
    ES[EmailSender :3003]
    AI[AI :3004]
    WH[Webhook :3005]
    JH[JobHandler :3006]
    CRM[CRM :3007]
  end
  subgraph "Infrastructure"
    NATS[NATS Bus]
    PG[(PostgreSQL)]
  end
  FE -->|HTTP| BE
  BE -->|/ws/:code/* proxy| ES & AI & WH & JH & CRM
  ES & AI & WH & JH & CRM -->|NATS| NATS
  ES & AI & WH & JH & CRM -->|SQL| PG
  BE -->|SQL| PG
`} />

The Backend (BE) acts as the API gateway. The Frontend (FE) never calls
microservices directly — all HTTP traffic goes through the BE's
`/ws/:serviceCode/*` proxy. Inter-service async communication uses NATS™
subjects.

## Quick start

Each microservice is a self-contained sub-folder with its own `package.json`,
`src/`, `Dockerfile`, `db-meta/`, and `terraform/`. To run EmailSender
locally:

```bash
cd emailsender
pnpm install
pnpm run build
bun dist/index.js          # starts on port 3003 (from config table)
```

The microservice reads its NATS™ URL, HTTP port, and service code from the
`config_entries` table at startup via the SDK's `ConfigLoader` — not from env vars.
The only required env vars are `DATABASE_URL` and `DATABASE_SCHEMA` (the
service's owned PG schema — closed-set validated by `assertDbEnv()`).

To verify the service is running:

```bash
curl http://localhost:3003/health
# → { "ok": true, "service": "emailsender", "version": "...", "url": "..." }

curl http://localhost:3003/api/v1/openapi.json | head -20
# → { "openapi": "3.x.x", "info": { "title": "EmailSender", ... } }
```

From the Frontend, the same service is reached through the BE proxy:

```bash
curl http://localhost:3001/ws/emailsender/api/v1/entities/provider/list
# → { "rows": [...], "total": 0, "page": 1, "page_size": 20 }
```

To apply database migrations for a microservice:

```bash
cd emailsender && pnpm run db:migrate
```

## Next steps

- [Architecture](/microservices/dev/architecture) — NATS™ bus, BE proxy, SDK lifecycle
- [Conventions](/microservices/dev/conventions) — API path conventions, data model rules
- [EmailSender](/microservices/dev/services/emailsender) — Email sending microservice