Technologies¶
This section explains the principal technologies and their repository-specific roles. The authoritative repository layout and stack summary live in the software structure page. This section explains each tool on its own terms.
At a glance¶
| Technology | Role | Why (in one line) |
|---|---|---|
| Go | 5 services: gateway, passport, fridge, shopping-list, measurement | Small static binaries, strong concurrency, explicit code where resilience and event throughput matter |
| chi | Go HTTP routing | stdlib-compatible router with the middleware the gateway needs |
| pgx + sqlc | Go ↔ Postgres | Hand-written SQL, compile-time-checked Go, no ORM between aggregates and tables |
| franz-go | Go ↔ Kafka | Modern client that keeps consumer-group mechanics explicit |
| TypeScript / Node.js | 3 services: identity, personalization, brand-analytics | Fast iteration where rules and queries dominate; same language as the SPA |
| Fastify | TS HTTP framework | Schema-validated routes on the same JSON Schema technology as the event contracts |
| Kysely | TS ↔ Postgres | Type-safe SQL query builder over explicit migrations |
| @confluentinc/kafka-javascript | TS ↔ Kafka | The repository's librdkafka-backed client |
| PostgreSQL | All persistent state | One instance, seven schemas, seven GRANT-restricted roles, DB-enforced ownership |
| Apache Kafka | Asynchronous integration facts | Event backbone, using KRaft in the local single-node deployment |
| Keycloak | Authentication (OIDC) | Hardened auth for health-adjacent data instead of hand-rolled passwords |
| JSON Schema + quicktype | Cross-language event contracts | One schema source generating both Go and TS types |
| OpenAPI | Per-service HTTP contracts | 'services/ |
| Docker Compose | Local orchestration | The whole fleet with one command |
| SvelteKit | Consumer + brand SPA | Compiler-based static applications served by Caddy |
| Tailwind CSS | Styling | Utility-first styling colocated with components |
| MkDocs Material | This documentation | Versioned docs-as-code with Mermaid diagrams |
| AWS EC2, Caddy, and Cloudflare Pages | App + docs hosting | Containers on one EC2 box; docs deploy separately to Cloudflare Pages |
| Make | Task entry points | One command vocabulary across web, docs, contracts and compose |
| GitHub Actions | Continuous integration | Path-aware cached checks, with the full container journey test scheduled separately |
| Semantic-release | Automated releases | Converts conventional commits into versions, changelog entries, tags and GitHub releases |