# bielxdh3/aip architecture

> Architecture diagram of the GitHub repository bielxdh3/aip, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bielxdh3/aip
- Repository: https://github.com/bielxdh3/aip

## Overview

AIP is a local-first agent platform: users interact with persistent agents through the desktop UI, which invokes a Rust-owned core for conversation, state, and persistence; generation crosses a managed NDJSON boundary to a local Ollama host. The graph also preserves documented memory, overlays, tools, voice, vision, extensions, and companion/gateway capabilities. Several Rust subsystems are represented from the repository map and README rather than inspected source; their internal edges are omitted where wiring was not evidenced.

Main entry points: [`apps/desktop/src/App.tsx`](https://github.com/bielxdh3/aip/blob/main/apps/desktop/src/App.tsx) (Agent UI), [`services/runtime/src/aip_runtime/server.py`](https://github.com/bielxdh3/aip/blob/main/services/runtime/src/aip_runtime/server.py) (Python runtime), [`android/app/src/main/java/com/aip/companion/MainActivity.kt`](https://github.com/bielxdh3/aip/blob/main/android/app/src/main/java/com/aip/companion/MainActivity.kt) (Android companion), [`apps/desktop/src-tauri/src/lib.rs`](https://github.com/bielxdh3/aip/blob/main/apps/desktop/src-tauri/src/lib.rs) (Tauri core)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interfaces"]
  node_desktop_ui["Agent UI<br/>[App.tsx]"]
  node_overlay_ui["Agent overlays<br/>[Overlay.tsx]"]
  node_bubble_ui["Agent bubble<br/>[Bubble.tsx]"]
  node_sprite["Agent sprite<br/>[AgentSprite.tsx]"]
  node_conversation_state["Conversation state"]
end

subgraph group_desktop["Desktop core"]
  node_core["Tauri core<br/>[lib.rs]"]
  node_chat["Chat handling<br/>[chat.rs]"]
  node_conversation["Conversation lifecycle<br/>[conversation.rs]"]
  node_database[("SQLite state<br/>[database.rs]")]
  node_cognitive["Agent cognition<br/>[cognitive.rs]"]
  node_tools["Agent tools<br/>[tools.rs]"]
  node_extensions["Extensions<br/>[extensions.rs]"]
  node_voice["Voice<br/>[voice.rs]"]
  node_vision["Screen vision<br/>[screen_vision.rs]"]
  node_overlay_core["Overlay management<br/>[overlays.rs]"]
  node_gateway["Companion gateway<br/>[gateway.rs]"]
end

subgraph group_inference["Local inference"]
  node_runtime["Python runtime<br/>[server.py]"]
  node_protocol["NDJSON protocol<br/>[protocol.py]"]
  node_ollama_adapter["Ollama adapter<br/>[ollama.py]"]
  node_readiness["Ollama lifecycle<br/>[readiness.py]"]
end

subgraph group_companion["Companion access"]
  node_android["Android companion<br/>[MainActivity.kt]"]
  node_secure_store["Secure credentials<br/>[SecureStore.kt]"]
  node_android_overlay["Android overlay<br/>[OverlayService.kt]"]
end

node_user(("User"))
node_ollama["Ollama host"]

node_user -->|"interacts"| node_desktop_ui
node_desktop_ui -->|"invokes commands"| node_core
node_desktop_ui -->|"uses state"| node_conversation_state
node_desktop_ui -->|"renders"| node_sprite
node_user -->|"uses overlay"| node_overlay_ui
node_user -->|"uses bubble"| node_bubble_ui
node_overlay_ui -->|"renders"| node_sprite
node_core -->|"owns persistence"| node_database
node_core -->|"manages boundary"| node_runtime
node_runtime -->|"validates messages"| node_protocol
node_runtime -->|"dispatches requests"| node_ollama_adapter
node_runtime -->|"checks readiness"| node_readiness
node_ollama_adapter -->|"streams generation"| node_ollama
node_readiness -->|"manages lifecycle"| node_ollama
node_cognitive -->|"persists state"| node_database
node_user -->|"connects locally"| node_android
node_android -->|"uses credentials"| node_secure_store
node_android -->|"starts service"| node_android_overlay
node_android -.->|"connects companion"| node_gateway

click node_desktop_ui "https://github.com/bielxdh3/aip/blob/main/apps/desktop/src/App.tsx"
click node_overlay_ui "https://github.com/bielxdh3/aip/blob/main/apps/desktop/src/Overlay.tsx"
click node_bubble_ui "https://github.com/bielxdh3/aip/blob/main/apps/desktop/src/Bubble.tsx"
click node_sprite "https://github.com/bielxdh3/aip/blob/main/apps/desktop/src/components/AgentSprite.tsx"
click node_conversation_state "https://github.com/bielxdh3/aip/blob/main/apps/desktop/src/conversation-state.ts"
click node_core "https://github.com/bielxdh3/aip/blob/main/apps/desktop/src-tauri/src/lib.rs"
click node_chat "https://github.com/bielxdh3/aip/blob/main/apps/desktop/src-tauri/src/chat.rs"
click node_conversation "https://github.com/bielxdh3/aip/blob/main/apps/desktop/src-tauri/src/conversation.rs"
click node_database "https://github.com/bielxdh3/aip/blob/main/apps/desktop/src-tauri/src/database.rs"
click node_cognitive "https://github.com/bielxdh3/aip/blob/main/apps/desktop/src-tauri/src/cognitive.rs"
click node_tools "https://github.com/bielxdh3/aip/blob/main/apps/desktop/src-tauri/src/tools.rs"
click node_extensions "https://github.com/bielxdh3/aip/blob/main/apps/desktop/src-tauri/src/extensions.rs"
click node_voice "https://github.com/bielxdh3/aip/blob/main/apps/desktop/src-tauri/src/voice.rs"
click node_vision "https://github.com/bielxdh3/aip/blob/main/apps/desktop/src-tauri/src/screen_vision.rs"
click node_overlay_core "https://github.com/bielxdh3/aip/blob/main/apps/desktop/src-tauri/src/overlays.rs"
click node_gateway "https://github.com/bielxdh3/aip/blob/main/apps/desktop/src-tauri/src/gateway.rs"
click node_runtime "https://github.com/bielxdh3/aip/blob/main/services/runtime/src/aip_runtime/server.py"
click node_protocol "https://github.com/bielxdh3/aip/blob/main/services/runtime/src/aip_runtime/protocol.py"
click node_ollama_adapter "https://github.com/bielxdh3/aip/blob/main/services/runtime/src/aip_runtime/ollama.py"
click node_readiness "https://github.com/bielxdh3/aip/blob/main/services/runtime/src/aip_runtime/readiness.py"
click node_android "https://github.com/bielxdh3/aip/blob/main/android/app/src/main/java/com/aip/companion/MainActivity.kt"
click node_secure_store "https://github.com/bielxdh3/aip/blob/main/android/app/src/main/java/com/aip/companion/SecureStore.kt"
click node_android_overlay "https://github.com/bielxdh3/aip/blob/main/android/app/src/main/java/com/aip/companion/OverlayService.kt"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_desktop_ui,node_overlay_ui,node_bubble_ui,node_sprite,node_conversation_state,node_user toneBlue
class node_core,node_chat,node_conversation,node_database,node_cognitive,node_tools,node_extensions,node_voice,node_vision,node_overlay_core,node_gateway toneAmber
class node_runtime,node_protocol,node_ollama_adapter,node_readiness toneMint
class node_android,node_secure_store,node_android_overlay toneRose
class node_ollama toneIndigo
```

## Components

### User interfaces

- [Agent UI](https://github.com/bielxdh3/aip/blob/main/apps/desktop/src/App.tsx): `apps/desktop/src/App.tsx`
- [Agent overlays](https://github.com/bielxdh3/aip/blob/main/apps/desktop/src/Overlay.tsx): `apps/desktop/src/Overlay.tsx`
- [Agent bubble](https://github.com/bielxdh3/aip/blob/main/apps/desktop/src/Bubble.tsx): `apps/desktop/src/Bubble.tsx`
- [Agent sprite](https://github.com/bielxdh3/aip/blob/main/apps/desktop/src/components/AgentSprite.tsx): `apps/desktop/src/components/AgentSprite.tsx`
- [Conversation state](https://github.com/bielxdh3/aip/blob/main/apps/desktop/src/conversation-state.ts): `apps/desktop/src/conversation-state.ts`

### Desktop core

- [Tauri core](https://github.com/bielxdh3/aip/blob/main/apps/desktop/src-tauri/src/lib.rs): `apps/desktop/src-tauri/src/lib.rs`
- [Chat handling](https://github.com/bielxdh3/aip/blob/main/apps/desktop/src-tauri/src/chat.rs): `apps/desktop/src-tauri/src/chat.rs`
- [Conversation lifecycle](https://github.com/bielxdh3/aip/blob/main/apps/desktop/src-tauri/src/conversation.rs): `apps/desktop/src-tauri/src/conversation.rs`
- [SQLite state](https://github.com/bielxdh3/aip/blob/main/apps/desktop/src-tauri/src/database.rs): `apps/desktop/src-tauri/src/database.rs`
- [Agent cognition](https://github.com/bielxdh3/aip/blob/main/apps/desktop/src-tauri/src/cognitive.rs): `apps/desktop/src-tauri/src/cognitive.rs`
- [Agent tools](https://github.com/bielxdh3/aip/blob/main/apps/desktop/src-tauri/src/tools.rs): `apps/desktop/src-tauri/src/tools.rs`
- [Extensions](https://github.com/bielxdh3/aip/blob/main/apps/desktop/src-tauri/src/extensions.rs): `apps/desktop/src-tauri/src/extensions.rs`
- [Voice](https://github.com/bielxdh3/aip/blob/main/apps/desktop/src-tauri/src/voice.rs): `apps/desktop/src-tauri/src/voice.rs`
- [Screen vision](https://github.com/bielxdh3/aip/blob/main/apps/desktop/src-tauri/src/screen_vision.rs): `apps/desktop/src-tauri/src/screen_vision.rs`
- [Overlay management](https://github.com/bielxdh3/aip/blob/main/apps/desktop/src-tauri/src/overlays.rs): `apps/desktop/src-tauri/src/overlays.rs`
- [Companion gateway](https://github.com/bielxdh3/aip/blob/main/apps/desktop/src-tauri/src/gateway.rs): `apps/desktop/src-tauri/src/gateway.rs`

### Local inference

- [Python runtime](https://github.com/bielxdh3/aip/blob/main/services/runtime/src/aip_runtime/server.py): `services/runtime/src/aip_runtime/server.py`
- [NDJSON protocol](https://github.com/bielxdh3/aip/blob/main/services/runtime/src/aip_runtime/protocol.py): `services/runtime/src/aip_runtime/protocol.py`
- [Ollama adapter](https://github.com/bielxdh3/aip/blob/main/services/runtime/src/aip_runtime/ollama.py): `services/runtime/src/aip_runtime/ollama.py`
- [Ollama lifecycle](https://github.com/bielxdh3/aip/blob/main/services/runtime/src/aip_runtime/readiness.py): `services/runtime/src/aip_runtime/readiness.py`

### Companion access

- [Android companion](https://github.com/bielxdh3/aip/blob/main/android/app/src/main/java/com/aip/companion/MainActivity.kt): `android/app/src/main/java/com/aip/companion/MainActivity.kt`
- [Secure credentials](https://github.com/bielxdh3/aip/blob/main/android/app/src/main/java/com/aip/companion/SecureStore.kt): `android/app/src/main/java/com/aip/companion/SecureStore.kt`
- [Android overlay](https://github.com/bielxdh3/aip/blob/main/android/app/src/main/java/com/aip/companion/OverlayService.kt): `android/app/src/main/java/com/aip/companion/OverlayService.kt`

### Other components

- **User**
- **Ollama host**

## Connections

- User → Agent UI: interacts (evidence: `README.md`)
- Agent UI → Tauri core: invokes commands (evidence: `apps/desktop/src/App.tsx`)
- Agent UI → Conversation state: uses state (evidence: `apps/desktop/src/App.tsx`)
- Agent UI → Agent sprite: renders (evidence: `apps/desktop/src/App.tsx`)
- User → Agent overlays: uses overlay (evidence: `README.md`)
- User → Agent bubble: uses bubble (evidence: `README.md`)
- Agent overlays → Agent sprite: renders (evidence: `apps/desktop/src/Overlay.tsx`)
- Tauri core → SQLite state: owns persistence (evidence: `README.md`)
- Tauri core → Python runtime: manages boundary (evidence: `README.md`)
- Python runtime → NDJSON protocol: validates messages (evidence: `services/runtime/src/aip_runtime/server.py`)
- Python runtime → Ollama adapter: dispatches requests (evidence: `services/runtime/src/aip_runtime/server.py`)
- Python runtime → Ollama lifecycle: checks readiness (evidence: `services/runtime/src/aip_runtime/server.py`)
- Ollama adapter → Ollama host: streams generation (evidence: `README.md`)
- Ollama lifecycle → Ollama host: manages lifecycle (evidence: `services/runtime/src/aip_runtime/readiness.py`)
- Agent cognition → SQLite state: persists state (evidence: `apps/desktop/src-tauri/src/cognitive.rs`)
- User → Android companion: connects locally (evidence: `README.md`)
- Android companion → Secure credentials: uses credentials (evidence: `android/app/src/main/java/com/aip/companion/MainActivity.kt`)
- Android companion → Android overlay: starts service (evidence: `android/app/src/main/java/com/aip/companion/MainActivity.kt`)
- Android companion → Companion gateway: connects companion (evidence: `README.md`)
