| name | meticulous-system-architecture |
| description | Use when reasoning about control plane vs agents, NATS or gRPC boundaries, org/project/pipeline domain model, phased roadmap, or locating detailed design plans under .cursor/plans. |
Meticulous system architecture
Overview
Operators use the web UI and REST API against PostgreSQL. Agents do not accept inbound control-plane connections; they dial out to the controller over gRPC. The controller uses NATS (often JetStream) for work dispatch and S3-compatible storage for artifacts and related binary data.
Core ideas
- Pub/sub job dispatch — Agents subscribe to NATS subjects (e.g. by pool tags). Egress-only networking for agents.
- Per-job PKI for secrets — Job-scoped key material; server encrypts secrets for the agent; no plaintext secrets on the wire for that hop. Details:
meticulous-agent-security-invariants.
- Custom execution engine — In-repo engine (DAG, steps, caching, artifacts); not Tekton-centric.
- Reusable workflows — Pipelines compose versioned workflows at global (platform) or project scope.
- External secrets preferred — First-class Vault/OpenBao, AWS Secrets Manager, Kubernetes secrets; built-in storage discouraged by product direction.
Domain hierarchy (summary)
Organization (tenant) → Project → Pipelines (Jobs as DAG, Steps) with scoped Secrets, Variables, Triggers; plus global or project reusable workflows. Pipeline YAML references workflows such as workflow: global/... or workflow: project/....
Deeper reference
Frontend stack for the web UI is SvelteKit and Svelte 5 under frontend/ (not React).
Keywords
NATS, JetStream, gRPC, controller, met-agent, Axum, PostgreSQL, S3, DAG, reusable workflows, control plane, egress-only.
