Architecture Overview

AIV is a multi-agent AI platform designed for business automation. This document explains the overall architecture and how components interact.

Platform Structure

aiv/                              ← MONOREPO
│
├── src/                          ← AIV ENGINE (CLI + Library)
│   │                               Core AI functionality
│   │                               "Claude Code for business"
│   │
│   └── Features:
│       • Multi-provider (Anthropic, Azure, OpenRouter)
│       • MCP ecosystem (Model Context Protocol)
│       • Built-in tools (read, write, exec, search)
│       • Agent system (@mention, /expert)
│       • Context management
│
├── aiv-agents/                   ← AGENT PACKS (Containerized)
│   │                               Specialized agents
│   │                               Email-based interface
│   │
│   ├── packs/                      Agent definitions
│   │   ├── core/                   @agi, @orchestrator
│   │   ├── security/               @cso, @soc, @ir
│   │   ├── legal/                  @prawnik
│   │   └── sales/                  @sales
│   │
│   ├── src/                        Platform modules
│   │   ├── daemon/                 Service management
│   │   ├── cron/                   Task scheduling
│   │   ├── heartbeat/              Health monitoring
│   │   ├── config/                 Configuration
│   │   └── onboarding/             Setup wizard
│   │
│   └── shared/                     Shared resources
│       ├── companies/              CRM data
│       └── knowledge/              Shared knowledge
│
└── aiv-desktop/                  ← DESKTOP APP (Electron)
                                    GUI for business users
                                    Three-panel interface

Component Diagram

┌─────────────────────────────────────────────────────────────────────────┐
│                           AIV PLATFORM                                   │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌───────────────────┐    ┌───────────────────┐    ┌─────────────────┐ │
│  │    AIV Engine     │    │   AIV Agents      │    │   AIV Desktop   │ │
│  │    (CLI/Lib)      │◀──▶│   (Containers)    │◀──▶│   (Electron)    │ │
│  └─────────┬─────────┘    └─────────┬─────────┘    └────────┬────────┘ │
│            │                        │                       │          │
│            ▼                        ▼                       ▼          │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │                     Platform Modules                             │   │
│  │  ┌─────────┐ ┌─────────┐ ┌───────────┐ ┌────────┐ ┌───────────┐ │   │
│  │  │ Daemon  │ │  Cron   │ │ Heartbeat │ │ Config │ │ Onboarding│ │   │
│  │  └─────────┘ └─────────┘ └───────────┘ └────────┘ └───────────┘ │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│                                                                         │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │                     External Services                            │   │
│  │  ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────────────┐│   │
│  │  │ Anthropic │ │   Azure   │ │ OpenRouter│ │ MCP Servers       ││   │
│  │  └───────────┘ └───────────┘ └───────────┘ └───────────────────┘│   │
│  └─────────────────────────────────────────────────────────────────┘   │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

Data Flow

1. User Interaction Flow

User Input → AIV Engine → Provider API → Response → User Output
                 ↓
           Tool Execution
                 ↓
         File Operations
         Command Execution
         MCP Server Calls

2. Agent Communication Flow

Email Request → Email Gateway → Router → Agent Container → Response Email
                     ↓
                Parse routing:
                agent@project.client.company.tld
                     ↓
                Load context:
                - Company data
                - Client data
                - Project data

3. Configuration Flow

Onboarding Wizard → Config Manager → File Watcher → Hot Reload
       ↓                  ↓
 Create files      Watch for changes
       ↓                  ↓
 config.json         Validate
    .env            Apply changes
  .mcp.json         Take snapshot

AIV Engine

The core engine handles all AI interactions:

// Simplified architecture
class Agent {
  provider: LlmProvider;    // Anthropic, Azure, OpenRouter
  tools: Tool[];            // Built-in and MCP tools
  context: ContextManager;  // System prompt, history

  async chat(message: string): Promise<Response> {
    // 1. Build context
    const systemPrompt = this.context.build();

    // 2. Call LLM
    const response = await this.provider.complete({
      system: systemPrompt,
      messages: this.history,
      tools: this.tools,
    });

    // 3. Handle tool calls
    if (response.toolCalls) {
      for (const call of response.toolCalls) {
        const result = await this.executeTool(call);
        // Continue conversation with tool result
      }
    }

    return response;
  }
}

