Updated README and did a little bit of cleanup
This commit is contained in:
311
docs/component_diagram.md
Normal file
311
docs/component_diagram.md
Normal file
@@ -0,0 +1,311 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user