403 lines
10 KiB
Markdown
403 lines
10 KiB
Markdown
# Architecture Diagram - Agent Media
|
||
|
||
## System Overview
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
subgraph Client["👤 Client"]
|
||
CHAT[Chat Interface<br/>OpenWebUI / CLI / Custom]
|
||
end
|
||
|
||
subgraph AgentMedia["🎬 Agent Media"]
|
||
subgraph API["API Layer"]
|
||
FASTAPI[FastAPI Server<br/>:8000]
|
||
end
|
||
|
||
subgraph Core["Core"]
|
||
AGENT[🤖 Agent<br/>Orchestrator]
|
||
MEMORY[🧠 Memory<br/>LTM + STM + Episodic]
|
||
end
|
||
|
||
subgraph Tools["Tools"]
|
||
T1[📁 Filesystem]
|
||
T2[🔍 Search]
|
||
T3[⬇️ Download]
|
||
end
|
||
end
|
||
|
||
subgraph LLM["🧠 LLM Provider"]
|
||
DEEPSEEK[DeepSeek API]
|
||
OLLAMA[Ollama<br/>Local]
|
||
end
|
||
|
||
subgraph External["☁️ External Services"]
|
||
TMDB[(TMDB<br/>Movie Database)]
|
||
KNABEN[(Knaben<br/>Torrent Search)]
|
||
QBIT[qBittorrent<br/>Download Client]
|
||
end
|
||
|
||
subgraph Storage["💾 Storage"]
|
||
JSON[(memory_data/<br/>ltm.json)]
|
||
MEDIA[(Media Folders<br/>/movies /tvshows)]
|
||
end
|
||
|
||
CHAT <-->|OpenAI API| FASTAPI
|
||
FASTAPI <--> AGENT
|
||
AGENT <--> MEMORY
|
||
AGENT <--> Tools
|
||
AGENT <-->|Chat Completion| LLM
|
||
|
||
T1 <--> MEDIA
|
||
T2 --> TMDB
|
||
T2 --> KNABEN
|
||
T3 --> QBIT
|
||
|
||
MEMORY <--> JSON
|
||
QBIT --> MEDIA
|
||
|
||
style AgentMedia fill:#1a1a2e,color:#fff
|
||
style AGENT fill:#ff6b6b,color:#fff
|
||
style MEMORY fill:#4ecdc4,color:#fff
|
||
```
|
||
|
||
## Detailed Architecture
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
subgraph Clients["Clients"]
|
||
direction LR
|
||
OWU[OpenWebUI]
|
||
CLI[CLI Client]
|
||
CURL[cURL / HTTP]
|
||
end
|
||
|
||
subgraph LoadBalancer["Entry Point"]
|
||
NGINX[Nginx / Reverse Proxy<br/>Optional]
|
||
end
|
||
|
||
subgraph Application["Agent Media Application"]
|
||
direction TB
|
||
|
||
subgraph Presentation["Presentation Layer"]
|
||
EP1["/v1/chat/completions"]
|
||
EP2["/v1/models"]
|
||
EP3["/health"]
|
||
EP4["/memory/state"]
|
||
end
|
||
|
||
subgraph AgentLayer["Agent Layer"]
|
||
direction LR
|
||
AG[Agent]
|
||
PB[PromptBuilder]
|
||
REG[Registry]
|
||
end
|
||
|
||
subgraph ToolsLayer["Tools Layer"]
|
||
direction LR
|
||
FS_TOOL[Filesystem Tools<br/>set_path, list_folder]
|
||
API_TOOL[API Tools<br/>find_torrent, add_torrent]
|
||
end
|
||
|
||
subgraph AppLayer["Application Layer"]
|
||
direction LR
|
||
UC1[SearchMovie<br/>UseCase]
|
||
UC2[SearchTorrents<br/>UseCase]
|
||
UC3[AddTorrent<br/>UseCase]
|
||
UC4[SetFolderPath<br/>UseCase]
|
||
end
|
||
|
||
subgraph DomainLayer["Domain Layer"]
|
||
direction LR
|
||
ENT[Entities<br/>Movie, TVShow, Subtitle]
|
||
VO[Value Objects<br/>ImdbId, Quality, FilePath]
|
||
REPO_INT[Repository<br/>Interfaces]
|
||
end
|
||
|
||
subgraph InfraLayer["Infrastructure Layer"]
|
||
direction TB
|
||
|
||
subgraph Persistence["Persistence"]
|
||
MEM[Memory Manager]
|
||
REPO_IMPL[JSON Repositories]
|
||
end
|
||
|
||
subgraph APIClients["API Clients"]
|
||
TMDB_C[TMDB Client]
|
||
KNAB_C[Knaben Client]
|
||
QBIT_C[qBittorrent Client]
|
||
end
|
||
|
||
subgraph FSManager["Filesystem"]
|
||
FM[FileManager]
|
||
end
|
||
end
|
||
end
|
||
|
||
subgraph LLMProviders["LLM Providers"]
|
||
direction LR
|
||
DS[DeepSeek<br/>api.deepseek.com]
|
||
OL[Ollama<br/>localhost:11434]
|
||
end
|
||
|
||
subgraph ExternalAPIs["External APIs"]
|
||
direction LR
|
||
TMDB_API[TMDB API<br/>api.themoviedb.org]
|
||
KNAB_API[Knaben API<br/>knaben.eu]
|
||
QBIT_API[qBittorrent WebUI<br/>localhost:8080]
|
||
end
|
||
|
||
subgraph DataStores["Data Stores"]
|
||
direction LR
|
||
LTM_FILE[(ltm.json<br/>Persistent Config)]
|
||
MEDIA_DIR[(Media Directories<br/>/downloads /movies /tvshows)]
|
||
end
|
||
|
||
%% Client connections
|
||
Clients --> LoadBalancer
|
||
LoadBalancer --> Presentation
|
||
|
||
%% Internal flow
|
||
Presentation --> AgentLayer
|
||
AgentLayer --> ToolsLayer
|
||
ToolsLayer --> AppLayer
|
||
AppLayer --> DomainLayer
|
||
AppLayer --> InfraLayer
|
||
InfraLayer -.->|implements| DomainLayer
|
||
|
||
%% Agent to LLM
|
||
AgentLayer <-->|HTTP| LLMProviders
|
||
|
||
%% Infrastructure to External
|
||
TMDB_C -->|HTTP| TMDB_API
|
||
KNAB_C -->|HTTP| KNAB_API
|
||
QBIT_C -->|HTTP| QBIT_API
|
||
|
||
%% Persistence
|
||
MEM <--> LTM_FILE
|
||
FM <--> MEDIA_DIR
|
||
QBIT_API --> MEDIA_DIR
|
||
```
|
||
|
||
## Memory System Architecture
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
subgraph MemoryManager["Memory Manager"]
|
||
direction TB
|
||
|
||
subgraph LTM["💾 Long-Term Memory"]
|
||
direction LR
|
||
LTM_DESC["Persistent across restarts<br/>Stored in ltm.json"]
|
||
|
||
subgraph LTM_DATA["Data"]
|
||
CONFIG["config{}<br/>folder paths, API keys"]
|
||
PREFS["preferences{}<br/>quality, languages"]
|
||
LIBRARY["library{}<br/>movies[], tv_shows[]"]
|
||
FOLLOWING["following[]<br/>watchlist"]
|
||
end
|
||
end
|
||
|
||
subgraph STM["🧠 Short-Term Memory"]
|
||
direction LR
|
||
STM_DESC["Session-based<br/>Cleared on restart"]
|
||
|
||
subgraph STM_DATA["Data"]
|
||
HISTORY["conversation_history[]<br/>last 20 messages"]
|
||
WORKFLOW["current_workflow{}<br/>type, stage, target"]
|
||
ENTITIES["extracted_entities{}<br/>title, year, quality"]
|
||
TOPIC["current_topic<br/>searching, downloading"]
|
||
end
|
||
end
|
||
|
||
subgraph EPISODIC["⚡ Episodic Memory"]
|
||
direction LR
|
||
EPIS_DESC["Transient state<br/>Cleared on restart"]
|
||
|
||
subgraph EPIS_DATA["Data"]
|
||
SEARCH["last_search_results{}<br/>indexed torrents"]
|
||
DOWNLOADS["active_downloads[]<br/>in-progress"]
|
||
ERRORS["recent_errors[]<br/>last 5 errors"]
|
||
PENDING["pending_question{}<br/>awaiting user input"]
|
||
EVENTS["background_events[]<br/>notifications"]
|
||
end
|
||
end
|
||
end
|
||
|
||
subgraph Storage["Storage"]
|
||
FILE[(memory_data/ltm.json)]
|
||
end
|
||
|
||
subgraph Lifecycle["Lifecycle"]
|
||
SAVE[save()]
|
||
LOAD[load()]
|
||
CLEAR[clear_session()]
|
||
end
|
||
|
||
LTM <-->|read/write| FILE
|
||
SAVE --> LTM
|
||
LOAD --> LTM
|
||
CLEAR --> STM
|
||
CLEAR --> EPISODIC
|
||
|
||
style LTM fill:#4caf50,color:#fff
|
||
style STM fill:#2196f3,color:#fff
|
||
style EPISODIC fill:#ff9800,color:#fff
|
||
```
|
||
|
||
## Request Flow
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
subgraph Request["1️⃣ Request"]
|
||
USER[User Message]
|
||
end
|
||
|
||
subgraph Parse["2️⃣ Parse"]
|
||
FASTAPI[FastAPI<br/>Extract message]
|
||
end
|
||
|
||
subgraph Context["3️⃣ Build Context"]
|
||
PROMPT[PromptBuilder<br/>+ Memory context<br/>+ Tool descriptions]
|
||
end
|
||
|
||
subgraph Think["4️⃣ Think"]
|
||
LLM[LLM<br/>Decide action]
|
||
end
|
||
|
||
subgraph Act["5️⃣ Act"]
|
||
TOOL[Execute Tool<br/>or respond]
|
||
end
|
||
|
||
subgraph Store["6️⃣ Store"]
|
||
MEM[Update Memory<br/>STM + Episodic]
|
||
end
|
||
|
||
subgraph Response["7️⃣ Response"]
|
||
RESP[JSON Response]
|
||
end
|
||
|
||
USER --> FASTAPI --> PROMPT --> LLM
|
||
LLM -->|Tool call| TOOL --> MEM --> LLM
|
||
LLM -->|Text response| MEM --> RESP
|
||
|
||
style Think fill:#ff6b6b,color:#fff
|
||
style Act fill:#4ecdc4,color:#fff
|
||
style Store fill:#45b7d1,color:#fff
|
||
```
|
||
|
||
## Deployment Architecture
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
subgraph Host["Host Machine"]
|
||
subgraph Docker["Docker (Optional)"]
|
||
AGENT_CONTAINER[Agent Media<br/>Container]
|
||
end
|
||
|
||
subgraph Native["Native Services"]
|
||
QBIT_SERVICE[qBittorrent<br/>:8080]
|
||
OLLAMA_SERVICE[Ollama<br/>:11434]
|
||
end
|
||
|
||
subgraph Storage["Local Storage"]
|
||
CONFIG_DIR[/config<br/>memory_data/]
|
||
MEDIA_DIR[/media<br/>downloads, movies, tvshows]
|
||
end
|
||
end
|
||
|
||
subgraph Cloud["Cloud Services"]
|
||
DEEPSEEK[DeepSeek API]
|
||
TMDB[TMDB API]
|
||
KNABEN[Knaben API]
|
||
end
|
||
|
||
subgraph Client["Client"]
|
||
BROWSER[Browser<br/>OpenWebUI]
|
||
end
|
||
|
||
BROWSER <-->|:8000| AGENT_CONTAINER
|
||
AGENT_CONTAINER <-->|:8080| QBIT_SERVICE
|
||
AGENT_CONTAINER <-->|:11434| OLLAMA_SERVICE
|
||
AGENT_CONTAINER <--> CONFIG_DIR
|
||
AGENT_CONTAINER <--> MEDIA_DIR
|
||
QBIT_SERVICE --> MEDIA_DIR
|
||
|
||
AGENT_CONTAINER <-->|HTTPS| Cloud
|
||
```
|
||
|
||
## Technology Stack
|
||
|
||
```mermaid
|
||
mindmap
|
||
root((Agent Media))
|
||
API
|
||
FastAPI
|
||
Uvicorn
|
||
OpenAI Compatible
|
||
Agent
|
||
Python 3.11+
|
||
Dataclasses
|
||
Protocol typing
|
||
LLM
|
||
DeepSeek
|
||
Ollama
|
||
OpenAI compatible
|
||
Storage
|
||
JSON files
|
||
Filesystem
|
||
External APIs
|
||
TMDB
|
||
Knaben
|
||
qBittorrent WebUI
|
||
Architecture
|
||
DDD
|
||
Clean Architecture
|
||
Hexagonal
|
||
```
|
||
|
||
## Security Considerations
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
subgraph Security["Security Layers"]
|
||
direction TB
|
||
|
||
subgraph Input["Input Validation"]
|
||
PATH_VAL[Path Traversal Protection<br/>FileManager._sanitize_path]
|
||
INPUT_VAL[Input Sanitization<br/>Tool parameters]
|
||
end
|
||
|
||
subgraph Auth["Authentication"]
|
||
API_KEYS[API Keys<br/>Environment variables]
|
||
QBIT_AUTH[qBittorrent Auth<br/>Username/Password]
|
||
end
|
||
|
||
subgraph Access["Access Control"]
|
||
FOLDER_RESTRICT[Folder Restrictions<br/>Configured paths only]
|
||
SAFE_PATH[Safe Path Checks<br/>_is_safe_path()]
|
||
end
|
||
end
|
||
|
||
subgraph Env["Environment"]
|
||
ENV_FILE[.env file<br/>DEEPSEEK_API_KEY<br/>TMDB_API_KEY<br/>QBITTORRENT_*]
|
||
end
|
||
|
||
ENV_FILE --> Auth
|
||
Input --> Access
|
||
```
|
||
|
||
## Legend
|
||
|
||
| Icon | Meaning |
|
||
|------|---------|
|
||
| 🎬 | Agent Media System |
|
||
| 🤖 | AI Agent |
|
||
| 🧠 | Memory / LLM |
|
||
| 💾 | Persistent Storage |
|
||
| ⚡ | Transient / Fast |
|
||
| 📁 | Filesystem |
|
||
| 🔍 | Search |
|
||
| ⬇️ | Download |
|
||
| ☁️ | Cloud / External |
|
||
| 👤 | User / Client |
|