# danielmiessler/personal_ai_infrastructure architecture

> Architecture diagram of the GitHub repository danielmiessler/personal_ai_infrastructure, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/danielmiessler/personal_ai_infrastructure
- Repository: https://github.com/danielmiessler/personal_ai_infrastructure

## Overview

##### Project type and purpose
- This is an open-source, personal AI orchestration platform (PAI). It lives in a user’s shell (`~/.claude/`) and surfaces both CLI commands and microservices for TTS and observability. It uses “Skills” (domain containers), “Workflows” (task definitions), “Agents” (parallel workers), “Hooks” (lifecycle interceptors), and “MCPs/Direct Code” (external API or self-contained integrations).

##### File structure
- Top-level remaps everything under `.claude/` to mirror `~/.claude/`.
- `.claude/agents/` – agent role definitions (.md)
- `.claude/hooks/` – TypeScript hooks (pre-commit, context loaders, observability)
- `.claude/skills/` – skill containers with `SKILL.md`, `workflows/`, plus subdirectories for frontend (Vue) and backend (Node) in the `agent-observability` skill
- `.claude/voice-server/` – Bun-based TypeScript microservice for text-to-speech
- Root contains GitHub metadata (README, .github, LICENSE).

##### README insights
- Four core primitives: Skills, Workflows, Agents, MCPs/Direct Code
- Architecture flow:
User Intent → Skill (container) → Workflow (task) → Implementation (code or MCP)
Agents orchestrate parallel invocations; hooks capture events and load context; observability microservice visualizes execution; voice-server provides TTS.

##### Main components & interactions
a. Components:
1. PAI CLI (shell entry point)
2. `.claude/` directory (configuration, hooks, skills, agents)
3. Skills + Workflows loader
4. Agents Manager (spawns researcher/engineer/designer agents)
5. Implementation layer
- Direct Code (TypeScript scripts, Python helpers)
- MCPs (Anthropic Claude, OpenAI, Gemini, Perplexity, browser tools, cloud services)
6. Hooks subsystem (context-loading, event capture, documentation updates)
7. Observability Service
- Backend (Node server, database)
- Frontend (Vue client UI)
8. Voice-Server microservice (Bun TS server + TTS providers)
b. Relationships & data flow:
1. User issues CLI command or Claude Code trigger → CLI reads PAI_DIR → loads Skills/Workflows.
2. Skill selects Workflow → Agents Manager spins up parallel Agents.
3. Each Agent invokes Implementation (code or MCP API calls) → returns results.
4. Hooks intercept events/results → write to Observability backend.
6. Voice-Server listens on configured port → receives text notifications → calls TTS providers → streams audio back to user.
c. Architectural patterns & principles:
- Skills-as-Containers: each skill self-contained with metadata, workflows, assets
- Progressive disclosure: minimal context on “Always-On,” detailed context loaded on demand
- Natural language routing: user intent → skill/workflow auto-selection
- Parallel agent orchestration for throughput
- Hooks system for modular lifecycle extensions (observability, context loading, docs updates)
- Microservices for observability & TTS decoupled from CLI/core logic
d. Key technologies/frameworks:
- Shell/Bash scripts for CLI and setup
- Bun + TypeScript for voice-server and hooks
- Node.js/TypeScript for observability server
- Vue 3 for observability frontend (agent-observability skill)
- Svelte for Fabric skill web UI
- Markdown-based workflows & skill descriptors
- External APIs: Anthropic Claude, OpenAI, Gemini, Perplexity, MCP servers (Chrome DevTools, Apify, BrightData)

##### Elements
- CLI → Skills loader → Agents Manager
- Agents → Direct Code/APIs (MCPs)
- Hooks capturing events → Observability backend → frontend
- CLI or Hooks → Voice-Server
- CLI & Config (e.g., gray)
- Skills & Workflows (blue)
- Agents (green)
- Implementation (purple)
- Microservices (orange)
- External APIs (red)
- Directional arrowheads for data flow and dependencies.

