Copy page

Getting Started

Infrastructure

Infrastructure Overview

Primebrick runs as a set of independent services connected via HTTP and NATS™ messaging. Everything is Dockerized for local development and deployable to any cloud via Terraform.

Components

External Clients

Component	Protocol	Description
Browser	HTTP	Admin UI accessed via SvelteKit™ frontend
API Clients	HTTP	SDK consumers, curl, integrations calling /api/v1/

Identity Provider — Casdoor™

Casdoor™ provides OAuth2 / OIDC authentication. The backend validates JWT tokens issued by Casdoor™ and maps IDP roles to internal RBAC permissions.

• Port: 8000
• Protocol: HTTP (OAuth2 / OIDC)
• Role: Issues JWT tokens, manages users and roles

Frontend — SvelteKit™

The admin frontend is a SvelteKit™ application. It communicates only with the backend API — never directly with microservices.

• Port: 5173
• Protocol: HTTP
• Talks to: Backend (/api/v1/)

Backend — Express API (System Brick)

The central backend is the "SYSTEM" virtual brick. It handles authentication, RBAC, service registry, and proxies requests to microservices.

• Port: 3001
• Base path: /api/v1/
• Modules: Auth, RBAC, Service Registry, Proxy, OpenAPI
• Talks to: Casdoor™ (OAuth), PostgreSQL® (via DAL), NATS™ (subscribe), Microservices (HTTP proxy)

Messaging — NATS™

NATS™ is the messaging backbone for inter-service communication. Microservices publish lifecycle events (register, heartbeat, unregister) and the backend subscribes to update the service registry.

• Port: 4222 (client connections)
• Monitoring: 8222
• Protocol: NATS protocol
• Patterns: Pub/Sub for lifecycle events, Request/Reply for inter-service calls

Microservices

Each microservice is an independent, Dockerized service with its own lifecycle, database schema, and port.

• Port: Dynamic (loaded from config)
• Protocol: HTTP for direct calls, NATS™ for lifecycle events
• Self-registration: Via @primebrick/sdk ServiceRegistrar
• OpenAPI spec: Served at /api/v1/openapi.json
• Aggregated spec: Backend merges all online specs at /api/v1/openapi/aggregated.json (microservice paths prefixed with /ws/:serviceCode)
• Talks to: PostgreSQL® (via DAL), NATS™ (via SDK), Backend (via proxy)

Data Layer — PostgreSQL® + pgvector

PostgreSQL® is the single data store for all services. pgvector extension enables vector similarity search for AI features.

• Port: 5432
• Protocol: PostgreSQL® wire protocol
• Extensions: pgvector
• Access: All services connect via @primebrick/dal-pg

Cache & Presence — Redis™

Redis™ is a mandatory infrastructure component. It is not optional or best-effort — the /health endpoint returns 503 when Redis is down, and Redis-dependent features hard-fail with REDIS_UNAVAILABLE (503).

• Port: 6379
• Protocol: RESP (Redis protocol)
• Used by: Backend (cache, presence, WebAuthn session relay, keyspace listener), Microservices (entity cache via @Cached() decorator)
• Mandatory for:
  • WebAuthn passkey signin — session cookie relay between begin/finish calls (hard-fail without Redis)
  • Entity caching — @Cached() decorator + withCache() wrapper (DB-only fallback, but performance degradation at scale)
  • Real-time presence — collaboration SSE presence store (presence disabled without Redis)
  • Cache invalidation — cross-pod config/role-mapping/api-key cache sharing (stale data without Redis)
• Health check: /health includes redis: { ok, version } — actual PING command on every probe
• Startup: BE retries Redis connection every 5s if unreachable (same pattern as DB/role mappings)

Shared Libraries

@primebrick/sdk

The SDK is the shared toolkit used by every microservice. It provides:

• ServiceRegistrar — registration + heartbeats via NATS™
• NatsClient — NATS™ connection management
• createHttpServer — HTTP server scaffolding
• HealthCheck — liveness/readiness endpoints
• ConfigLoader — config loading from database
• requireEnv — environment variable validation
• GracefulShutdown — cleanup on termination

@primebrick/dal-pg

The DAL is the shared data access library. It provides:

• Dal gateway — manages pg.Pool, connection lifecycle
• Repository — type-safe CRUD from TypeScript® entity metadata
• Type parsers — INT8 → bigint, NUMERIC → number/string
• Per-connection settings — search_path, statement_timeout, application_name
• Transaction support — dal.withClient(fn, options?)

Data Flow

Request flow (client → database)

Service lifecycle (startup → heartbeat → shutdown)

Deployment

Docker® (local development)

Code
# docker-compose.postgres.yml
services:
  postgres:
    image: postgres:18-bookworm
    ports: ["5432:5432"]
  casdoor:
    image: casbin/casdoor:3.75.0
    ports: ["8000:8000"]
  nats:
    image: nats:latest  # JetStream enabled
    ports: ["4222:4222", "8222:8222"]
  redis:
    image: redis:8-alpine
    ports: ["6379:6379"]

Terraform (production)

Each microservice includes Terraform templates for cloud deployment:

• terraform/main.tf — resource definitions
• terraform/variables.tf — configurable parameters
• terraform/scripts/deploy.{ps1,sh} — cross-platform deploy scripts
• terraform/scripts/find-available-port.{ps1,sh} — dynamic port allocation

Ports Summary

Component	Default Port	Protocol
Frontend (SvelteKit™)	5173	HTTP
Backend (Express)	3001	HTTP
Casdoor™ (OAuth)	8000	HTTP
PostgreSQL®	5432	PostgreSQL®
NATS™ (client)	4222	NATS™
NATS™ (monitoring)	8222	HTTP
Microservices	Dynamic	HTTP

Next steps

• Architecture — high-level architectural overview
• Quick Start — get running locally
• Microservice Standard — how to build a compliant microservice