Architecture Overview
The SeptemCore Platform-Kernel is a polyglot, industry-agnostic modular backbone built for long-horizon B2B2B SaaS products. Its architecture rests on three guarantees:
- Single entry point — every external request, regardless of source, passes through one API Gateway before touching any domain service.
- Protocol translation — the public contract is REST/OpenAPI; internal communication is gRPC. Clients are decoupled from service topology.
- Primitive composition — seven orthogonal primitives (Auth, Data, Events, Notify, Files, Money, Audit) cover 100 % of module needs without placing any business logic in the kernel.
C4 Level 1 — System Context
Service Inventory
The kernel ships 15 Go backend services and 22 TypeScript packages in a single polyglot monorepo (Go workspace + pnpm workspace + Bazel).
| Layer | Technology | Services / Packages |
|---|---|---|
| Frontend host | Vite 8 · React 19 · Module Federation 2.0 | ui-shell |
| Gateway | Envoy Gateway · Go net/http · chi router | gateway |
| Core primitives | Go · gRPC · OpenAPI 3.1.0 | iam, data-layer, event-bus, notify, files, money, audit |
| Platform services | Go | billing, module-registry, integration-hub, domain-resolver, kernel-cli |
| Shared libs | Go | shared/crypto, shared/mtls, shared/flags, vault |
| SDK | TypeScript strict | sdk-auth, sdk-data, sdk-events, sdk-notify, sdk-files, sdk-money, sdk-audit, sdk-flags, sdk-core, sdk-ui, sdk-testing, sdk-codegen |
Protocol Translation: REST ↔ gRPC
All REST endpoints visible at https://api.septemcore.com/v1/... are
owned by the API Gateway. No Go service exposes REST directly. The
Gateway performs full protocol translation:
Client (REST) → Envoy Gateway (L7 proxy) → Go Gateway Service → gRPC → Domain Service
↓
Client (REST) ← Envoy Gateway ← Go Gateway Service ← gRPC response
This two-layer design gives you:
- OpenAPI request/response validation before any business logic runs.
- Circuit breaking —
sony/gobreakerper-service: 5 errors / 30 s → OPEN 30 s → HALF_OPEN. - Retry safety — single GET retry with 100 ms backoff; POST/PATCH/DELETE
no-retry (idempotency via
Idempotency-Key). - Deadline enforcement — gRPC deadline 5 s (
GRPC_CALL_TIMEOUT_MS); timeout →504 Gateway Timeout.
Inter-Service Communication
Protocol key:
| Protocol | Use case |
|---|---|
gRPC (unary RPCs) | Gateway → core domain services. Typed contracts via Protobuf. |
Kafka | Async domain events. Eight topics: platform.{domain}.events. Partition key: entityId. |
RabbitMQ | Transactional task queues — notify.outgoing.{tenantId}, Integration Hub retries. |
HTTP | Services without a gRPC contract (Notify, Files, Money, Audit in current phase). |
WebSocket | Real-time delivery from Notify Service directly to browser. The only service clients connect to outside the Gateway. |
mTLS (Istio) | All inter-service traffic is mutually authenticated at the transport layer. |
Storage Architecture
| Store | Technology | Primary consumers |
|---|---|---|
| OLTP | PostgreSQL 17 + Row-Level Security | IAM, Data Layer, Money, Billing, Notify, Files, Module Registry, Integration Hub |
| OLAP | ClickHouse | Audit (hot 90 d), Data Layer analytics |
| Cache | Valkey | Gateway (permissions, rate limit), Money, Event Bus, Notify (WS replay buffer) |
| Object | S3-compatible (SeaweedFS / AWS S3) | Files, Audit cold archive (S3 Glacier), Module bundles |
| Secrets | HashiCorp Vault | JWT signing keys, TLS certificates, field-level DEKs |
CDC Pipeline
PostgreSQL (WAL) → Debezium → Kafka → ClickHouse
Latency: < 5 s. Guarantee: at-least-once.
Deduplication: ReplacingMergeTree + FINAL.
Middleware Chain (Gateway)
Every inbound request traverses this ordered chain before reaching any domain service:
Recoverer → RequestID → RealIP → Logging → CORS → JWT Auth
→ Rate Limiting (local token-bucket + Valkey sliding window)
→ OpenAPI Validation → Tenant-Module Check → gRPC Proxy
The Tenant-Module Check step rejects requests for modules not installed
for the requesting tenant (404 Not Found) before any downstream call is
made. The module's existence is not disclosed to unauthorised callers.
Observability
| Signal | Technology |
|---|---|
| Metrics | OpenTelemetry → VictoriaMetrics |
| Logs | slog (structured JSON) |
| Traces | OpenTelemetry — Trace ID propagated on every gRPC and HTTP hop |
| Health | /live, /ready, /health exposed by every service |
Polyglot Stack — Quick Reference
| Runtime | Version | Role |
|---|---|---|
| Go | 1.24 | All backend services |
| Node.js | 24 LTS | SDK packages, UI Shell, build tooling |
| TypeScript | 5.8 | SDK, UI Shell, Docusaurus |
| Rust / Wasm | 1.87 (stable) | Module sandbox isolation layer |
| Docker Desktop | 4.70.0 (Engine 28.1) | Local development environment |
| pnpm | 10.33 | TypeScript monorepo package manager |