System Architecture

Understanding the Vision system's layered architecture and component interactions.

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                          Shane                               │
└──────────────────────────┬──────────────────────────────────┘
                           │
                 ┌─────────▼──────────┐
                 │        VAL         │  Request preprocessing
                 │  Abstraction Layer │  Response validation
                 └─────────┬──────────┘  Domain routing
                           │
                 ┌─────────▼──────────┐
                 │    Claude Code     │  Core AI engine
                 │  (Claude Sonnet    │  Tool execution
                 │     4.5 VISION)    │  Code operations
                 └─────────┬──────────┘
                           │
        ┌──────────────────┼──────────────────┐
        │                  │                  │
   ┌────▼────┐      ┌─────▼─────┐     ┌─────▼──────┐
   │   MCP   │      │  Agent    │     │  Knowledge │
   │ Servers │      │  Network  │     │  Database  │
   └─────────┘      └───────────┘     └────────────┘

Layer Breakdown

Layer 1: Request Processing (VAL)

Components:

• Preprocessor: Domain detection, context enrichment
• Domain Modules: Work, Personal, Research specialization
• Template System: Common task automation

Purpose: Enrich every request with relevant context before processing

Layer 2: Core Intelligence (Claude Code)

Components:

• Claude Sonnet 4.5: Primary reasoning engine
• Tool System: File ops, bash, search, etc.
• MCP Integration: Extended capabilities

Purpose: Execute tasks with full system access

Layer 3: Response Validation (VAL)

Components:

• Postprocessor: Output validation
• Action Triggers: Slack, Flare, screenshots
• Knowledge Ingestion: Pattern learning

Purpose: Ensure accuracy and trigger follow-up actions

Layer 4: Infrastructure

Components:

• 21 MCP Servers: Browser, search, docs, error tracking
• Agent Network: JARVIS, HEIMDALL, FRIDAY
• Databases: Knowledge DB, network DB, history

Purpose: Provide specialized capabilities and distributed intelligence

Data Flow

Request Flow

1. User input → VAL preprocessor
2. Domain detection (work/personal/research)
3. Knowledge DB query for relevant context
4. Enriched request → Claude Code
5. Tool execution → Results
6. Results → VAL postprocessor
7. Validation + automatic actions
8. Response → User

Learning Flow

1. Interaction occurs
2. Postprocessor extracts patterns
3. Patterns → Knowledge DB
4. Operational log updated
5. Future requests use learned patterns

Key Design Principles

Hub-and-Spoke Agent Communication

Decision: VISION as central orchestrator Benefit: Prevents bot loops, maintains audit trail Implementation: Bot filter in agent_core.py

Domain-Based Context

Decision: Separate work/personal/research modules Benefit: Specialized protocols and knowledge per domain Implementation: Domain router in VAL preprocessor

Validation-First

Decision: All outputs validated before delivery Benefit: Ensures accuracy, prevents mistakes Implementation: VAL postprocessor with action triggers

Truth-Based

Decision: "YOU DO NOT LIE" fundamental rule Benefit: Evidence-based responses only Implementation: System prompts + audit logging

Component Dependencies

Claude Code (Core)
├── VAL (Request/Response processing)
│   ├── Knowledge DB (Context)
│   ├── Operational Log (Learnings)
│   └── Templates (Common tasks)
├── MCP Servers (Extended capabilities)
│   ├── Browser Automation (playwright, puppeteer)
│   ├── Search (duckduckgo, wikipedia)
│   ├── Docs (cloudflare, jetbrains, atlas)
│   ├── Error Tracking (flare)
│   └── Communication (slack)
└── Agent Network (Distributed intelligence)
    ├── JARVIS (Code validation)
    ├── HEIMDALL (Monitoring)
    ├── FRIDAY (Task execution)
    └── Network DB (Shared knowledge)

Version: 3.0.0 Architecture Type: Layered with Hub-and-Spoke coordination