docs: add hexagonal architecture implementation plan
Comprehensive plan covering: - Current state assessment (what's implemented vs stubbed) - Risk analysis for SSE, executor, auth, and database - Hexagonal architecture refactoring strategy - Domain model, ports, and adapters design - 6 implementation epics with effort estimates - Security hardening priorities - Success criteria for v0.6-v0.8 Key findings: - Core functionality IS working (handlers, SSE, auth, executor) - Missing: tests, rate limiting, command sanitization - Architecture is layered, not hexagonal (testability issue) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
jordan
parent
2fc8454b8c
commit
74643f0692
604
IMPLEMENTATION_PLAN.md
Normal file
604
IMPLEMENTATION_PLAN.md
Normal file
@ -0,0 +1,604 @@
|
||||
# rdev-api Implementation Plan
|
||||
|
||||
> Refactoring to Hexagonal Architecture + Production Hardening
|
||||
|
||||
## Current State Assessment
|
||||
|
||||
### What's Already Implemented (Working)
|
||||
|
||||
| Component | Status | Lines | Notes |
|
||||
|-----------|--------|-------|-------|
|
||||
| HTTP Handlers | ✅ Complete | 611 | All 6 project endpoints + 4 key endpoints |
|
||||
| Executor | ✅ Complete | 183 | kubectl exec with streaming output |
|
||||
| SSE Streaming | ✅ Complete | ~100 | Channel-based pub/sub with heartbeats |
|
||||
| Auth Service | ✅ Complete | 561 | Keys, scopes, middleware, expiration |
|
||||
| Database | ✅ Complete | 173 | Auto-migrations, connection pooling |
|
||||
| API Framework | ✅ Complete | 298 | Response envelopes, OpenAPI, chi router |
|
||||
|
||||
### What's Missing
|
||||
|
||||
| Component | Priority | Impact |
|
||||
|-----------|----------|--------|
|
||||
| Tests | HIGH | No unit or integration tests |
|
||||
| Dynamic Projects | MEDIUM | Hardcoded to 2 projects |
|
||||
| Project Access Control | HIGH | Middleware exists but unused |
|
||||
| Rate Limiting | HIGH | No request throttling |
|
||||
| Metrics | MEDIUM | No Prometheus/observability |
|
||||
| Retry Logic | MEDIUM | No transient failure recovery |
|
||||
| Command Cancellation | LOW | No explicit kill mechanism |
|
||||
|
||||
---
|
||||
|
||||
## Architecture Analysis
|
||||
|
||||
### Current: Layered (Not Hexagonal)
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────┐
|
||||
│ HTTP Layer (handlers/) │
|
||||
│ - Chi router, request parsing, responses │
|
||||
├─────────────────────────────────────────────┤
|
||||
│ Service Layer (auth/, executor/) │
|
||||
│ - Business logic mixed with infrastructure │
|
||||
├─────────────────────────────────────────────┤
|
||||
│ Data Layer (db/, projects/) │
|
||||
│ - Direct PostgreSQL, kubectl calls │
|
||||
└─────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**Problems:**
|
||||
1. Handlers directly depend on concrete implementations
|
||||
2. No interfaces for testability
|
||||
3. Executor calls kubectl directly (hard to test)
|
||||
4. Registry hardcodes project definitions
|
||||
5. No domain model - just request/response structs
|
||||
|
||||
### Target: Hexagonal Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────┐
|
||||
│ Domain (Core) │
|
||||
│ │
|
||||
│ - Project │
|
||||
│ - Command │
|
||||
│ - APIKey │
|
||||
│ - CommandResult │
|
||||
│ - Stream │
|
||||
└─────────────────────┘
|
||||
▲
|
||||
┌──────────────┼──────────────┐
|
||||
│ │ │
|
||||
┌─────┴─────┐ ┌─────┴─────┐ ┌─────┴─────┐
|
||||
│ Ports │ │ Ports │ │ Ports │
|
||||
│ (Inbound) │ │ (Outbound)│ │ (Outbound)│
|
||||
└───────────┘ └───────────┘ └───────────┘
|
||||
│ │ │
|
||||
┌─────┴─────┐ ┌─────┴─────┐ ┌─────┴─────┐
|
||||
│ Adapters │ │ Adapters │ │ Adapters │
|
||||
│ (HTTP) │ │ (kubectl) │ │ (Postgres)│
|
||||
└───────────┘ └───────────┘ └───────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Risk Analysis: What Could Go Wrong
|
||||
|
||||
### SSE Streaming Risks
|
||||
|
||||
| Risk | Severity | Mitigation |
|
||||
|------|----------|------------|
|
||||
| **Memory leak from abandoned streams** | HIGH | Stream cleanup after 30s (implemented), but no max stream limit |
|
||||
| **Buffer overflow** | MEDIUM | 100-event buffer with non-blocking send (drops events) |
|
||||
| **Client reconnection gaps** | MEDIUM | No event replay - missed events are lost |
|
||||
| **Proxy buffering** | MEDIUM | Headers set correctly, but nginx/cloudflare may still buffer |
|
||||
| **Connection hijacking** | LOW | No stream authentication after initial auth |
|
||||
|
||||
**Current Implementation Strengths:**
|
||||
- Heartbeat keeps connection alive (30s)
|
||||
- Context cancellation on client disconnect
|
||||
- Non-blocking sends prevent goroutine leaks
|
||||
- Completion event triggers cleanup
|
||||
|
||||
**Gaps to Address:**
|
||||
1. No max concurrent streams per user
|
||||
2. No event ID for resumability (Last-Event-ID)
|
||||
3. No backpressure signaling to clients
|
||||
4. Stream state not persisted (restart loses all)
|
||||
|
||||
### Executor Risks
|
||||
|
||||
| Risk | Severity | Mitigation |
|
||||
|------|----------|------------|
|
||||
| **kubectl timeout** | HIGH | 10-minute context timeout (implemented) |
|
||||
| **Pod not found** | HIGH | Registry refresh, but no retry |
|
||||
| **Large output OOM** | MEDIUM | 1MB line buffer, but no total limit |
|
||||
| **Command injection** | HIGH | Args passed directly to kubectl (needs validation) |
|
||||
| **Zombie processes** | MEDIUM | Context cancellation, but no kill -9 |
|
||||
|
||||
**Current Implementation Strengths:**
|
||||
- Context-based cancellation
|
||||
- Line-by-line streaming (not buffering full output)
|
||||
- Separate stdout/stderr handling
|
||||
- Exit code capture
|
||||
|
||||
**Gaps to Address:**
|
||||
1. No command sanitization (shell injection risk)
|
||||
2. No output size limit (could fill memory)
|
||||
3. No concurrent command limit per project
|
||||
4. No pod health check before exec
|
||||
|
||||
### Auth Risks
|
||||
|
||||
| Risk | Severity | Mitigation |
|
||||
|------|----------|------------|
|
||||
| **Timing attack on key comparison** | MEDIUM | Using crypto/subtle (verify!) |
|
||||
| **Key enumeration** | LOW | Generic "invalid key" errors |
|
||||
| **Revocation delay** | MEDIUM | No cache - checks DB each request |
|
||||
| **Admin key exposure** | HIGH | Env var, but logged if DEBUG |
|
||||
|
||||
**Current Implementation Strengths:**
|
||||
- SHA-256 hashed keys (never stored plain)
|
||||
- Scoped permissions
|
||||
- Expiration enforcement
|
||||
- last_used_at audit trail
|
||||
|
||||
**Gaps to Address:**
|
||||
1. Verify constant-time comparison is used
|
||||
2. Add key rotation support
|
||||
3. Add IP allowlisting per key
|
||||
4. Rate limit failed auth attempts
|
||||
|
||||
### Database Risks
|
||||
|
||||
| Risk | Severity | Mitigation |
|
||||
|------|----------|------------|
|
||||
| **Connection pool exhaustion** | MEDIUM | Fixed at 10 max connections |
|
||||
| **Migration failure on startup** | HIGH | Fails fast (correct), but no rollback |
|
||||
| **Query timeout** | MEDIUM | No explicit query timeouts set |
|
||||
|
||||
---
|
||||
|
||||
## Hexagonal Refactoring Plan
|
||||
|
||||
### Phase 1: Define Domain Model
|
||||
|
||||
Create pure domain types with no external dependencies.
|
||||
|
||||
```go
|
||||
// internal/domain/project.go
|
||||
package domain
|
||||
|
||||
type ProjectID string
|
||||
type CommandID string
|
||||
|
||||
type Project struct {
|
||||
ID ProjectID
|
||||
Name string
|
||||
Description string
|
||||
PodName string
|
||||
Status ProjectStatus
|
||||
Workspace string
|
||||
}
|
||||
|
||||
type ProjectStatus string
|
||||
|
||||
const (
|
||||
ProjectStatusRunning ProjectStatus = "running"
|
||||
ProjectStatusPending ProjectStatus = "pending"
|
||||
ProjectStatusFailed ProjectStatus = "failed"
|
||||
ProjectStatusNotFound ProjectStatus = "not_found"
|
||||
)
|
||||
```
|
||||
|
||||
```go
|
||||
// internal/domain/command.go
|
||||
package domain
|
||||
|
||||
type CommandType string
|
||||
|
||||
const (
|
||||
CommandTypeClaude CommandType = "claude"
|
||||
CommandTypeShell CommandType = "shell"
|
||||
CommandTypeGit CommandType = "git"
|
||||
)
|
||||
|
||||
type Command struct {
|
||||
ID CommandID
|
||||
ProjectID ProjectID
|
||||
Type CommandType
|
||||
Args []string
|
||||
StartedAt time.Time
|
||||
}
|
||||
|
||||
type CommandResult struct {
|
||||
CommandID CommandID
|
||||
ExitCode int
|
||||
DurationMs int64
|
||||
Error error
|
||||
}
|
||||
|
||||
type OutputLine struct {
|
||||
Stream string // "stdout" or "stderr"
|
||||
Line string
|
||||
Time time.Time
|
||||
}
|
||||
```
|
||||
|
||||
### Phase 2: Define Ports (Interfaces)
|
||||
|
||||
```go
|
||||
// internal/port/project_repository.go
|
||||
package port
|
||||
|
||||
type ProjectRepository interface {
|
||||
List(ctx context.Context) ([]domain.Project, error)
|
||||
Get(ctx context.Context, id domain.ProjectID) (*domain.Project, error)
|
||||
RefreshStatus(ctx context.Context) error
|
||||
}
|
||||
```
|
||||
|
||||
```go
|
||||
// internal/port/command_executor.go
|
||||
package port
|
||||
|
||||
type CommandExecutor interface {
|
||||
Execute(ctx context.Context, cmd *domain.Command, onOutput func(domain.OutputLine)) (*domain.CommandResult, error)
|
||||
Cancel(ctx context.Context, cmdID domain.CommandID) error
|
||||
}
|
||||
```
|
||||
|
||||
```go
|
||||
// internal/port/stream_publisher.go
|
||||
package port
|
||||
|
||||
type StreamPublisher interface {
|
||||
Subscribe(streamID string) (<-chan StreamEvent, func())
|
||||
Publish(streamID string, event StreamEvent)
|
||||
Close(streamID string)
|
||||
}
|
||||
|
||||
type StreamEvent struct {
|
||||
Type string
|
||||
Data map[string]any
|
||||
}
|
||||
```
|
||||
|
||||
```go
|
||||
// internal/port/api_key_repository.go
|
||||
package port
|
||||
|
||||
type APIKeyRepository interface {
|
||||
Create(ctx context.Context, key *domain.APIKey) error
|
||||
GetByHash(ctx context.Context, hash string) (*domain.APIKey, error)
|
||||
List(ctx context.Context) ([]domain.APIKey, error)
|
||||
Revoke(ctx context.Context, id uuid.UUID) error
|
||||
UpdateLastUsed(ctx context.Context, id uuid.UUID) error
|
||||
}
|
||||
```
|
||||
|
||||
### Phase 3: Create Adapters
|
||||
|
||||
```
|
||||
internal/
|
||||
├── adapter/
|
||||
│ ├── http/ # HTTP handlers (inbound adapter)
|
||||
│ │ ├── project_handler.go
|
||||
│ │ ├── key_handler.go
|
||||
│ │ └── middleware.go
|
||||
│ ├── kubernetes/ # kubectl executor (outbound adapter)
|
||||
│ │ └── executor.go
|
||||
│ ├── postgres/ # Database (outbound adapter)
|
||||
│ │ ├── project_repo.go
|
||||
│ │ └── key_repo.go
|
||||
│ └── memory/ # In-memory (for testing)
|
||||
│ ├── project_repo.go
|
||||
│ └── stream_publisher.go
|
||||
```
|
||||
|
||||
### Phase 4: Wire with Dependency Injection
|
||||
|
||||
```go
|
||||
// cmd/rdev-api/main.go
|
||||
|
||||
func main() {
|
||||
// Create adapters
|
||||
db := postgres.NewDB(cfg)
|
||||
projectRepo := postgres.NewProjectRepository(db)
|
||||
keyRepo := postgres.NewAPIKeyRepository(db)
|
||||
executor := kubernetes.NewExecutor(cfg.Namespace)
|
||||
streamPub := memory.NewStreamPublisher()
|
||||
|
||||
// Create services (use cases)
|
||||
projectSvc := service.NewProjectService(projectRepo, executor, streamPub)
|
||||
keySvc := service.NewAPIKeyService(keyRepo)
|
||||
|
||||
// Create HTTP handlers
|
||||
projectHandler := http.NewProjectHandler(projectSvc)
|
||||
keyHandler := http.NewKeyHandler(keySvc)
|
||||
|
||||
// Wire routes
|
||||
router := chi.NewRouter()
|
||||
projectHandler.Mount(router)
|
||||
keyHandler.Mount(router)
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Implementation Tasks
|
||||
|
||||
### Epic 1: Testing Foundation (Priority: CRITICAL)
|
||||
|
||||
Without tests, refactoring is dangerous.
|
||||
|
||||
| Task | Effort | Files |
|
||||
|------|--------|-------|
|
||||
| 1.1 Add test utilities (fixtures, mocks) | 2h | `internal/testutil/` |
|
||||
| 1.2 Unit tests for auth/keys.go | 2h | `internal/auth/keys_test.go` |
|
||||
| 1.3 Unit tests for auth/service.go | 3h | `internal/auth/service_test.go` |
|
||||
| 1.4 Unit tests for executor | 2h | `internal/executor/executor_test.go` |
|
||||
| 1.5 Integration tests for handlers | 4h | `internal/handlers/*_test.go` |
|
||||
| 1.6 E2E test with docker-compose | 4h | `tests/e2e/` |
|
||||
|
||||
**Test Strategy:**
|
||||
- Unit tests: Mock all dependencies via interfaces
|
||||
- Integration tests: Use real postgres (docker), mock kubectl
|
||||
- E2E tests: Full stack with test k8s cluster or kind
|
||||
|
||||
### Epic 2: Security Hardening (Priority: HIGH)
|
||||
|
||||
| Task | Effort | Risk Mitigated |
|
||||
|------|--------|----------------|
|
||||
| 2.1 Command sanitization | 2h | Shell injection |
|
||||
| 2.2 Rate limiting middleware | 3h | DoS, brute force |
|
||||
| 2.3 Concurrent command limit | 2h | Resource exhaustion |
|
||||
| 2.4 Output size limit | 1h | OOM |
|
||||
| 2.5 Constant-time key comparison audit | 1h | Timing attacks |
|
||||
|
||||
**Command Sanitization Rules:**
|
||||
```go
|
||||
// Disallow these in shell commands:
|
||||
var dangerousPatterns = []string{
|
||||
";", "&&", "||", "|", "`", "$(", // Command chaining
|
||||
">", ">>", "<", // Redirects
|
||||
"rm -rf", "dd if=", // Destructive
|
||||
}
|
||||
```
|
||||
|
||||
### Epic 3: Hexagonal Refactoring (Priority: MEDIUM)
|
||||
|
||||
| Task | Effort | Impact |
|
||||
|------|--------|--------|
|
||||
| 3.1 Create domain package | 2h | Foundation |
|
||||
| 3.2 Define port interfaces | 2h | Testability |
|
||||
| 3.3 Extract kubernetes adapter | 3h | Mockable executor |
|
||||
| 3.4 Extract postgres adapter | 3h | Mockable repos |
|
||||
| 3.5 Create memory adapter (tests) | 2h | Fast tests |
|
||||
| 3.6 Refactor handlers to use ports | 4h | Decoupling |
|
||||
| 3.7 Add dependency injection | 2h | Flexibility |
|
||||
|
||||
### Epic 4: SSE Improvements (Priority: MEDIUM)
|
||||
|
||||
| Task | Effort | Benefit |
|
||||
|------|--------|---------|
|
||||
| 4.1 Add Last-Event-ID support | 3h | Resumable connections |
|
||||
| 4.2 Max streams per user | 2h | Resource control |
|
||||
| 4.3 Event replay buffer | 4h | Catch missed events |
|
||||
| 4.4 Backpressure detection | 2h | Client health |
|
||||
|
||||
**Event ID Format:**
|
||||
```
|
||||
event: output
|
||||
id: cmd-pantheon-001:42
|
||||
data: {"line": "Building..."}
|
||||
```
|
||||
|
||||
### Epic 5: Observability (Priority: MEDIUM)
|
||||
|
||||
| Task | Effort | Benefit |
|
||||
|------|--------|---------|
|
||||
| 5.1 Prometheus metrics | 3h | Monitoring |
|
||||
| 5.2 Request tracing (OpenTelemetry) | 4h | Debugging |
|
||||
| 5.3 Structured logging improvements | 2h | Log analysis |
|
||||
| 5.4 Health check enhancements | 1h | K8s probes |
|
||||
|
||||
**Key Metrics:**
|
||||
```
|
||||
rdev_commands_total{project, type, status}
|
||||
rdev_command_duration_seconds{project, type}
|
||||
rdev_active_streams{project}
|
||||
rdev_auth_failures_total{reason}
|
||||
rdev_api_request_duration_seconds{endpoint, method, status}
|
||||
```
|
||||
|
||||
### Epic 6: Dynamic Project Discovery (Priority: LOW)
|
||||
|
||||
| Task | Effort | Benefit |
|
||||
|------|--------|---------|
|
||||
| 6.1 K8s label-based discovery | 3h | No hardcoding |
|
||||
| 6.2 Project config from ConfigMap | 2h | External config |
|
||||
| 6.3 Watch for pod changes | 3h | Real-time updates |
|
||||
|
||||
**Label Convention:**
|
||||
```yaml
|
||||
metadata:
|
||||
labels:
|
||||
rdev.orchard9.ai/project: "true"
|
||||
rdev.orchard9.ai/name: "pantheon"
|
||||
rdev.orchard9.ai/description: "Go API backend"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Implementation Order
|
||||
|
||||
```
|
||||
Week 1: Testing Foundation
|
||||
├── 1.1 Test utilities
|
||||
├── 1.2 Auth key tests
|
||||
├── 1.3 Auth service tests
|
||||
└── 1.4 Executor tests
|
||||
|
||||
Week 2: Security + More Tests
|
||||
├── 2.1 Command sanitization
|
||||
├── 2.2 Rate limiting
|
||||
├── 1.5 Handler integration tests
|
||||
└── 2.3 Concurrent command limit
|
||||
|
||||
Week 3: Hexagonal Refactoring
|
||||
├── 3.1 Domain package
|
||||
├── 3.2 Port interfaces
|
||||
├── 3.3 Kubernetes adapter
|
||||
└── 3.4 Postgres adapter
|
||||
|
||||
Week 4: Production Hardening
|
||||
├── 3.5-3.7 Complete hexagonal
|
||||
├── 4.1 SSE Last-Event-ID
|
||||
├── 5.1 Prometheus metrics
|
||||
└── 1.6 E2E tests
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## File Structure After Refactoring
|
||||
|
||||
```
|
||||
internal/
|
||||
├── domain/ # Pure domain model (no deps)
|
||||
│ ├── project.go
|
||||
│ ├── command.go
|
||||
│ ├── apikey.go
|
||||
│ └── errors.go
|
||||
├── port/ # Interface definitions
|
||||
│ ├── project_repository.go
|
||||
│ ├── command_executor.go
|
||||
│ ├── apikey_repository.go
|
||||
│ └── stream_publisher.go
|
||||
├── service/ # Use cases / business logic
|
||||
│ ├── project_service.go
|
||||
│ ├── command_service.go
|
||||
│ └── apikey_service.go
|
||||
├── adapter/
|
||||
│ ├── http/ # Inbound: HTTP handlers
|
||||
│ │ ├── project_handler.go
|
||||
│ │ ├── key_handler.go
|
||||
│ │ ├── middleware/
|
||||
│ │ │ ├── auth.go
|
||||
│ │ │ └── ratelimit.go
|
||||
│ │ └── response.go
|
||||
│ ├── kubernetes/ # Outbound: kubectl
|
||||
│ │ └── executor.go
|
||||
│ ├── postgres/ # Outbound: database
|
||||
│ │ ├── project_repo.go
|
||||
│ │ ├── apikey_repo.go
|
||||
│ │ └── migrations/
|
||||
│ └── memory/ # Outbound: in-memory (testing)
|
||||
│ ├── project_repo.go
|
||||
│ ├── apikey_repo.go
|
||||
│ └── stream_publisher.go
|
||||
└── config/ # Configuration loading
|
||||
└── config.go
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria
|
||||
|
||||
### Must Have (v0.6)
|
||||
- [ ] 80%+ test coverage on auth and executor
|
||||
- [ ] Command input sanitization
|
||||
- [ ] Rate limiting (100 req/min per key)
|
||||
- [ ] No shell injection vulnerabilities
|
||||
|
||||
### Should Have (v0.7)
|
||||
- [ ] Hexagonal architecture complete
|
||||
- [ ] Prometheus metrics endpoint
|
||||
- [ ] SSE reconnection support
|
||||
|
||||
### Nice to Have (v0.8+)
|
||||
- [ ] Dynamic project discovery
|
||||
- [ ] OpenTelemetry tracing
|
||||
- [ ] Command cancellation API
|
||||
|
||||
---
|
||||
|
||||
## Appendix: SSE Event Protocol
|
||||
|
||||
### Event Types
|
||||
|
||||
```
|
||||
event: connected
|
||||
data: {"project":"pantheon","stream_id":"cmd-001"}
|
||||
|
||||
event: output
|
||||
id: cmd-001:1
|
||||
data: {"line":"Starting build...","stream":"stdout"}
|
||||
|
||||
event: output
|
||||
id: cmd-001:2
|
||||
data: {"line":"Warning: deprecated API","stream":"stderr"}
|
||||
|
||||
event: heartbeat
|
||||
data: {"timestamp":"2026-01-25T07:00:00Z"}
|
||||
|
||||
event: complete
|
||||
id: cmd-001:final
|
||||
data: {"exit_code":0,"duration_ms":4523}
|
||||
|
||||
event: error
|
||||
data: {"code":"POD_NOT_FOUND","message":"claudebox-pantheon-0 not running"}
|
||||
```
|
||||
|
||||
### Client Reconnection
|
||||
|
||||
```javascript
|
||||
const events = new EventSource('/projects/pantheon/events?stream_id=cmd-001', {
|
||||
headers: { 'Authorization': 'Bearer rdev_sk_...' }
|
||||
});
|
||||
|
||||
// On reconnect, browser sends Last-Event-ID header automatically
|
||||
// Server should replay events since that ID
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Appendix: Command Execution Flow
|
||||
|
||||
```
|
||||
┌─────────┐ ┌─────────┐ ┌──────────┐ ┌─────────┐
|
||||
│ Client │ │ Handler │ │ Executor │ │ Pod │
|
||||
└────┬────┘ └────┬────┘ └────┬─────┘ └────┬────┘
|
||||
│ │ │ │
|
||||
│ POST /claude │ │ │
|
||||
│──────────────>│ │ │
|
||||
│ │ │ │
|
||||
│ 201 Created │ │ │
|
||||
│<──────────────│ │ │
|
||||
│ │ │ │
|
||||
│ GET /events │ go execute() │ │
|
||||
│──────────────>│──────────────>│ │
|
||||
│ │ │ kubectl exec │
|
||||
│ │ │───────────────>│
|
||||
│ │ │ │
|
||||
│ │ onOutput() │ stdout/stderr │
|
||||
│ SSE output │<──────────────│<───────────────│
|
||||
│<──────────────│ │ │
|
||||
│ │ │ │
|
||||
│ SSE output │ onOutput() │ stdout/stderr │
|
||||
│<──────────────│<──────────────│<───────────────│
|
||||
│ │ │ │
|
||||
│ SSE complete │ result │ exit code │
|
||||
│<──────────────│<──────────────│<───────────────│
|
||||
│ │ │ │
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Decision Log
|
||||
|
||||
| Decision | Rationale | Date |
|
||||
|----------|-----------|------|
|
||||
| Use hexagonal architecture | Testability, flexibility, clean boundaries | 2026-01-25 |
|
||||
| Keep SSE (not WebSocket) | Simpler, HTTP/2 multiplexing, auto-reconnect | 2026-01-25 |
|
||||
| Prioritize tests over refactoring | Can't safely refactor without tests | 2026-01-25 |
|
||||
| Port 5433 for local dev | Avoid conflicts with system postgres | 2026-01-25 |
|
||||
Loading…
Reference in New Issue
Block a user