# gi-tuu/ambrace architecture

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

- Interactive diagram: https://gitdiagram.com/gi-tuu/ambrace
- Repository: https://github.com/gi-tuu/ambrace

## Overview

AMBRACE is a self-hosted AI companion: a user chats with configurable characters, the server builds context from memories and character state, invokes an LLM, and streams a reply. Distinct product stages include recall and response, ongoing memory and life updates, and proactive outreach; the graph also captures voice, social, group-game, phone, and extension capabilities. Exact flow is clearest for sampled modules; several feature links use README descriptions and enclosing source directories where implementation was not sampled.

Main entry points: [`backend/app/api/chat.py`](https://github.com/gi-tuu/ambrace/blob/main/backend/app/api/chat.py) (Chat API), [`backend/app/application/chat_service.py`](https://github.com/gi-tuu/ambrace/blob/main/backend/app/application/chat_service.py) (Chat service), [`backend/app/agent/loop.py`](https://github.com/gi-tuu/ambrace/blob/main/backend/app/agent/loop.py) (Agent loop), [`backend/app/db/engine.py`](https://github.com/gi-tuu/ambrace/blob/main/backend/app/db/engine.py) (SQL database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_conversation["Conversation and cognition"]
  node_chat_api["Chat API<br/>[chat.py]"]
  node_chat_service["Chat service<br/>[chat_service.py]"]
  node_context["Context builder<br/>[context_builder.py]"]
  node_agent["Agent loop<br/>[loop.py]"]
  node_llm["LLM client<br/>[llm_client.py]"]
end

subgraph group_companion["Memory and companion life"]
  node_memory["Memory system"]
  node_relational["Character state"]
  node_life["Life simulation"]
  node_scheduler["Proactive scheduler"]
end

subgraph group_engagement["Social and engagement"]
  node_social["Diary and moments"]
  node_games["Group games"]
  node_voice["Voice services"]
end

subgraph group_integrations["Devices and integrations"]
  node_phone["Phone perception<br/>[phone.py]"]
  node_android_accessibility["Android accessibility"]
  node_android_notifications["Android notifications"]
  node_mcp["MCP manager<br/>[manager.py]"]
  node_plugins["Plugin system"]
  node_channels["Chat channels"]
end

subgraph group_platform["Service and state"]
  node_app["FastAPI app<br/>[main.py]"]
  node_database[("SQL database<br/>[engine.py]")]
  node_notifications["WebSocket notifications<br/>[notify_manager.py]"]
end

node_user(("User"))
node_llm_provider{{"LLM provider"}}

node_user -->|"sends message"| node_chat_api
node_app -->|"registers routes"| node_chat_api
node_chat_api -->|"handles chat"| node_chat_service
node_chat_service -->|"builds context"| node_context
node_chat_service -->|"runs response"| node_agent
node_agent -->|"requests completion"| node_llm
node_llm -->|"calls model"| node_llm_provider
node_context -->|"retrieves memories"| node_memory
node_context -->|"reads state"| node_relational
node_memory -->|"reads and writes"| node_database
node_relational -->|"stores state"| node_database
node_scheduler -->|"advances life"| node_life
node_scheduler -->|"generates activity"| node_social
node_social -->|"stores content"| node_database
node_chat_api -->|"serves game APIs"| node_games
node_chat_api -->|"serves voice APIs"| node_voice
node_android_accessibility -->|"reports perception"| node_phone
node_android_notifications -->|"reports notifications"| node_phone
node_phone -->|"stores perception"| node_database
node_agent -.->|"invokes tools"| node_mcp
node_agent -.->|"uses extensions"| node_plugins
node_channels -.->|"delivers messages"| node_chat_service
node_chat_service -.->|"pushes updates"| node_notifications

click node_chat_api "https://github.com/gi-tuu/ambrace/blob/main/backend/app/api/chat.py"
click node_chat_service "https://github.com/gi-tuu/ambrace/blob/main/backend/app/application/chat_service.py"
click node_context "https://github.com/gi-tuu/ambrace/blob/main/backend/app/agent/context_builder.py"
click node_agent "https://github.com/gi-tuu/ambrace/blob/main/backend/app/agent/loop.py"
click node_llm "https://github.com/gi-tuu/ambrace/blob/main/backend/app/agent/llm_client.py"
click node_memory "https://github.com/gi-tuu/ambrace/tree/main/backend/app/memory"
click node_relational "https://github.com/gi-tuu/ambrace/tree/main/backend/app/domain"
click node_life "https://github.com/gi-tuu/ambrace/tree/main/backend/app/life"
click node_scheduler "https://github.com/gi-tuu/ambrace/tree/main/backend/app/scheduling"
click node_social "https://github.com/gi-tuu/ambrace/tree/main/backend/app/application"
click node_games "https://github.com/gi-tuu/ambrace/tree/main/backend/app/games"
click node_voice "https://github.com/gi-tuu/ambrace/tree/main/backend/app/voice"
click node_phone "https://github.com/gi-tuu/ambrace/blob/main/backend/app/api/phone.py"
click node_android_accessibility "https://github.com/gi-tuu/ambrace/blob/main/flutter_app/android/app/src/main/kotlin/com/gituu/ambrace/PhonePerceptionAccessibilityService.kt"
click node_android_notifications "https://github.com/gi-tuu/ambrace/blob/main/flutter_app/android/app/src/main/kotlin/com/gituu/ambrace/PhonePerceptionNotificationService.kt"
click node_mcp "https://github.com/gi-tuu/ambrace/blob/main/backend/app/mcp/manager.py"
click node_plugins "https://github.com/gi-tuu/ambrace/tree/main/backend/app/plugins"
click node_channels "https://github.com/gi-tuu/ambrace/tree/main/backend/app/providers"
click node_app "https://github.com/gi-tuu/ambrace/blob/main/backend/app/main.py"
click node_database "https://github.com/gi-tuu/ambrace/blob/main/backend/app/db/engine.py"
click node_notifications "https://github.com/gi-tuu/ambrace/blob/main/backend/app/ws/notify_manager.py"

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_chat_api,node_chat_service,node_context,node_agent,node_llm,node_user toneBlue
class node_memory,node_relational,node_life,node_scheduler toneAmber
class node_social,node_games,node_voice toneMint
class node_phone,node_android_accessibility,node_android_notifications,node_mcp,node_plugins,node_channels toneRose
class node_app,node_database,node_notifications,node_llm_provider toneIndigo
```

## Components

### Conversation and cognition

- [Chat API](https://github.com/gi-tuu/ambrace/blob/main/backend/app/api/chat.py): `backend/app/api/chat.py`
- [Chat service](https://github.com/gi-tuu/ambrace/blob/main/backend/app/application/chat_service.py): `backend/app/application/chat_service.py`
- [Context builder](https://github.com/gi-tuu/ambrace/blob/main/backend/app/agent/context_builder.py): `backend/app/agent/context_builder.py`
- [Agent loop](https://github.com/gi-tuu/ambrace/blob/main/backend/app/agent/loop.py): `backend/app/agent/loop.py`
- [LLM client](https://github.com/gi-tuu/ambrace/blob/main/backend/app/agent/llm_client.py): `backend/app/agent/llm_client.py`

### Memory and companion life

- [Memory system](https://github.com/gi-tuu/ambrace/tree/main/backend/app/memory): `backend/app/memory`
- [Character state](https://github.com/gi-tuu/ambrace/tree/main/backend/app/domain): `backend/app/domain`
- [Life simulation](https://github.com/gi-tuu/ambrace/tree/main/backend/app/life): `backend/app/life`
- [Proactive scheduler](https://github.com/gi-tuu/ambrace/tree/main/backend/app/scheduling): `backend/app/scheduling`

### Social and engagement

- [Diary and moments](https://github.com/gi-tuu/ambrace/tree/main/backend/app/application): `backend/app/application`
- [Group games](https://github.com/gi-tuu/ambrace/tree/main/backend/app/games): `backend/app/games`
- [Voice services](https://github.com/gi-tuu/ambrace/tree/main/backend/app/voice): `backend/app/voice`

### Devices and integrations

- [Phone perception](https://github.com/gi-tuu/ambrace/blob/main/backend/app/api/phone.py): `backend/app/api/phone.py`
- [Android accessibility](https://github.com/gi-tuu/ambrace/blob/main/flutter_app/android/app/src/main/kotlin/com/gituu/ambrace/PhonePerceptionAccessibilityService.kt): `flutter_app/android/app/src/main/kotlin/com/gituu/ambrace/PhonePerceptionAccessibilityService.kt`
- [Android notifications](https://github.com/gi-tuu/ambrace/blob/main/flutter_app/android/app/src/main/kotlin/com/gituu/ambrace/PhonePerceptionNotificationService.kt): `flutter_app/android/app/src/main/kotlin/com/gituu/ambrace/PhonePerceptionNotificationService.kt`
- [MCP manager](https://github.com/gi-tuu/ambrace/blob/main/backend/app/mcp/manager.py): `backend/app/mcp/manager.py`
- [Plugin system](https://github.com/gi-tuu/ambrace/tree/main/backend/app/plugins): `backend/app/plugins`
- [Chat channels](https://github.com/gi-tuu/ambrace/tree/main/backend/app/providers): `backend/app/providers`

### Service and state

- [FastAPI app](https://github.com/gi-tuu/ambrace/blob/main/backend/app/main.py): `backend/app/main.py`
- [SQL database](https://github.com/gi-tuu/ambrace/blob/main/backend/app/db/engine.py): `backend/app/db/engine.py`
- [WebSocket notifications](https://github.com/gi-tuu/ambrace/blob/main/backend/app/ws/notify_manager.py): `backend/app/ws/notify_manager.py`

### Other components

- **User**
- **LLM provider**

## Connections

- User → Chat API: sends message
- FastAPI app → Chat API: registers routes
- Chat API → Chat service: handles chat
- Chat service → Context builder: builds context
- Chat service → Agent loop: runs response
- Agent loop → LLM client: requests completion
- LLM client → LLM provider: calls model
- Context builder → Memory system: retrieves memories
- Context builder → Character state: reads state
- Memory system → SQL database: reads and writes
- Character state → SQL database: stores state
- Proactive scheduler → Life simulation: advances life
- Proactive scheduler → Diary and moments: generates activity
- Diary and moments → SQL database: stores content
- Chat API → Group games: serves game APIs
- Chat API → Voice services: serves voice APIs
- Android accessibility → Phone perception: reports perception
- Android notifications → Phone perception: reports notifications
- Phone perception → SQL database: stores perception
- Agent loop → MCP manager: invokes tools
- Agent loop → Plugin system: uses extensions
- Chat channels → Chat service: delivers messages
- Chat service → WebSocket notifications: pushes updates