docs(P00): research findings - architecture + personas

---ci--- project: orca phase: 0 milestone: v0.1 status: research personas_active: 5 personas_deactivated: 2 ---/ci---
2026-06-03 12:15:20 +00:00
parent 6f34f1794b
commit 65eb2e601b
2 changed files with 255 additions and 11 deletions
@@ -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.
@@ -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.