Karakoram architecture decisions
These accepted records describe the architecture and its design rationale. Karakoram provides self-hosted PSMDB/PBM orchestration in one Zerops project, without Kubernetes. Decisions are not deployment-specific availability or recovery guarantees.
Decision priorities are: (1) database correctness and recoverability, (2) simple self-hosted operation, (3) maintainable engine/infrastructure separation. Availability guarantees must be limited by the platform’s actual failure domains, not inferred from member count. Each record includes alternatives and accepted failure/operational costs.
| ADR | Decision |
|---|---|
| 0001 | Standalone Zerops-native, in-project control plane |
| 0002 | Go + React/TypeScript; server/agent binary and karactl |
| 0003 | SQLite on Local Storage; one CP replica, state backups and recovery |
| 0004 | Level-triggered Sync, durable operations, cluster locks and SSE |
| 0005 | Engine provider seam inspired by OpenEverest v2, not its K8s interface |
| 0006 | Infrastructure Backend and an owned thin Zerops REST client |
| 0007 | Runtime + volume per mongod; generated pipelines and executable artifacts |
| 0008 | Pinned-CA config pull, member tokens and bounded node supervision |
| 0009 | Stable compact resource names and platform hostname validation |
| 0010 | Curated PSMDB/PBM versions; rolling upgrades and explicit FCV raise |
| 0011 | PBM/S3, schedules, count retention, PITR, restore and clone |
| 0012 | Encrypted secrets, purpose-specific users, keyfile and TLS defaults |
| 0013 | Casbin tuples; local/OIDC auth, API tokens and cookie/CSRF sessions |
| 0014 | Agent exporter, Prometheus endpoint and UI; PMM deferred |
| 0015 | OpenAPI-first generated contracts and x-karakoram-rbac mapping |
| 0016 | No anti-affinity guarantee; heuristic detection and honest warnings |
| 0017 | Optional public TCP, IP/allowlist policy and discovery-safe endpoints |
References and verification
Section titled “References and verification”Use the verification guide for automated test coverage and deployment checks. Recovery, authorization and platform integration should be exercised against your own installation; design rationale alone does not establish those behaviors.
Primary references: Zerops API, Local Storage, public networking, Percona system users, PBM, and OpenEverest provider runtime.
Changing an accepted decision requires updating its consequences, dependent ADRs and affected implementation/docs; preserve numbering. Karakoram is the product name. OpenEverest, Percona and MongoDB appear only as descriptive references, not product branding or endorsement claims.