Architecture & Operations Guide
This document explains the Rulebricks Helm chart architecture, component interactions, migration flows, and operational considerations, so you can better configure your deployment.
Component Overview
Request Flow
Component Responsibilities
| Component | Purpose | Scaling |
|---|---|---|
| Traefik | Ingress, TLS termination, routing | HPA (2-3 replicas default) |
| App | Web UI, rule editor, management API | Single replica |
| HPS Gateway | API gateway for rule execution | Static replicas |
| HPS Workers | Rule execution engines | KEDA-scaled Deployment |
| Redis | Rule cache, session storage | Single replica with persistence |
| Kafka | Message queue, event streaming | KRaft mode, single node default |
| PostgreSQL | Persistent data storage | Single replica with PVC |
| Vector | Decision log aggregation and forwarding | Static replicas |
| ClickHouse | Decision log queries over object storage | Stateless, single replica default |
| Prometheus | Metrics collection | Single replica, optional remote write |
Decision Log Pipeline
Every rule execution emits a structured decision log. HPS and the app produce entries to the Kafka logs topic; Vector archives them to object storage as NDJSON; ClickHouse queries the archive on demand for the dashboard:
The full walkthrough, values, and custom sink examples live in Decision Logs. Database backups travel to the same bucket under a separate key prefix; see Storage & Backups.
Database Migrations
The chart includes two migration job variants that run automatically based on your configuration.
Migration Decision Tree
Self-Hosted Migration Job
Triggered when: supabase.enabled: true
The job extracts SQL migrations from the Rulebricks app image, waits for PostgreSQL to become ready, and applies them in order. Applied migrations are tracked in a schema_migrations table so re-runs skip what's already done. Jobs run as Helm post-install/post-upgrade hooks and clean themselves up automatically.
Managed Supabase Setup Job
Triggered when: supabase.enabled: false AND global.supabase.accessToken is provided
The job authenticates with your access token via the Supabase CLI, links to your project, pushes configuration (domain, SMTP, auth settings, email templates), applies the schema with supabase db push, and enables SSL enforcement.
If a migration job fails, see Troubleshooting for diagnostics.
DNS and TLS Setup
DNS Record Requirements
| Scenario | Records Needed |
|---|---|
| Self-hosted Supabase | {domain}, supabase.{domain} |
| Managed Supabase | {domain} only |
Scaling Considerations
| Component | Scaling Method | Trigger |
|---|---|---|
| Traefik | HPA | CPU utilization |
| HPS Workers | KEDA | Kafka lag, CPU |
| Vector | Manual | Log volume |
Workers run as a Deployment scaled by KEDA, so scale-out creates pods in parallel and delivers burst capacity in seconds. Worker concurrency is bounded by the partition count of the solution Kafka topic; the full sizing model and the values that control it live in Performance & Scaling.
For diagnostics across all components, see Troubleshooting.