##### Detailed capture of essential elements
- Hooks subsystem as a sidecar that connects to both the Agents Manager and the Observability Service.
- PAI_DIR environment variable is annotated as the config switch that mounts `.claude/` in user’s home.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "CLI & Config"
        CLI["PAI CLI"]:::cli
        Status["Statusline & Aliases"]:::cli
        Config["Config & MCP Mapping"]:::cli
    end
    CLI -->|reads PAI_DIR & loads| SkillsLoader["Skills & Workflows Loader"]:::skills
    Status -->|integrates with| CLI
    Config -->|provides| CLI

    subgraph "Skills & Workflows"
        SkillsContainer[".claude/skills"]:::skills
    end
    SkillsLoader --> SkillsContainer

    subgraph "Agents Manager"
        Agents["Agent Manager"]:::agents
    end
    SkillsContainer --> Agents

    subgraph "Implementation Layer"
        DirectCode["Direct Code (TS, Python)"]:::implementation
        MCPs["MCPs / External APIs"]:::external
    end
    Agents --> DirectCode
    Agents --> MCPs

    subgraph "Hooks Subsystem"
        HooksCore["Core Hooks"]:::implementation
        HooksLib["Hook Libraries"]:::implementation
        HooksUtil["Hook Utilities"]:::implementation
    end
    DirectCode --> HooksCore
    MCPs --> HooksCore
    HooksLib --> HooksCore
    HooksUtil --> HooksCore

    subgraph "Observability Service" 
        ObsBackend["Backend (Node + DB)"]:::microservices
        ObsFrontend["Frontend (Vue UI)"]:::microservices
    end
    HooksCore -->|writes events| ObsBackend
    ObsBackend -->|serves data| ObsFrontend

    subgraph "Voice-Server (.claude/voice-server)"
        VoiceServer["TTS Service (Bun TS)"]:::microservices
    end
    HooksCore -->|sends text| VoiceServer

    click CLI "https://github.com/danielmiessler/personal_ai_infrastructure/blob/main/.claude/setup.sh"
    click Status "https://github.com/danielmiessler/personal_ai_infrastructure/blob/main/.claude/statusline-command.sh"
    click Status "https://github.com/danielmiessler/personal_ai_infrastructure/tree/main/.claude/zshrc-aliases"
    click Config "https://github.com/danielmiessler/personal_ai_infrastructure/blob/main/.claude/.mcp.json"
    click SkillsContainer "https://github.com/danielmiessler/personal_ai_infrastructure/blob/main/.claude/skills/**/SKILL.md"
    click SkillsContainer "https://github.com/danielmiessler/personal_ai_infrastructure/blob/main/.claude/skills/**/workflows/*.md"
    click Agents "https://github.com/danielmiessler/personal_ai_infrastructure/blob/main/.claude/agents/*.md"
    click HooksCore "https://github.com/danielmiessler/personal_ai_infrastructure/blob/main/.claude/hooks/*.ts"
    click HooksLib "https://github.com/danielmiessler/personal_ai_infrastructure/tree/main/.claude/hooks/lib/"
    click HooksUtil "https://github.com/danielmiessler/personal_ai_infrastructure/tree/main/.claude/hooks/utils/"
    click ObsBackend "https://github.com/danielmiessler/personal_ai_infrastructure/tree/main/.claude/skills/agent-observability/apps/server/"
    click ObsFrontend "https://github.com/danielmiessler/personal_ai_infrastructure/tree/main/.claude/skills/agent-observability/apps/client/"
    click VoiceServer "https://github.com/danielmiessler/personal_ai_infrastructure/blob/main/.claude/voice-server/server.ts"

    classDef cli fill:#EEEEEE,stroke:#333,stroke-width:1px
    classDef skills fill:#BBDEFB,stroke:#1E88E5,stroke-width:1px
    classDef agents fill:#C8E6C9,stroke:#388E3C,stroke-width:1px
    classDef implementation fill:#E1BEE7,stroke:#8E24AA,stroke-width:1px
    classDef microservices fill:#FFE0B2,stroke:#FB8C00,stroke-width:1px
    classDef external fill:#FFCDD2,stroke:#E53935,stroke-width:1px
```
