# 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](/user-guide/microservices/services/emailsender) | `EMAILSENDER` | 3003 | Email provider configuration, template rendering, and email dispatch via Brevo |

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]
  end
  subgraph "Infrastructure"
    NATS[NATS Bus]
    PG[(PostgreSQL)]
  end
  FE -->|HTTP| BE
  BE -->|/ws/emailsender/* proxy| ES
  BE -->|NATS| ES
  ES -->|NATS| NATS
  ES -->|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.

## Next steps

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