312 lines
8.1 KiB
Markdown
312 lines
8.1 KiB
Markdown
# Component Diagram - Agent Media (DDD Architecture)
|
|
|
|
```mermaid
|
|
C4Component
|
|
title Component Diagram - Agent Media
|
|
|
|
Container_Boundary(agent_layer, "Agent Layer") {
|
|
Component(agent, "Agent", "Python", "Orchestrates LLM and tools")
|
|
Component(prompt_builder, "PromptBuilder", "Python", "Builds system prompts with context")
|
|
Component(registry, "Tool Registry", "Python", "Registers and binds tools")
|
|
|
|
Component_Boundary(llm_clients, "LLM Clients") {
|
|
Component(deepseek, "DeepSeekClient", "Python", "DeepSeek API client")
|
|
Component(ollama, "OllamaClient", "Python", "Ollama local client")
|
|
}
|
|
|
|
Component_Boundary(tools, "Tools") {
|
|
Component(api_tools, "API Tools", "Python", "find_torrent, add_torrent, etc.")
|
|
Component(fs_tools, "Filesystem Tools", "Python", "set_path, list_folder")
|
|
}
|
|
}
|
|
```
|
|
|
|
## Layered Architecture (DDD)
|
|
|
|
```mermaid
|
|
flowchart TB
|
|
subgraph Presentation["🌐 Presentation Layer"]
|
|
API["FastAPI Server<br/>/v1/chat/completions"]
|
|
end
|
|
|
|
subgraph Agent["🤖 Agent Layer"]
|
|
AG[Agent]
|
|
PB[PromptBuilder]
|
|
TR[Tool Registry]
|
|
|
|
subgraph LLM["LLM Clients"]
|
|
DS[DeepSeek]
|
|
OL[Ollama]
|
|
end
|
|
|
|
subgraph Tools["Tools"]
|
|
AT[API Tools]
|
|
FT[Filesystem Tools]
|
|
end
|
|
end
|
|
|
|
subgraph Application["⚙️ Application Layer"]
|
|
subgraph UseCases["Use Cases"]
|
|
UC1[SearchMovieUseCase]
|
|
UC2[SearchTorrentsUseCase]
|
|
UC3[AddTorrentUseCase]
|
|
UC4[SetFolderPathUseCase]
|
|
UC5[ListFolderUseCase]
|
|
end
|
|
|
|
subgraph DTOs["DTOs"]
|
|
DTO1[SearchMovieResponse]
|
|
DTO2[SearchTorrentsResponse]
|
|
DTO3[AddTorrentResponse]
|
|
end
|
|
end
|
|
|
|
subgraph Domain["📦 Domain Layer"]
|
|
subgraph Movies["movies/"]
|
|
ME[Movie Entity]
|
|
MVO[MovieTitle, Quality, ReleaseYear]
|
|
MR[MovieRepository Interface]
|
|
end
|
|
|
|
subgraph TVShows["tv_shows/"]
|
|
TE[TVShow Entity]
|
|
TVO[ShowStatus]
|
|
TR2[TVShowRepository Interface]
|
|
end
|
|
|
|
subgraph Subtitles["subtitles/"]
|
|
SE[Subtitle Entity]
|
|
SVO[Language, SubtitleFormat]
|
|
SR[SubtitleRepository Interface]
|
|
end
|
|
|
|
subgraph Shared["shared/"]
|
|
SH[ImdbId, FilePath, FileSize]
|
|
end
|
|
end
|
|
|
|
subgraph Infrastructure["🔧 Infrastructure Layer"]
|
|
subgraph Persistence["persistence/"]
|
|
MEM[Memory<br/>LTM + STM + Episodic]
|
|
JMR[JsonMovieRepository]
|
|
JTR[JsonTVShowRepository]
|
|
JSR[JsonSubtitleRepository]
|
|
end
|
|
|
|
subgraph APIs["api/"]
|
|
TMDB[TMDBClient]
|
|
KNAB[KnabenClient]
|
|
QBIT[QBittorrentClient]
|
|
end
|
|
|
|
subgraph FS["filesystem/"]
|
|
FM[FileManager]
|
|
end
|
|
end
|
|
|
|
subgraph External["☁️ External Services"]
|
|
TMDB_API[(TMDB API)]
|
|
KNAB_API[(Knaben API)]
|
|
QBIT_API[(qBittorrent)]
|
|
DISK[(Filesystem)]
|
|
end
|
|
|
|
%% Connections
|
|
API --> AG
|
|
AG --> PB
|
|
AG --> TR
|
|
AG --> LLM
|
|
TR --> Tools
|
|
|
|
AT --> UC1
|
|
AT --> UC2
|
|
AT --> UC3
|
|
FT --> UC4
|
|
FT --> UC5
|
|
|
|
UC1 --> TMDB
|
|
UC2 --> KNAB
|
|
UC3 --> QBIT
|
|
UC4 --> FM
|
|
UC5 --> FM
|
|
|
|
JMR --> MEM
|
|
JTR --> MEM
|
|
JSR --> MEM
|
|
FM --> MEM
|
|
|
|
JMR -.->|implements| MR
|
|
JTR -.->|implements| TR2
|
|
JSR -.->|implements| SR
|
|
|
|
TMDB --> TMDB_API
|
|
KNAB --> KNAB_API
|
|
QBIT --> QBIT_API
|
|
FM --> DISK
|
|
MEM --> DISK
|
|
|
|
%% Styling
|
|
classDef presentation fill:#e1f5fe
|
|
classDef agent fill:#fff3e0
|
|
classDef application fill:#f3e5f5
|
|
classDef domain fill:#e8f5e9
|
|
classDef infrastructure fill:#fce4ec
|
|
classDef external fill:#f5f5f5
|
|
|
|
class API presentation
|
|
class AG,PB,TR,DS,OL,AT,FT agent
|
|
class UC1,UC2,UC3,UC4,UC5,DTO1,DTO2,DTO3 application
|
|
class ME,MVO,MR,TE,TVO,TR2,SE,SVO,SR,SH domain
|
|
class MEM,JMR,JTR,JSR,TMDB,KNAB,QBIT,FM infrastructure
|
|
class TMDB_API,KNAB_API,QBIT_API,DISK external
|
|
```
|
|
|
|
## Memory Architecture
|
|
|
|
```mermaid
|
|
flowchart LR
|
|
subgraph Memory["Memory System"]
|
|
direction TB
|
|
|
|
subgraph LTM["💾 Long-Term Memory<br/>(Persistent - JSON)"]
|
|
CONFIG[config<br/>download_folder, tvshow_folder...]
|
|
PREFS[preferences<br/>quality, languages...]
|
|
LIB[library<br/>movies[], tv_shows[]]
|
|
FOLLOW[following<br/>watchlist]
|
|
end
|
|
|
|
subgraph STM["🧠 Short-Term Memory<br/>(Session - RAM)"]
|
|
HIST[conversation_history]
|
|
WORKFLOW[current_workflow]
|
|
ENTITIES[extracted_entities]
|
|
TOPIC[current_topic]
|
|
end
|
|
|
|
subgraph EPISODIC["⚡ Episodic Memory<br/>(Transient - RAM)"]
|
|
SEARCH[last_search_results<br/>indexed torrents]
|
|
DOWNLOADS[active_downloads]
|
|
ERRORS[recent_errors]
|
|
PENDING[pending_question]
|
|
EVENTS[background_events]
|
|
end
|
|
end
|
|
|
|
subgraph Storage["Storage"]
|
|
JSON[(ltm.json)]
|
|
end
|
|
|
|
LTM -->|save| JSON
|
|
JSON -->|load| LTM
|
|
|
|
STM -.->|cleared on| RESTART[Server Restart]
|
|
EPISODIC -.->|cleared on| RESTART
|
|
```
|
|
|
|
## Data Flow
|
|
|
|
```mermaid
|
|
flowchart LR
|
|
subgraph Input
|
|
USER[User Request]
|
|
end
|
|
|
|
subgraph Processing
|
|
direction TB
|
|
FASTAPI[FastAPI]
|
|
AGENT[Agent]
|
|
TOOLS[Tools]
|
|
USECASES[Use Cases]
|
|
end
|
|
|
|
subgraph External
|
|
direction TB
|
|
TMDB[(TMDB)]
|
|
KNABEN[(Knaben)]
|
|
QBIT[(qBittorrent)]
|
|
end
|
|
|
|
subgraph Memory
|
|
direction TB
|
|
LTM[(LTM)]
|
|
STM[(STM)]
|
|
EPIS[(Episodic)]
|
|
end
|
|
|
|
USER -->|HTTP POST| FASTAPI
|
|
FASTAPI -->|step()| AGENT
|
|
AGENT -->|execute| TOOLS
|
|
TOOLS -->|call| USECASES
|
|
|
|
USECASES -->|search| TMDB
|
|
USECASES -->|search| KNABEN
|
|
USECASES -->|add| QBIT
|
|
|
|
AGENT <-->|read/write| LTM
|
|
AGENT <-->|read/write| STM
|
|
TOOLS <-->|read/write| EPIS
|
|
|
|
AGENT -->|response| FASTAPI
|
|
FASTAPI -->|JSON| USER
|
|
```
|
|
|
|
## Dependency Direction
|
|
|
|
```mermaid
|
|
flowchart BT
|
|
subgraph External["External"]
|
|
EXT[APIs, Filesystem]
|
|
end
|
|
|
|
subgraph Infra["Infrastructure"]
|
|
INF[Clients, Repositories, Memory]
|
|
end
|
|
|
|
subgraph App["Application"]
|
|
APP[Use Cases, DTOs]
|
|
end
|
|
|
|
subgraph Dom["Domain"]
|
|
DOM[Entities, Value Objects, Interfaces]
|
|
end
|
|
|
|
subgraph Agent["Agent"]
|
|
AGT[Agent, Tools, Prompts]
|
|
end
|
|
|
|
subgraph Pres["Presentation"]
|
|
PRES[FastAPI]
|
|
end
|
|
|
|
EXT --> Infra
|
|
Infra --> App
|
|
Infra -.->|implements| Dom
|
|
App --> Dom
|
|
Agent --> App
|
|
Agent --> Infra
|
|
Pres --> Agent
|
|
|
|
style Dom fill:#e8f5e9,stroke:#4caf50,stroke-width:3px
|
|
style Infra fill:#fce4ec,stroke:#e91e63
|
|
style App fill:#f3e5f5,stroke:#9c27b0
|
|
style Agent fill:#fff3e0,stroke:#ff9800
|
|
style Pres fill:#e1f5fe,stroke:#03a9f4
|
|
```
|
|
|
|
## Legend
|
|
|
|
| Layer | Responsibility | Examples |
|
|
|-------|---------------|----------|
|
|
| 🌐 **Presentation** | HTTP interface, request/response handling | FastAPI endpoints |
|
|
| 🤖 **Agent** | AI orchestration, LLM interaction, tools | Agent, PromptBuilder, Tools |
|
|
| ⚙️ **Application** | Use case orchestration, DTOs | SearchMovieUseCase, SearchTorrentsResponse |
|
|
| 📦 **Domain** | Business entities, rules, interfaces | Movie, TVShow, ImdbId, MovieRepository |
|
|
| 🔧 **Infrastructure** | External service implementations | TMDBClient, JsonMovieRepository, Memory |
|
|
| ☁️ **External** | Third-party services | TMDB API, qBittorrent, Filesystem |
|
|
|
|
## Key Principles
|
|
|
|
1. **Dependency Inversion**: Domain defines interfaces, Infrastructure implements them
|
|
2. **Clean Architecture**: Dependencies point inward (toward Domain)
|
|
3. **Separation of Concerns**: Each layer has a single responsibility
|
|
4. **Memory Segregation**: LTM (persistent), STM (session), Episodic (transient)
|