# mon1-innovation/maica architecture

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

- Interactive diagram: https://gitdiagram.com/mon1-innovation/maica
- Repository: https://github.com/mon1-innovation/maica

## Overview

MAICA is a conversational backend with WebSocket and HTTP interfaces, centered on a user-session workflow: prepare context and tools, generate a response, run post-generation triggers and checks, then persist session state. Its documented capabilities also include memory and inspiration features, weather/event/search tools, image understanding, and quality checks. The graph follows relationships shown in excerpts or documented in the README; links to unsampled runtime integrations are omitted or marked unverified.

Main entry points: [`maica/mtrigger/post_core_pipeliner.py`](https://github.com/mon1-innovation/maica/blob/main/maica/mtrigger/post_core_pipeliner.py) (Post-generation pipeline), [`maica/mtools/__init__.py`](https://github.com/mon1-innovation/maica/blob/main/maica/mtools/__init__.py) (Tool registry), [`maica/mfocus/pre_core_pipeliner.py`](https://github.com/mon1-innovation/maica/blob/main/maica/mfocus/pre_core_pipeliner.py) (Pre-generation pipeline), [`maica/maica_utils/database_utils.py`](https://github.com/mon1-innovation/maica/blob/main/maica/maica_utils/database_utils.py) (Database access)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Client interfaces"]
  node_ws["WebSocket service<br/>[maica_ws.py]"]
  node_http["HTTP service<br/>[maica_http.py]"]
end

subgraph group_conversation["Conversation workflow"]
  node_pre["Pre-generation pipeline"]
  node_focus["MFocus agent<br/>[mfocus_llm.py]"]
  node_trigger["MTrigger agent<br/>[mtrigger_llm.py]"]
  node_post["Post-generation pipeline"]
end

subgraph group_capabilities["Assistant capabilities"]
  node_tools["Tool registry<br/>[__init__.py]"]
  node_agent_tools["Agent tools<br/>[agent_tools.py]"]
  node_search["Search and events<br/>[serp_get.py]"]
  node_vision["Image understanding<br/>[img_proc.py]"]
  node_quality["Quality checks<br/>[quality_chk.py]"]
  node_memory["Memory conclusion<br/>[memory_concl.py]"]
end

subgraph group_state["State and persistence"]
  node_db_utils["Database access<br/>[database_utils.py]"]
  node_models["Database models<br/>[database_models.py]"]
  node_database[("SQL database")]
end

node_client(("Chat client"))
node_http_client(("HTTP client"))

node_client -->|"connects to"| node_ws
node_http_client -->|"sends requests"| node_http
node_pre -->|"runs agent"| node_focus
node_pre -->|"invokes tools"| node_tools
node_pre -->|"queries helper"| node_search
node_post -->|"runs trigger"| node_trigger
node_post -->|"checks response"| node_quality
node_post -->|"concludes memory"| node_memory
node_post -.->|"saves session"| node_db_utils
node_db_utils -->|"uses models"| node_models
node_db_utils -->|"queries database"| node_database
node_tools -->|"exports capability"| node_vision
node_tools -->|"exports capability"| node_quality
node_tools -->|"exports capability"| node_memory

click node_ws "https://github.com/mon1-innovation/maica/blob/main/maica/maica_ws.py"
click node_http "https://github.com/mon1-innovation/maica/blob/main/maica/maica_http.py"
click node_pre "https://github.com/mon1-innovation/maica/blob/main/maica/mfocus/pre_core_pipeliner.py"
click node_focus "https://github.com/mon1-innovation/maica/blob/main/maica/mfocus/mfocus_llm.py"
click node_trigger "https://github.com/mon1-innovation/maica/blob/main/maica/mtrigger/mtrigger_llm.py"
click node_post "https://github.com/mon1-innovation/maica/blob/main/maica/mtrigger/post_core_pipeliner.py"
click node_tools "https://github.com/mon1-innovation/maica/blob/main/maica/mtools/__init__.py"
click node_agent_tools "https://github.com/mon1-innovation/maica/blob/main/maica/maica_utils/agent_tools.py"
click node_search "https://github.com/mon1-innovation/maica/blob/main/maica/mtools/serp_get.py"
click node_vision "https://github.com/mon1-innovation/maica/blob/main/maica/mtools/mvista/img_proc.py"
click node_quality "https://github.com/mon1-innovation/maica/blob/main/maica/mtools/quality_chk.py"
click node_memory "https://github.com/mon1-innovation/maica/blob/main/maica/mtools/memory_concl.py"
click node_db_utils "https://github.com/mon1-innovation/maica/blob/main/maica/maica_utils/database_utils.py"
click node_models "https://github.com/mon1-innovation/maica/blob/main/maica/maica_utils/database_models.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_ws,node_http,node_client,node_http_client toneBlue
class node_pre,node_focus,node_trigger,node_post toneAmber
class node_tools,node_agent_tools,node_search,node_vision,node_quality,node_memory toneMint
class node_db_utils,node_models,node_database toneRose
```

## Components

### Client interfaces

- [WebSocket service](https://github.com/mon1-innovation/maica/blob/main/maica/maica_ws.py): `maica/maica_ws.py`
- [HTTP service](https://github.com/mon1-innovation/maica/blob/main/maica/maica_http.py): `maica/maica_http.py`

### Conversation workflow

- [Pre-generation pipeline](https://github.com/mon1-innovation/maica/blob/main/maica/mfocus/pre_core_pipeliner.py): `maica/mfocus/pre_core_pipeliner.py`
- [MFocus agent](https://github.com/mon1-innovation/maica/blob/main/maica/mfocus/mfocus_llm.py): `maica/mfocus/mfocus_llm.py`
- [MTrigger agent](https://github.com/mon1-innovation/maica/blob/main/maica/mtrigger/mtrigger_llm.py): `maica/mtrigger/mtrigger_llm.py`
- [Post-generation pipeline](https://github.com/mon1-innovation/maica/blob/main/maica/mtrigger/post_core_pipeliner.py): `maica/mtrigger/post_core_pipeliner.py`

### Assistant capabilities

- [Tool registry](https://github.com/mon1-innovation/maica/blob/main/maica/mtools/__init__.py): `maica/mtools/__init__.py`
- [Agent tools](https://github.com/mon1-innovation/maica/blob/main/maica/maica_utils/agent_tools.py): `maica/maica_utils/agent_tools.py`
- [Search and events](https://github.com/mon1-innovation/maica/blob/main/maica/mtools/serp_get.py): `maica/mtools/serp_get.py`
- [Image understanding](https://github.com/mon1-innovation/maica/blob/main/maica/mtools/mvista/img_proc.py): `maica/mtools/mvista/img_proc.py`
- [Quality checks](https://github.com/mon1-innovation/maica/blob/main/maica/mtools/quality_chk.py): `maica/mtools/quality_chk.py`
- [Memory conclusion](https://github.com/mon1-innovation/maica/blob/main/maica/mtools/memory_concl.py): `maica/mtools/memory_concl.py`

### State and persistence

- [Database access](https://github.com/mon1-innovation/maica/blob/main/maica/maica_utils/database_utils.py): `maica/maica_utils/database_utils.py`
- [Database models](https://github.com/mon1-innovation/maica/blob/main/maica/maica_utils/database_models.py): `maica/maica_utils/database_models.py`
- **SQL database**

### Other components

- **Chat client**
- **HTTP client**

## Connections

- Chat client → WebSocket service: connects to (evidence: `maica/maica_ws.py`)
- HTTP client → HTTP service: sends requests (evidence: `README.md`)
- Pre-generation pipeline → MFocus agent: runs agent (evidence: `maica/mfocus/pre_core_pipeliner.py`)
- Pre-generation pipeline → Tool registry: invokes tools (evidence: `maica/mfocus/pre_core_pipeliner.py`)
- Pre-generation pipeline → Search and events: queries helper (evidence: `maica/mfocus/pre_core_pipeliner.py`)
- Post-generation pipeline → MTrigger agent: runs trigger (evidence: `maica/mtrigger/post_core_pipeliner.py`)
- Post-generation pipeline → Quality checks: checks response (evidence: `maica/mtrigger/post_core_pipeliner.py`)
- Post-generation pipeline → Memory conclusion: concludes memory (evidence: `maica/mtrigger/post_core_pipeliner.py`)
- Post-generation pipeline → Database access: saves session
- Database access → Database models: uses models (evidence: `maica/maica_utils/database_utils.py`)
- Database access → SQL database: queries database (evidence: `maica/maica_utils/database_utils.py`)
- Tool registry → Image understanding: exports capability (evidence: `maica/mtools/__init__.py`)
- Tool registry → Quality checks: exports capability (evidence: `maica/mtools/__init__.py`)
- Tool registry → Memory conclusion: exports capability (evidence: `maica/mtools/__init__.py`)
