Architecture reference
This page is a reference for how Obics is built. You don’t need it to use Obics, but it’s useful if you self-host, or if you want to understand exactly what happens between clicking “scan” and seeing a recommendation.
System context
Section titled “System context”Obics runs as a set of services alongside a Kafka message bus and a PostgreSQL database (provided by Supabase). It talks to four kinds of external system:
| External system | Direction | Purpose |
|---|---|---|
| Observability vendor (Datadog, Grafana, CloudWatch, Coralogix) | Read | Discover logs, metrics, volume and cardinality; read dashboards and monitors. |
| Source code host (GitHub, GitLab, Azure DevOps) | Read + Write | Clone repos to match telemetry to code; create branches, commits and PRs. |
| LLM provider (Vertex AI / Gemini, OpenAI, Anthropic, Bedrock, Azure) | Outbound | Turn log/metric + code context into optimization suggestions and fix code. |
| Container registry (gcr.io) | Pull | Pull Obics service images on install/update. |
The services
Section titled “The services”| Service | Language | Role |
|---|---|---|
| obics-server | Node/TypeScript (Fastify) | The main API and scan scheduler; everything the frontend talks to. |
| frontend | React (Vite) | The web UI. |
| siftr | Python | Groups raw logs into clusters. |
| matchr | Python | Extracts log patterns from clusters. |
| rmatchr | Rust | Regex-matches log patterns against source code. |
| optir | Python | Generates optimization suggestions for log clusters (via LLM). |
| symmetry | Python | Discovers metrics and their cardinality. |
| meteor | Python | Detects where each metric is emitted in code. |
| outline | Python | Generates optimization recommendations for metrics (via LLM). |
| fixr | Python | Creates the actual code fix and opens the pull request. |
Scan pipelines
Section titled “Scan pipelines”A scan begins when obics-server creates a scan record and publishes one Kafka message. That single message fans out into two pipelines that run in parallel.
Logs pipeline
Section titled “Logs pipeline”obics-server → siftr → matchr → rmatchr → optir- siftr groups logs into clusters, emits
schedule.match_logs. - matchr extracts patterns from clusters, emits
schedule.log_patterns_ready. - rmatchr matches patterns to source code, emits
schedule.match_logs_finished. - optir asks the LLM for an optimization per cluster and stores the suggestions.
Metrics pipeline
Section titled “Metrics pipeline”obics-server → symmetry → meteor → outline- symmetry discovers metrics and cardinality, emits
schedule.metric_analysis. - meteor finds each metric’s source in code, emits
schedule.metric_analysis_finished. - outline asks the LLM which metrics are redundant/reducible and stores the recommendations.
The results of both land in the database and show up on the Optimize Logs and Optimize Metrics pages.
Fix / PR creation
Section titled “Fix / PR creation”Creating a pull request is a separate, user-triggered flow. When you approve a suggestion, obics-server sends a message to fixr, which reads the recommendation from the database, clones your repo, generates the fix with an LLM, creates a branch + commit + PR on your provider, and updates the fix record. A webhook from your source host notifies Obics when the PR merges or closes.
Data isolation
Section titled “Data isolation”Every organization’s data is isolated: rows are keyed by organization and protected by PostgreSQL row-level security, every API call carries a JWT, and repositories are cloned into ephemeral temporary directories that are discarded after each scan. Credentials for external systems live in environment variables, never in the database.
Deployment
Section titled “Deployment”Obics can run:
- Managed cloud (Obics-hosted).
- Self-hosted on Kubernetes, via the provided Helm chart.
- Self-hosted with Docker Compose, which bundles Kafka and Supabase.
Self-hosted deployments show selfhost as their environment in logs.