Architecture Overview
cPod is a layered platform. Your application speaks REST to cpod-backend, which enforces auth, policy, and tenancy through the CoreSDK sidecar, then fans out to the appropriate backing stores. The SDK handles OAuth token lifecycle automatically — you write business logic, not plumbing.
Component Map
┌─────────────────────────────────────────────────────┐
│ Your Application │
│ @cpod/sdk · cpod-sdk · cpod-sdk-go │
└───────────────────────┬─────────────────────────────┘
│ HTTPS REST
│ Authorization: Bearer <jwt>
▼
┌─────────────────────────────────────────────────────┐
│ cpod-backend │
│ FastAPI · JWT validation │
│ Extracts tenantId · appId · userId │
│ │
│ Every request middleware (in order): │
│ 1. Extract Bearer token │
│ 2. gRPC AuthService.ValidateToken │
│ 3. gRPC AuthService.Authorize (Rego policy) │
│ 4. gRPC RateLimitService.Check │
│ 5. Handler executes │
│ 6. gRPC AuditService.Emit │
└──────────────┬──────────────────────────────────────┘
│ gRPC [::1]:50051
│ loopback — never internet-facing
▼
┌──────────────────────┐ ┌────────────────────────────────┐
│ CoreSDK Sidecar │ │ Backing Stores │
│ Rust · Tokio · │ │ │
│ tonic · regorus │ │ MongoDB — EDM entities │
│ │ │ Redis — KV / ephemeral │
│ AuthService │ │ MinIO — file blobs │
│ PolicyService │ │ ClickHouse — analytics │
│ AuditService │ │ PostgreSQL — Control Plane │
│ MaskingService │ │ │
│ SecretsService │ └────────────────────────────────┘
│ RateLimitService │
│ TenantService │
└──────────────────────┘The CoreSDK sidecar binds to loopback [::1]:50051 only. It is physically unreachable from outside the host — not just firewalled, but not listening on any routable interface.
Layer Responsibilities
| Layer | Technology | Responsibility |
|---|---|---|
| SDK | TypeScript / Python / Go / .NET | Typed API client, OAuth token lifecycle, retry/backoff |
| cpod-backend | FastAPI (Python) | REST gateway, JWT extraction, request routing, audit emission |
| CoreSDK Sidecar | Rust (Tokio, tonic, regorus) | Token validation, Rego policy enforcement, PII masking, audit chain |
| Backing Stores | MongoDB, Redis, MinIO, ClickHouse, PostgreSQL | Durable storage, indexed by tenantId |
Security Boundaries
| Boundary | Enforcement |
|---|---|
| Internet → cpod-backend | TLS at reverse proxy; HSTS; no plain HTTP |
| cpod-backend → sidecar | Loopback only; mTLS available via CORESDK_TLS_* |
| cpod-backend → Control Plane | Internal network; CPOD_ADMIN_TOKEN required |
| Control Plane → internet | Never exposed; firewall :8080 at infra level |
| Token signatures | RS256 only; alg: none rejected |
| client_secret at rest | Argon2-hashed; raw value never stored |
| Audit log integrity | Hash-chained: each record contains SHA-256(previous_record) |
| PII in logs | MaskingService strips before any storage or response |