Provider Abstraction

interface LlmProvider {
  complete(request: LlmRequest): Promise<LlmResponse>;
  stream(request: LlmRequest): AsyncIterable<LlmChunk>;
}

// Implementations
class AnthropicProvider implements LlmProvider { ... }
class AzureProvider implements LlmProvider { ... }
class OpenRouterProvider implements LlmProvider { ... }

Tool System

interface Tool {
  name: string;
  description: string;
  inputSchema: ZodSchema;
  execute(input: unknown): Promise<ToolResult>;
}

// Built-in tools
const tools = [
  readFileTool,
  writeFileTool,
  execTool,
  searchTool,
  browserTool,
];

// MCP tools loaded dynamically
const mcpTools = await mcpManager.getTools();

Agent Packs

Agents are defined in markdown with YAML frontmatter:

---
name: soc
description: "SOC Tier 2 Analyst"
model: sonnet
---

# SOC Analyst

## Role
You are a SOC Tier 2 Analyst...

## Procedures
1. Alert triage
2. Investigation
3. Escalation

## Output Format
Save analyses to: reports/alert-{id}-analysis.md

Pack Structure

packs/security/
├── pack.yaml           # Pack configuration
├── agents/
│   ├── cso.md          # Chief Security Officer
│   ├── soc.md          # SOC Analyst
│   └── ir.md           # Incident Response
├── knowledge/
│   └── playbooks.md    # Security playbooks
└── templates/
    └── incident-report.md

DNS-Like Routing

Agents are addressed hierarchically:

agent@[project.][client.][department.]company.domain

Examples

Address	Agent	Context
@soc@seciq.pl	soc	SecIQ company
@soc@security.seciq.pl	soc	Security dept at SecIQ
@intune@solaris.itdev.allnet.pl	intune	Solaris project, IT-Dev client, Allnet company

Context Loading

intune@solaris.itdev.allnet.pl
         ↓
Loads context layers:
1. shared/knowledge/              ← Global knowledge
2. shared/companies/allnet/       ← Allnet company
3. .../clients/itdev/             ← IT-Dev client
4. .../projects/solaris/          ← Solaris project

Desktop App

Three-panel interface:

┌──────────────────────────────────────────────────────────────┐
│  AIV Desktop                                           - □ × │
├────────────────┬─────────────────────────────────────────────┤
│                │                                             │
│  📁 File Tree  │  📝 Markdown Editor                        │
│                │                                             │
│  ▸ vault/      │  # Project Status                          │
│  ▸ clients/    │                                             │
│    ▸ allnet/   │  ## Overview                                │
│  ▸ reports/    │  - Phase 1: ✅ Complete                     │
│                │  - Phase 2: 🔄 In Progress                  │
│                │                                             │
│                ├─────────────────────────────────────────────┤
│                │                                             │
│                │  💬 AI Chat                                  │
│                │                                             │
│                │  🤖 Analyzing project status...             │
│                │  ⚙️ read_file: vault/projects/solaris.md    │
│                │  ✅ Project is 67% complete.                │
│                │                                             │
│                │  > Ask a question...                 🎤 📎  │
│                │                                             │
└────────────────┴─────────────────────────────────────────────┘

IPC Bridge

// Renderer → Main
window.aiv.chat.send(message);
window.aiv.files.read(path);
window.aiv.terminal.send(input);

// Main → Renderer (events)
window.aiv.chat.onResponse(callback);
window.aiv.chat.onTool(callback);
window.aiv.files.onChange(callback);

Security Architecture

Layered Security

┌─────────────────────────────────────────┐
│          Input Validation (Zod)         │
├─────────────────────────────────────────┤
│         Path Traversal Prevention       │
├─────────────────────────────────────────┤
│         Command Whitelisting            │
├─────────────────────────────────────────┤
│         Permission System               │
├─────────────────────────────────────────┤
│         File Permissions (0o600)        │
└─────────────────────────────────────────┘

Validation Layers

1. Input - Zod schemas validate all input
2. Path - Block .., null bytes, symlinks
3. Command - Whitelist safe commands
4. Permission - Confirm destructive actions
5. Storage - Secure file permissions

Next Steps

• Platform Components - Detailed component docs
• Agent Routing - Full routing documentation
• Data Flow - Complete flow diagrams