john/tractatus
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
tractatus/public/images/architecture-diagram.svg
TheFlow 23b342febb feat: technical architecture diagram with comprehensive documentation (Task 8) 
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>
2025-10-12 07:37:10 +13:00

306 lines
No EOL
15 KiB
XML
Raw Blame History

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 1000" style="background: white;">
<!-- Title -->
<text x="600" y="30" font-family="Arial, sans-serif" font-size="24" font-weight="bold" text-anchor="middle" fill="#1f2937">
Tractatus Framework Architecture
</text>
<text x="600" y="55" font-family="Arial, sans-serif" font-size="14" text-anchor="middle" fill="#6b7280">
Claude Code + Tractatus Governance Integration
</text>
<!-- Layer 1: Claude Code Runtime (Foundation) -->
<rect x="50" y="850" width="1100" height="120" fill="#dbeafe" stroke="#3b82f6" stroke-width="2" rx="8"/>
<text x="600" y="880" font-family="Arial, sans-serif" font-size="18" font-weight="bold" text-anchor="middle" fill="#1e40af">
Claude Code Runtime Environment
</text>
<text x="600" y="905" font-family="Arial, sans-serif" font-size="13" text-anchor="middle" fill="#475569">
Base LLM Environment • Session Management • Tool Access • File System Operations
</text>
<text x="600" y="925" font-family="Arial, sans-serif" font-size="13" text-anchor="middle" fill="#475569">
.claude/instruction-history.json • .claude/session-state.json • .claude/token-checkpoints.json
</text>
<text x="600" y="945" font-family="Arial, sans-serif" font-size="12" text-anchor="middle" fill="#64748b" font-style="italic">
Provides: Context Window (200k tokens) • Bash/Read/Write Tools • Session Persistence
</text>
<!-- Layer 2: Tractatus Governance Services -->
<rect x="50" y="520" width="1100" height="310" fill="#f0fdf4" stroke="#10b981" stroke-width="3" rx="8"/>
<text x="600" y="550" font-family="Arial, sans-serif" font-size="18" font-weight="bold" text-anchor="middle" fill="#065f46">
Tractatus Governance Layer
</text>
<!-- 5 Core Services in Grid -->
<!-- Row 1: 3 services -->
<g id="boundary-enforcer">
<rect x="80" y="570" width="320" height="110" fill="#fef3c7" stroke="#f59e0b" stroke-width="2" rx="6"/>
<text x="240" y="595" font-family="Arial, sans-serif" font-size="14" font-weight="bold" text-anchor="middle" fill="#92400e">
BoundaryEnforcer
</text>
<text x="240" y="615" font-family="Arial, sans-serif" font-size="11" text-anchor="middle" fill="#78350f">
Blocks values decisions
</text>
<text x="240" y="635" font-family="Arial, sans-serif" font-size="10" text-anchor="middle" fill="#78350f">
• Privacy decisions
</text>
<text x="240" y="650" font-family="Arial, sans-serif" font-size="10" text-anchor="middle" fill="#78350f">
• Ethical trade-offs
</text>
<text x="240" y="665" font-family="Arial, sans-serif" font-size="10" text-anchor="middle" fill="#78350f">
• User agency violations
</text>
</g>
<g id="classifier">
<rect x="440" y="570" width="320" height="110" fill="#ddd6fe" stroke="#8b5cf6" stroke-width="2" rx="6"/>
<text x="600" y="595" font-family="Arial, sans-serif" font-size="14" font-weight="bold" text-anchor="middle" fill="#5b21b6">
InstructionPersistenceClassifier
</text>
<text x="600" y="615" font-family="Arial, sans-serif" font-size="11" text-anchor="middle" fill="#6b21a8">
Classifies &amp; stores instructions
</text>
<text x="600" y="635" font-family="Arial, sans-serif" font-size="10" text-anchor="middle" fill="#6b21a8">
• Quadrant (STR/OPS/TAC/SYS)
</text>
<text x="600" y="650" font-family="Arial, sans-serif" font-size="10" text-anchor="middle" fill="#6b21a8">
• Persistence (HIGH/MED/LOW)
</text>
<text x="600" y="665" font-family="Arial, sans-serif" font-size="10" text-anchor="middle" fill="#6b21a8">
• Temporal scope
</text>
</g>
<g id="validator">
<rect x="800" y="570" width="320" height="110" fill="#fce7f3" stroke="#ec4899" stroke-width="2" rx="6"/>
<text x="960" y="595" font-family="Arial, sans-serif" font-size="14" font-weight="bold" text-anchor="middle" fill="#9f1239">
CrossReferenceValidator
</text>
<text x="960" y="615" font-family="Arial, sans-serif" font-size="11" text-anchor="middle" fill="#9f1239">
Prevents pattern bias override
</text>
<text x="960" y="635" font-family="Arial, sans-serif" font-size="10" text-anchor="middle" fill="#9f1239">
• Checks instruction history
</text>
<text x="960" y="650" font-family="Arial, sans-serif" font-size="10" text-anchor="middle" fill="#9f1239">
• Detects conflicts (27027)
</text>
<text x="960" y="665" font-family="Arial, sans-serif" font-size="10" text-anchor="middle" fill="#9f1239">
• Blocks contradictions
</text>
</g>
<!-- Row 2: 2 services centered -->
<g id="pressure-monitor">
<rect x="260" y="700" width="320" height="110" fill="#e0e7ff" stroke="#6366f1" stroke-width="2" rx="6"/>
<text x="420" y="725" font-family="Arial, sans-serif" font-size="14" font-weight="bold" text-anchor="middle" fill="#3730a3">
ContextPressureMonitor
</text>
<text x="420" y="745" font-family="Arial, sans-serif" font-size="11" text-anchor="middle" fill="#3730a3">
Detects degraded conditions
</text>
<text x="420" y="765" font-family="Arial, sans-serif" font-size="10" text-anchor="middle" fill="#3730a3">
• Token budget tracking
</text>
<text x="420" y="780" font-family="Arial, sans-serif" font-size="10" text-anchor="middle" fill="#3730a3">
• Error accumulation
</text>
<text x="420" y="795" font-family="Arial, sans-serif" font-size="10" text-anchor="middle" fill="#3730a3">
• Checkpoint reporting
</text>
</g>
<g id="verifier">
<rect x="620" y="700" width="320" height="110" fill="#fef2f2" stroke="#ef4444" stroke-width="2" rx="6"/>
<text x="780" y="725" font-family="Arial, sans-serif" font-size="14" font-weight="bold" text-anchor="middle" fill="#991b1b">
MetacognitiveVerifier
</text>
<text x="780" y="745" font-family="Arial, sans-serif" font-size="11" text-anchor="middle" fill="#991b1b">
Self-checks complex operations
</text>
<text x="780" y="765" font-family="Arial, sans-serif" font-size="10" text-anchor="middle" fill="#991b1b">
• &gt;3 files or &gt;5 steps
</text>
<text x="780" y="780" font-family="Arial, sans-serif" font-size="10" text-anchor="middle" fill="#991b1b">
• Architecture changes
</text>
<text x="780" y="795" font-family="Arial, sans-serif" font-size="10" text-anchor="middle" fill="#991b1b">
• Confidence scoring
</text>
</g>
<!-- Layer 3: MongoDB Persistence -->
<rect x="50" y="250" width="1100" height="240" fill="#fef9c3" stroke="#eab308" stroke-width="2" rx="8"/>
<text x="600" y="280" font-family="Arial, sans-serif" font-size="18" font-weight="bold" text-anchor="middle" fill="#713f12">
MongoDB Persistence Layer
</text>
<!-- Collections in Grid -->
<g id="governance-rules">
<rect x="80" y="300" width="240" height="160" fill="#fff7ed" stroke="#f97316" stroke-width="2" rx="6"/>
<text x="200" y="325" font-family="Arial, sans-serif" font-size="13" font-weight="bold" text-anchor="middle" fill="#7c2d12">
governance_rules
</text>
<text x="200" y="350" font-family="Arial, sans-serif" font-size="10" text-anchor="middle" fill="#7c2d12">
• rule_id (STR-001...)
</text>
<text x="200" y="370" font-family="Arial, sans-serif" font-size="10" text-anchor="middle" fill="#7c2d12">
• quadrant
</text>
<text x="200" y="390" font-family="Arial, sans-serif" font-size="10" text-anchor="middle" fill="#7c2d12">
• persistence level
</text>
<text x="200" y="410" font-family="Arial, sans-serif" font-size="10" text-anchor="middle" fill="#7c2d12">
• enforced_by
</text>
<text x="200" y="430" font-family="Arial, sans-serif" font-size="10" text-anchor="middle" fill="#7c2d12">
• violation_action
</text>
<text x="200" y="450" font-family="Arial, sans-serif" font-size="10" text-anchor="middle" fill="#7c2d12">
• active status
</text>
</g>
<g id="audit-logs">
<rect x="360" y="300" width="240" height="160" fill="#f0fdfa" stroke="#14b8a6" stroke-width="2" rx="6"/>
<text x="480" y="325" font-family="Arial, sans-serif" font-size="13" font-weight="bold" text-anchor="middle" fill="#134e4a">
audit_logs
</text>
<text x="480" y="350" font-family="Arial, sans-serif" font-size="10" text-anchor="middle" fill="#134e4a">
• timestamp
</text>
<text x="480" y="370" font-family="Arial, sans-serif" font-size="10" text-anchor="middle" fill="#134e4a">
• service (which enforcer)
</text>
<text x="480" y="390" font-family="Arial, sans-serif" font-size="10" text-anchor="middle" fill="#134e4a">
• action (BLOCK/WARN)
</text>
<text x="480" y="410" font-family="Arial, sans-serif" font-size="10" text-anchor="middle" fill="#134e4a">
• instruction
</text>
<text x="480" y="430" font-family="Arial, sans-serif" font-size="10" text-anchor="middle" fill="#134e4a">
• rule_violated
</text>
<text x="480" y="450" font-family="Arial, sans-serif" font-size="10" text-anchor="middle" fill="#134e4a">
• session_id
</text>
</g>
<g id="session-state">
<rect x="640" y="300" width="240" height="160" fill="#fae8ff" stroke="#d946ef" stroke-width="2" rx="6"/>
<text x="760" y="325" font-family="Arial, sans-serif" font-size="13" font-weight="bold" text-anchor="middle" fill="#701a75">
session_state
</text>
<text x="760" y="350" font-family="Arial, sans-serif" font-size="10" text-anchor="middle" fill="#701a75">
• session_id
</text>
<text x="760" y="370" font-family="Arial, sans-serif" font-size="10" text-anchor="middle" fill="#701a75">
• token_count
</text>
<text x="760" y="390" font-family="Arial, sans-serif" font-size="10" text-anchor="middle" fill="#701a75">
• message_count
</text>
<text x="760" y="410" font-family="Arial, sans-serif" font-size="10" text-anchor="middle" fill="#701a75">
• pressure_level
</text>
<text x="760" y="430" font-family="Arial, sans-serif" font-size="10" text-anchor="middle" fill="#701a75">
• last_checkpoint
</text>
<text x="760" y="450" font-family="Arial, sans-serif" font-size="10" text-anchor="middle" fill="#701a75">
• framework_active
</text>
</g>
<g id="instruction-history">
<rect x="920" y="300" width="240" height="160" fill="#ede9fe" stroke="#a78bfa" stroke-width="2" rx="6"/>
<text x="1040" y="325" font-family="Arial, sans-serif" font-size="13" font-weight="bold" text-anchor="middle" fill="#4c1d95">
instruction_history
</text>
<text x="1040" y="350" font-family="Arial, sans-serif" font-size="10" text-anchor="middle" fill="#4c1d95">
• instruction_id
</text>
<text x="1040" y="370" font-family="Arial, sans-serif" font-size="10" text-anchor="middle" fill="#4c1d95">
• content
</text>
<text x="1040" y="390" font-family="Arial, sans-serif" font-size="10" text-anchor="middle" fill="#4c1d95">
• classification
</text>
<text x="1040" y="410" font-family="Arial, sans-serif" font-size="10" text-anchor="middle" fill="#4c1d95">
• persistence
</text>
<text x="1040" y="430" font-family="Arial, sans-serif" font-size="10" text-anchor="middle" fill="#4c1d95">
• created_at
</text>
<text x="1040" y="450" font-family="Arial, sans-serif" font-size="10" text-anchor="middle" fill="#4c1d95">
• active status
</text>
</g>
<!-- Layer 4: API & Interface -->
<rect x="50" y="80" width="1100" height="140" fill="#f3e8ff" stroke="#a855f7" stroke-width="2" rx="8"/>
<text x="600" y="110" font-family="Arial, sans-serif" font-size="18" font-weight="bold" text-anchor="middle" fill="#581c87">
API &amp; Web Interface Layer
</text>
<!-- API Endpoints -->
<g id="api-endpoints">
<rect x="80" y="130" width="500" height="70" fill="#fdf4ff" stroke="#c084fc" stroke-width="1" rx="4"/>
<text x="330" y="150" font-family="Arial, sans-serif" font-size="12" font-weight="bold" text-anchor="middle" fill="#581c87">
API Endpoints
</text>
<text x="330" y="170" font-family="Arial, sans-serif" font-size="10" text-anchor="middle" fill="#6b21a8">
/api/demo/classify • /api/demo/boundary-check • /api/demo/pressure-check
</text>
<text x="330" y="188" font-family="Arial, sans-serif" font-size="10" text-anchor="middle" fill="#6b21a8">
/api/admin/* • /api/auth/* • /api/health
</text>
</g>
<!-- Web Interface -->
<g id="web-interface">
<rect x="620" y="130" width="500" height="70" fill="#ecfdf5" stroke="#6ee7b7" stroke-width="1" rx="4"/>
<text x="870" y="150" font-family="Arial, sans-serif" font-size="12" font-weight="bold" text-anchor="middle" fill="#065f46">
Web Interface
</text>
<text x="870" y="170" font-family="Arial, sans-serif" font-size="10" text-anchor="middle" fill="#047857">
Interactive Demos • Admin Dashboard • Documentation
</text>
<text x="870" y="188" font-family="Arial, sans-serif" font-size="10" text-anchor="middle" fill="#047857">
Blog System • Case Submissions • Media Inquiry
</text>
</g>
<!-- Data Flow Arrows -->
<!-- User -> API -->
<defs>
<marker id="arrowhead" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
<polygon points="0 0, 10 3, 0 6" fill="#4b5563" />
</marker>
</defs>
<!-- API to Governance Services -->
<line x1="330" y1="220" x2="420" y2="570" stroke="#4b5563" stroke-width="2" marker-end="url(#arrowhead)"/>
<line x1="870" y1="220" x2="780" y2="570" stroke="#4b5563" stroke-width="2" marker-end="url(#arrowhead)"/>
<!-- Governance to Persistence -->
<line x1="240" y1="680" x2="200" y2="300" stroke="#4b5563" stroke-width="2" marker-end="url(#arrowhead)"/>
<line x1="600" y1="680" x2="480" y2="460" stroke="#4b5563" stroke-width="2" marker-end="url(#arrowhead)"/>
<line x1="780" y1="810" x2="760" y2="460" stroke="#4b5563" stroke-width="2" marker-end="url(#arrowhead)"/>
<line x1="960" y1="680" x2="1040" y2="460" stroke="#4b5563" stroke-width="2" marker-end="url(#arrowhead)"/>
<!-- Persistence to Claude Code -->
<line x1="200" y1="490" x2="300" y2="850" stroke="#4b5563" stroke-width="2" marker-end="url(#arrowhead)"/>
<line x1="480" y1="490" x2="500" y2="850" stroke="#4b5563" stroke-width="2" marker-end="url(#arrowhead)"/>
<line x1="760" y1="490" x2="700" y2="850" stroke="#4b5563" stroke-width="2" marker-end="url(#arrowhead)"/>
<line x1="1040" y1="490" x2="900" y2="850" stroke="#4b5563" stroke-width="2" marker-end="url(#arrowhead)"/>
<!-- Key Components Legend -->
<g id="legend" transform="translate(900, 15)">
<text x="0" y="0" font-family="Arial, sans-serif" font-size="11" font-weight="bold" fill="#374151">
Integration Points:
</text>
<text x="0" y="18" font-family="Arial, sans-serif" font-size="9" fill="#6b7280">
↓ Data flows from interface through
</text>
<text x="0" y="30" font-family="Arial, sans-serif" font-size="9" fill="#6b7280">
governance services to persistence
</text>
</g>
</svg>
Reference in a new issue View git blame Copy permalink