|
| 1 | +# Summary: lessons-learned.md |
| 2 | + |
| 3 | +## Purpose |
| 4 | +Captures critical technical insights, development patterns, and lessons from Terraphim AI implementation. Serves as knowledge repository for repeatable patterns and anti-patterns to avoid. |
| 5 | + |
| 6 | +## Key Functionality |
| 7 | +- **Pattern Discovery**: Documents successful implementation patterns for reuse |
| 8 | +- **Anti-patterns**: Records mistakes and their solutions for future reference |
| 9 | +- **Technology Insights**: Lessons about tools, frameworks, deployment strategies |
| 10 | +- **Decision Context**: Explains why certain technical approaches were chosen |
| 11 | +- **Best Practices**: Establishes project-specific development guidelines |
| 12 | + |
| 13 | +## Critical Lessons |
| 14 | + |
| 15 | +**Pattern 1: Pattern Discovery Through Reading Existing Code** |
| 16 | +- **Context**: Deployment infrastructure implementation |
| 17 | +- **Learning**: Always read existing scripts before creating new infrastructure |
| 18 | +- **Example**: Reading `deploy-to-bigbox.sh` revealed correct Caddy+rsync pattern (not Docker/nginx) |
| 19 | +- **When to Apply**: Any new feature deployment, integration with existing infrastructure |
| 20 | + |
| 21 | +**Pattern 2: Vanilla JavaScript over Framework for Simple UIs** |
| 22 | +- **Context**: TruthForge UI implementation |
| 23 | +- **Learning**: No build step = instant deployment; check project patterns before choosing technology |
| 24 | +- **Implementation**: Class-based separation (TruthForgeClient, TruthForgeUI), progressive enhancement |
| 25 | +- **Benefits**: Static files work immediately, no compilation required |
| 26 | + |
| 27 | +**Pattern 3: Rsync + Caddy Deployment Pattern** |
| 28 | +- **Context**: Bigbox infrastructure deployment |
| 29 | +- **Learning**: Project uses rsync for file copying, Caddy for reverse proxy (not Docker/nginx) |
| 30 | +- **Steps**: Copy files → Configure Caddy → Update endpoints → Start backend → Verify |
| 31 | +- **Example**: `alpha.truthforge.terraphim.cloud` deployment |
| 32 | + |
| 33 | +**Pattern 4: 1Password CLI for Secret Management** |
| 34 | +- **Context**: Production secret injection |
| 35 | +- **Learning**: Use `op run --env-file=.env` in systemd services, never commit secrets |
| 36 | +- **Benefits**: Centralized management, audit trail, automatic rotation |
| 37 | +- **Implementation**: `.env` file contains vault references (`op://Shared/Key/field`) |
| 38 | + |
| 39 | +**Pattern 5: Test-Driven Security Implementation** |
| 40 | +- **Context**: Security vulnerability fixes |
| 41 | +- **Learning**: Write tests first for security issues, then implement fixes |
| 42 | +- **Categories**: Prompt injection, command injection, memory safety, network validation |
| 43 | +- **Coverage**: 99 comprehensive tests across multiple attack vectors |
| 44 | + |
| 45 | +## Technical Insights |
| 46 | + |
| 47 | +**UI Development**: |
| 48 | +- WebSocket client reusability from shared libraries (agent-workflows/shared/) |
| 49 | +- Protocol-aware URL configuration for file:// vs http:// protocols |
| 50 | +- Fallback mechanisms for graceful degradation |
| 51 | + |
| 52 | +**Security**: |
| 53 | +- Defense-in-depth patterns with multiple validation layers |
| 54 | +- Unicode obfuscation detection critical for prompt sanitizers |
| 55 | +- Concurrent security testing required for production readiness |
| 56 | +- Regex catastrophic backtracking prevention in validation |
| 57 | + |
| 58 | +**Deployment**: |
| 59 | +- Phase-based deployment makes debugging easier (copy, configure, update, verify) |
| 60 | +- Caddy reverse proxy with automatic HTTPS and zero-downtime reloads |
| 61 | +- Systemd services with proper EnvironmentFile for secret loading |
| 62 | + |
| 63 | +**Testing**: |
| 64 | +- Browser automation (Playwright) for E2E validation |
| 65 | +- Protocol validation prevents future regressions |
| 66 | +- Comprehensive test suites build confidence in changes |
| 67 | + |
| 68 | +## Anti-Patterns to Avoid |
| 69 | +- Assuming Docker deployment without checking existing patterns |
| 70 | +- Creating new infrastructure without reading existing scripts |
| 71 | +- Using frameworks when vanilla JS suffices for simple UIs |
| 72 | +- Storing secrets in .env files or environment variables |
| 73 | +- Skipping security tests for "simple" changes |
| 74 | +- Using blocking operations in async functions |
| 75 | + |
| 76 | +## When to Apply These Lessons |
| 77 | +- **Pattern Discovery**: Beginning any new feature or integration |
| 78 | +- **Vanilla JS**: Building simple UIs, demos, or examples |
| 79 | +- **Deployment Pattern**: Any production deployment or service configuration |
| 80 | +- **Secret Management**: All production deployments with sensitive data |
| 81 | +- **Security Testing**: Any code handling user input, system commands, or network operations |
0 commit comments