# ssa-d/ai-tutor architecture

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

- Interactive diagram: https://gitdiagram.com/ssa-d/ai-tutor
- Repository: https://github.com/ssa-d/ai-tutor

## Overview

AI Tutor is a personal study and career assistant. In the implemented web workflow, a user submits a question to the FastAPI endpoint, which checks configuration and calls the LLM adapter for a DeepSeek reply. The Feishu workflow receives chat messages, handles log commands and confirmations, and routes ordinary conversation through persistent chat memory; it can also summarize that day’s saved logs. The README describes Canvas reminders, recommendations, résumé support, and a 3D interface as future plans, not implemented components. The map follows documented behavior and sampled source; planned capabilities have no verified runtime wiring.

Main entry points: [`app/llm.py`](https://github.com/ssa-d/ai-tutor/blob/main/app/llm.py) (LLM Adapter), [`app/feishu.py`](https://github.com/ssa-d/ai-tutor/blob/main/app/feishu.py) (Message Handler), [`app/main.py`](https://github.com/ssa-d/ai-tutor/blob/main/app/main.py) (FastAPI Routes), [`app/memory.py`](https://github.com/ssa-d/ai-tutor/blob/main/app/memory.py) (Chat Memory)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web Q&A"]
  node_api["FastAPI Routes<br/>[main.py]"]
  node_config["Configuration<br/>[config.py]"]
  node_llm["LLM Adapter<br/>[llm.py]"]
end

subgraph group_feishu["Feishu Assistant"]
  node_feishu["Message Handler<br/>[feishu.py]"]
  node_daily_logs["Daily Log Flow<br/>[feishu.py]"]
end

subgraph group_memory["Memory and Logs"]
  node_chat_memory["Chat Memory<br/>[memory.py]"]
  node_storage[("SQLite Storage<br/>[storage.py]")]
end

subgraph group_planned["Planned Capabilities"]
  node_canvas["Canvas Reminders"]
  node_recommendations["Competition and Planning"]
  node_career["Résumé and Jobs"]
  node_visualization["3D Interface"]
end

node_user(("User"))
node_deepseek{{"DeepSeek API"}}
node_feishu_platform(("Feishu Platform"))

node_user -->|"submits question"| node_api
node_api -->|"checks key"| node_config
node_api -->|"asks question"| node_llm
node_llm -->|"reads settings"| node_config
node_llm -->|"sends prompt"| node_deepseek
node_deepseek -->|"returns answer"| node_llm
node_llm -->|"returns reply"| node_api
node_feishu_platform -->|"delivers message"| node_feishu
node_feishu -->|"replies via IM"| node_feishu_platform
node_feishu -->|"routes log intent"| node_daily_logs
node_daily_logs -->|"reads and writes logs"| node_storage
node_daily_logs -->|"requests summary"| node_llm
node_feishu -->|"updates conversation"| node_chat_memory
node_chat_memory -->|"loads and saves history"| node_storage
node_feishu -->|"requests conversation"| node_llm

click node_api "https://github.com/ssa-d/ai-tutor/blob/main/app/main.py"
click node_config "https://github.com/ssa-d/ai-tutor/blob/main/app/config.py"
click node_llm "https://github.com/ssa-d/ai-tutor/blob/main/app/llm.py"
click node_feishu "https://github.com/ssa-d/ai-tutor/blob/main/app/feishu.py"
click node_chat_memory "https://github.com/ssa-d/ai-tutor/blob/main/app/memory.py"
click node_storage "https://github.com/ssa-d/ai-tutor/blob/main/app/storage.py"
click node_daily_logs "https://github.com/ssa-d/ai-tutor/blob/main/app/feishu.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_api,node_config,node_llm,node_user toneBlue
class node_feishu,node_daily_logs toneAmber
class node_chat_memory,node_storage,node_deepseek toneMint
class node_canvas,node_recommendations,node_career,node_visualization toneRose
class node_feishu_platform toneIndigo
```

## Components

### Web Q&A

- [FastAPI Routes](https://github.com/ssa-d/ai-tutor/blob/main/app/main.py): `app/main.py`
- [Configuration](https://github.com/ssa-d/ai-tutor/blob/main/app/config.py): `app/config.py`
- [LLM Adapter](https://github.com/ssa-d/ai-tutor/blob/main/app/llm.py): `app/llm.py`

### Feishu Assistant

- [Message Handler](https://github.com/ssa-d/ai-tutor/blob/main/app/feishu.py): `app/feishu.py`
- [Daily Log Flow](https://github.com/ssa-d/ai-tutor/blob/main/app/feishu.py): `app/feishu.py`

### Memory and Logs

- [Chat Memory](https://github.com/ssa-d/ai-tutor/blob/main/app/memory.py): `app/memory.py`
- [SQLite Storage](https://github.com/ssa-d/ai-tutor/blob/main/app/storage.py): `app/storage.py`

### Planned Capabilities

- **Canvas Reminders**
- **Competition and Planning**
- **Résumé and Jobs**
- **3D Interface**

### Other components

- **User**
- **DeepSeek API**
- **Feishu Platform**

## Connections

- User → FastAPI Routes: submits question
- FastAPI Routes → Configuration: checks key
- FastAPI Routes → LLM Adapter: asks question
- LLM Adapter → Configuration: reads settings
- LLM Adapter → DeepSeek API: sends prompt
- DeepSeek API → LLM Adapter: returns answer
- LLM Adapter → FastAPI Routes: returns reply
- Feishu Platform → Message Handler: delivers message
- Message Handler → Feishu Platform: replies via IM
- Message Handler → Daily Log Flow: routes log intent
- Daily Log Flow → SQLite Storage: reads and writes logs
- Daily Log Flow → LLM Adapter: requests summary
- Message Handler → Chat Memory: updates conversation
- Chat Memory → SQLite Storage: loads and saves history
- Message Handler → LLM Adapter: requests conversation