alfred/docs/component_diagram.md

Component Diagram - Agent Media (DDD Architecture)

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)

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

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

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

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)