e086066b99
Complete system architecture visualization showing Claude Code + Tractatus integration across 4 layers: API/Web, Governance, Persistence, and Runtime. **Diagram Files:** 1. architecture-diagram.svg (15KB) - Scalable vector format for web and documentation - 4-layer visualization with color-coded components - Data flow arrows showing integration points - Professional design suitable for research papers 2. architecture-diagram.png (581KB) - High-resolution 2400x2000 raster format - Generated via Inkscape from SVG - Suitable for presentations and print materials 3. architecture-diagram.mmd - Mermaid diagram for markdown embedding - Supports dynamic rendering in documentation - Version control friendly text format **Documentation:** 4. docs/markdown/technical-architecture.md (18KB) - Comprehensive technical architecture guide - Layer-by-layer component descriptions - Integration points and data flows - Performance characteristics (<10ms overhead) - Deployment architecture (Docker/systemd) - Complementarity with Claude Code explanation 5. public/downloads/technical-architecture-diagram.pdf - Generated from markdown with embedded diagram - Complete documentation in portable format - Suitable for offline reading and distribution **Implementer Page Integration:** 6. public/implementer.html - Added "System Architecture" section after Deployment Quickstart - Full-width diagram display with shadow effects - Three download buttons: SVG, PNG (High-Res), PDF - 4-card layer breakdown (API → Governance → Persistence → Runtime) - 3-point integration explanation with numbered badges - Professional color scheme matching brand (purple/green/yellow/blue) **Architecture Layers:** Layer 4 - API & Web Interface: - Demo endpoints (/api/demo/*) - Admin dashboard - Documentation system - Blog with AI curation Layer 3 - Tractatus Governance: - BoundaryEnforcer (values decisions) - InstructionPersistenceClassifier (classification) - CrossReferenceValidator (pattern bias prevention) - ContextPressureMonitor (degradation detection) - MetacognitiveVerifier (complex operation verification) Layer 2 - MongoDB Persistence: - governance_rules collection (rule storage with indexes) - audit_logs collection (compliance trail) - session_state collection (pressure tracking) - instruction_history collection (cross-reference validation) Layer 1 - Claude Code Runtime: - Base LLM environment (200k context window) - Session management (persistent state) - Tool access (Bash, Read, Write, Edit) - File system operations (.claude/ directory) **Key Integration Points:** 1. Pre-Action Checks: - All actions validated against governance rules - BLOCK or ALLOW with explanation - Audit log entry created 2. Instruction Persistence: - User instructions classified (quadrant, persistence, scope) - Stored in .claude/instruction-history.json + MongoDB - Cross-referenced before conflicting actions 3. Context Pressure Monitoring: - Real-time pressure calculation (tokens, messages, errors) - Mandatory checkpoint reporting (50k, 100k, 150k) - Early warning system for degradation **The 27027 Incident Prevention Flow:** User: "Use MongoDB port 27027" → Classifier: SYSTEM/HIGH/session → Stored in instruction_history [107k tokens later, pressure builds] AI attempts: port 27017 (pattern recognition) → CrossReferenceValidator: CONFLICT DETECTED → Action BLOCKED, user notified → AI corrects to 27027 → Audit log created **Deployment:** ✅ Deployed to production: - SVG/PNG diagrams to /public/images/ - PDF to /public/downloads/ - Markdown docs to /docs/markdown/ - Updated implementer.html with diagram section **Roadmap Progress:** Phase 2, Week 3, Task 8: Technical Architecture Diagram - COMPLETED Priority: High | Effort: 4-6 hours | Status: ✅ Done **Success Criteria Met:** ✓ Clear, professional diagram explaining complementarity with Claude Code ✓ High-resolution exports (SVG, PNG, PDF) ✓ Comprehensive technical documentation ✓ Integrated into implementer page ✓ Multiple format downloads available ✓ Layer-by-layer component breakdown ✓ Data flow visualization ✓ Performance metrics documented Next: Task 9 - Video Walkthrough (Week 3, 2-3 days) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
52 lines
2.8 KiB
Text
52 lines
2.8 KiB
Text
graph TB
|
|
subgraph "API & Web Interface Layer"
|
|
API["<b>API Endpoints</b><br/>/api/demo/classify<br/>/api/demo/boundary-check<br/>/api/demo/pressure-check<br/>/api/admin/* • /api/auth/*"]
|
|
WEB["<b>Web Interface</b><br/>Interactive Demos<br/>Admin Dashboard<br/>Documentation<br/>Blog System"]
|
|
end
|
|
|
|
subgraph "Tractatus Governance Layer"
|
|
BE["<b>BoundaryEnforcer</b><br/>Blocks values decisions<br/>• Privacy decisions<br/>• Ethical trade-offs<br/>• User agency violations"]
|
|
IPC["<b>InstructionPersistenceClassifier</b><br/>Classifies & stores instructions<br/>• Quadrant (STR/OPS/TAC/SYS)<br/>• Persistence (HIGH/MED/LOW)<br/>• Temporal scope"]
|
|
CRV["<b>CrossReferenceValidator</b><br/>Prevents pattern bias override<br/>• Checks instruction history<br/>• Detects conflicts (27027)<br/>• Blocks contradictions"]
|
|
CPM["<b>ContextPressureMonitor</b><br/>Detects degraded conditions<br/>• Token budget tracking<br/>• Error accumulation<br/>• Checkpoint reporting"]
|
|
MV["<b>MetacognitiveVerifier</b><br/>Self-checks complex operations<br/>• >3 files or >5 steps<br/>• Architecture changes<br/>• Confidence scoring"]
|
|
end
|
|
|
|
subgraph "MongoDB Persistence Layer"
|
|
GR["<b>governance_rules</b><br/>• rule_id (STR-001...)<br/>• quadrant<br/>• persistence level<br/>• enforced_by<br/>• violation_action<br/>• active status"]
|
|
AL["<b>audit_logs</b><br/>• timestamp<br/>• service (which enforcer)<br/>• action (BLOCK/WARN)<br/>• instruction<br/>• rule_violated<br/>• session_id"]
|
|
SS["<b>session_state</b><br/>• session_id<br/>• token_count<br/>• message_count<br/>• pressure_level<br/>• last_checkpoint<br/>• framework_active"]
|
|
IH["<b>instruction_history</b><br/>• instruction_id<br/>• content<br/>• classification<br/>• persistence<br/>• created_at<br/>• active status"]
|
|
end
|
|
|
|
subgraph "Claude Code Runtime Environment"
|
|
CC["<b>Base LLM Environment</b><br/>Session Management • Tool Access<br/>File System Operations<br/>.claude/instruction-history.json<br/>.claude/session-state.json<br/>.claude/token-checkpoints.json<br/><i>Context Window (200k tokens)</i>"]
|
|
end
|
|
|
|
%% Data Flow
|
|
API --> BE
|
|
API --> IPC
|
|
WEB --> CRV
|
|
WEB --> CPM
|
|
|
|
BE --> GR
|
|
IPC --> AL
|
|
CRV --> IH
|
|
CPM --> SS
|
|
MV --> AL
|
|
|
|
GR --> CC
|
|
AL --> CC
|
|
SS --> CC
|
|
IH --> CC
|
|
|
|
%% Styling
|
|
classDef api fill:#f3e8ff,stroke:#a855f7,stroke-width:2px
|
|
classDef governance fill:#f0fdf4,stroke:#10b981,stroke-width:2px
|
|
classDef persistence fill:#fef9c3,stroke:#eab308,stroke-width:2px
|
|
classDef runtime fill:#dbeafe,stroke:#3b82f6,stroke-width:2px
|
|
|
|
class API,WEB api
|
|
class BE,IPC,CRV,CPM,MV governance
|
|
class GR,AL,SS,IH persistence
|
|
class CC runtime
|