From 65eb2e601b741b36388598b9f8adddd7bd8dd3a8 Mon Sep 17 00:00:00 2001 From: Jon Chery Date: Wed, 3 Jun 2026 12:15:20 +0000 Subject: [PATCH] docs(P00): research findings - architecture + personas ---ci--- project: orca phase: 0 milestone: v0.1 status: research personas_active: 5 personas_deactivated: 2 ---/ci--- --- .ciagent/ARCHITECTURE.md | 181 ++++++++++++++++++++++++++++++++++++--- .ciagent/PERSONAS.md | 85 ++++++++++++++++++ 2 files changed, 255 insertions(+), 11 deletions(-) create mode 100644 .ciagent/PERSONAS.md diff --git a/.ciagent/ARCHITECTURE.md b/.ciagent/ARCHITECTURE.md index 290dc73..083fde1 100644 --- a/.ciagent/ARCHITECTURE.md +++ b/.ciagent/ARCHITECTURE.md @@ -1,13 +1,172 @@ -# Architecture: Orchestration Engine +# Architecture: Orca -(Initial Draft) -The system will consist of: -1. **CLI Tool**: The primary interface for users and AI agents. -2. **Controller/Server**: A lightweight daemon managing state and scheduling. -3. **Agent/Worker**: A daemon running on each node to execute workloads. -4. **State Store**: A simple, local-first state persistence mechanism. +## System Overview -## Design Pillars -- Security before features. -- Bug fixes before features. -- NFRs before features. +Orca is a single-binary, offline-first orchestration engine. The system consists of three logical components, all compiled into one `orca` binary and selected via subcommands. + +``` +┌─────────────────────────────────────────────────────────────┐ +│ orca (single binary) │ +├─────────────────────────────────────────────────────────────┤ +│ CLI Layer (Cobra) │ +│ ├── orca version │ +│ ├── orca init │ +│ ├── orca status │ +│ ├── orca node {join,leave,list} │ +│ └── orca job {run,list,stop,logs} │ +├─────────────────────────────────────────────────────────────┤ +│ Daemon Layer (net/http server) │ +│ ├── /healthz (liveness) │ +│ ├── /readyz (readiness) │ +│ ├── /v1/jobs/* (job control API) │ +│ ├── /v1/nodes/* (node registry API) │ +│ └── /v1/tasks/* (task lifecycle API) │ +├─────────────────────────────────────────────────────────────┤ +│ Core Engine │ +│ ├── Node Registry (in-memory + SQLite persistence) │ +│ ├── Task Executor (os/exec with WaitDelay, Go 1.25+) │ +│ ├── Job Scheduler (single-node for v0.1) │ +│ └── Audit Logger (log/slog JSON handler) │ +├─────────────────────────────────────────────────────────────┤ +│ State Store (modernc/sqlite, CGO-free) │ +│ ~/.orca/orca.db │ +└─────────────────────────────────────────────────────────────┘ +``` + +## Component Details + +### 1. CLI Layer (`cmd/orca`, `internal/cli`) +- **Framework**: Cobra (industry standard, familiar to operators) +- **Subcommands**: `version`, `init`, `status`, `node`, `job` +- **Output**: Human-readable by default; `--json` flag for machine consumption +- **Discovery**: All subcommands self-document via Cobra's auto-generated help + +### 2. Daemon Layer (`internal/daemon`) +- **Server**: `net/http` with `http.ServeMux` (no external router for v0.1) +- **TLS**: `crypto/tls` with self-signed certs (mTLS-ready) +- **Ports**: Configurable (default `:8443` for API, `:8080` for health) +- **Graceful Shutdown**: `signal.NotifyContext` with SIGINT/SIGTERM + +### 3. Core Engine (`internal/engine`) +- **Node Registry**: In-memory map of node IDs → metadata, persisted to SQLite +- **Task Executor**: `os/exec.CommandContext` with `WaitDelay` (Go 1.25+) for clean process termination +- **Job Scheduler**: Single-node FIFO queue (multi-node deferred to v0.2+) +- **Audit Logger**: `slog.NewJSONHandler(os.Stderr, ...)` with structured fields + +### 4. State Store (`internal/store`) +- **Driver**: `modernc.org/sqlite` (pure Go, CGO-free) +- **Location**: `~/.orca/orca.db` (user-mode) or `/var/lib/orca/orca.db` (system-mode) +- **Schema**: `nodes`, `jobs`, `tasks`, `audit_log` tables +- **Migrations**: Embedded SQL files, applied on startup + +## Data Model + +### Node +```go +type Node struct { + ID string + Name string + Address string + State string + JoinedAt time.Time + LastSeen time.Time + Metadata map[string]string +} +``` + +### Job +```go +type Job struct { + ID string + Name string + Spec string + Status string + CreatedAt time.Time + StartedAt *time.Time + EndedAt *time.Time +} +``` + +### Task +```go +type Task struct { + ID string + JobID string + Command string + Args []string + Env []string + PID int + ExitCode int + Status string + CreatedAt time.Time + StartedAt *time.Time + EndedAt *time.Time +} +``` + +## Security Architecture + +### Authentication +- **v0.1**: mTLS for all API endpoints (self-signed CA) +- **v0.2+**: Token-based auth as alternative + +### Audit Logging +- All state-changing operations emit structured log records +- Fields: `timestamp`, `actor`, `action`, `resource`, `result`, `error` +- Stored in SQLite `audit_log` table and stderr (JSON) + +### Input Validation +- All CLI inputs validated via Cobra's `Args`/`ValidArgs` functions +- All API inputs validated at handler boundary +- HCL/YAML specs parsed with strict schemas + +## Key Architectural Decisions + +| ID | Decision | Rationale | +|----|----------|-----------| +| AD-001 | Single binary with subcommands | Simpler distribution, aligns with simplicity pillar | +| AD-002 | modernc/sqlite (CGO-free) | Cross-compile friendly, no CGO toolchain needed | +| AD-003 | net/http (no framework) | Stdlib suffices; avoids external router dependency | +| AD-004 | os/exec with WaitDelay (Go 1.25+) | Clean process termination, native to Go | +| AD-005 | Cobra for CLI | Industry standard, familiar to operators | +| AD-006 | slog for logging | Native to Go 1.21+, no external dependency | +| AD-007 | HCL for job specs | Familiar to Nomad/HashiCorp users | +| AD-008 | Single-node scheduling (v0.1) | Multi-node scheduling deferred to v0.2+ | + +## Anti-Patterns (Explicitly Avoided) + +- No controller/agent split (single binary) +- No CRDs / custom resource definitions +- No web UI (CLI-only) +- No service mesh +- No container runtime integration +- No multi-tenancy +- No cloud provider integrations +- No auto-scaling +- No admission controllers +- No complex scheduling algorithms + +## Dependency Map (minimal) + +``` +github.com/spf13/cobra # CLI framework +github.com/hashicorp/hcl/v2 # HCL parser +modernc.org/sqlite # SQLite (pure Go) +github.com/google/uuid # UUID generation +``` + +Total: ~4 direct dependencies. No web framework, no ORM, no RPC framework. + +## Deployment Model + +``` +User Machine Server Node +┌──────────┐ ┌──────────────────┐ +│ orca CLI │─────── mTLS ──────────▶│ orca daemon │ +│ │ │ ├── API server │ +│ │ │ ├── Engine │ +│ │ │ └── SQLite store │ +└──────────┘ └──────────────────┘ +``` + +For v0.1, the CLI and daemon can be the same binary on the same machine. Multi-node is deferred. diff --git a/.ciagent/PERSONAS.md b/.ciagent/PERSONAS.md new file mode 100644 index 0000000..a462cb4 --- /dev/null +++ b/.ciagent/PERSONAS.md @@ -0,0 +1,85 @@ +--- +active_personas: + - lead-developer + - backend-engineer + - data-engineer + - cli-engineer + - security-engineer +deactivated_personas: + - frontend-engineer + - devops-sre +phase_specific: [] +reason: | + Orca is a CLI-first, offline-first orchestration engine with no web UI and + a single-binary distribution model. The persona roster reflects this: + + - lead-developer: coordination and task decomposition + - backend-engineer: core engine and API handlers + - data-engineer: SQLite state store and migrations + - cli-engineer: Cobra subcommands and CLI UX + - security-engineer: mTLS, audit logging, input validation + + Deactivated: + - frontend-engineer: no web UI in v0.1 + - devops-sre: no container/cloud integrations; release flow is + handled by CoreCI (not a persona territory) +--- + +# Personas: Orca + +## Roster + +### lead-developer +- **Domain**: coordination +- **Frameworks**: `cobra` +- **Constraints**: `boundary-enforcement`, `offline-first`, `no-redundant-implementations` +- **Territory**: `**/*.go`, `cmd/**`, `internal/**` +- **Active**: true + +### backend-engineer +- **Domain**: backend +- **Frameworks**: `cobra`, `net/http` +- **Constraints**: `API-first`, `error-handling`, `minimal-dependencies`, `security-first` +- **Territory**: `**/api/**`, `**/*_handler*`, `**/*_handler.go`, `internal/daemon/**` +- **Active**: true + +### data-engineer +- **Domain**: data +- **Frameworks**: `modernc/sqlite` +- **Constraints**: `schema-first`, `migration-safe`, `local-storage-only` +- **Territory**: `**/store/**`, `**/model.go`, `**/migration*`, `migrations/**` +- **Active**: true + +### cli-engineer (custom) +- **Domain**: CLI/UX +- **Frameworks**: `cobra`, `pflag` +- **Constraints**: `discoverable-help`, `consistent-flag-naming`, `human-readable-output`, `machine-readable-json-flag` +- **Territory**: `cmd/**`, `internal/cli/**`, `internal/commands/**` +- **Active**: true +- **Reason**: Orca is CLI-first; this persona ensures CLI quality and discoverability. + +### security-engineer (custom) +- **Domain**: security +- **Frameworks**: `crypto/tls`, `slog` +- **Constraints**: `no-panic-in-production`, `structured-audit-logging`, `no-secret-in-logs`, `input-validation` +- **Territory**: `**/auth/**`, `**/audit/**`, `internal/security/**` +- **Active**: true +- **Reason**: mTLS, audit logging, and input validation are first-class concerns. + +### frontend-engineer +- **Active**: false +- **Reason**: No web UI in v0.1. + +### devops-sre +- **Active**: false +- **Reason**: No container/cloud integrations. Release flow is handled by CoreCI. + +## Territory Enforcement + +- **Mode**: `warn` (per `config.json`) +- **Behavior**: Out-of-territory file changes log a warning but do not block. +- **Rationale**: Allows flexibility during early development; tighten to `strict` post-v0.1. + +## Phase-Specific Personas + +None for v0.1. All personas persist across all 6 phases.