# 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 |