# milan-panda/autolycus architecture

> Architecture diagram of the GitHub repository milan-panda/autolycus, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/milan-panda/autolycus
- Repository: https://github.com/milan-panda/autolycus

## Overview

##### Project type and purpose
- This is a full-stack, containerized web application (“Autolycus”) that lets users remotely stream torrent files from a home server.
- Frontend: React.js SPA (under ui/)
- Backend API: Python Flask microservice (under api/) exposing REST endpoints for authentication, torrent management, HLS streaming, search, etc.
- Persistent store: PostgreSQL (configured via docker-compose and alembic migrations)
- Auxiliary components: reverse-proxy (nginx under proxy/), libtorrent wrapper, file storage on the host FS.
- Orchestrated with Docker Compose (docker-compose.yml) and CI/CD workflows (.github/workflows).

##### File structure
Top-level:
- .github: CI pipelines to build docker images for API and UI
- api/: Flask app
– endpoints/: route handlers (auth.py, torrents.py, hls_streaming.py, etc.)
– models/: SQLAlchemy models for users, torrents, revoked tokens, public URLs
– migrations/: Alembic setup & scripts
– shared/: utility modules (factories, hls_converter, torrent_name_parser, file_system, logger)
– torrentclient/ & torrentsearch/: components for interacting with libtorrent and external search providers
– config.py, app.py, entrypoint.sh, Dockerfile
- ui/: React app
– src/components/FileManager, services, views, styles
– services/: LoginService, SignupService
– Dockerfile, entrypoint.sh
- proxy/: nginx.conf
- docker-compose.yml
- env.example, README.md, LICENSE.txt

##### Extract architecture insights from README
- Tech stack: Flask, libtorrent, React, Postgres, Docker
- Runtime: all services containerized
- Reverse proxy routes UI traffic and API calls
- API polls torrent engine at intervals for updates (future plan: WebSockets)
- Data flow: React → REST API → torrent engine + Postgres + file system → HLS segments → React

##### Main components and interactions (to be drawn
a. React Frontend (Container)
- Hosts SPA (JavaScript, CSS)
- Communicates over HTTP(S) to the API via a proxy
b. Nginx Reverse-Proxy (Container)
- Listens on ports 80/443
- Routes “/api/*” to Flask API, other paths to React UI
c. Flask API (Container)
- Auth endpoints: login/signup, JWT handling
- Torrent endpoints: add magnet, list files, streaming (HLS), search
- Uses libtorrent wrapper for managing torrent sessions
- Stores metadata in Postgres
- Writes/reads media files and HLS fragments on host FS volume
d. PostgreSQL Database (Container)
- Stores users, torrent metadata, revoked tokens, public URLs
e. Host File System (Docker-mounted volume)
- Stores raw torrent downloads, HLS segments, preview images
f. External Services
- Torrent search providers (TPB, YTS, 1337x, IMDB for metadata)
- Upstream trackers via magnet URI

##### Architectural patterns & design principles
- Separation of concerns: distinct containers for frontend, API, proxy, DB
- RESTful API
- Layered architecture in API: endpoints → service/shared modules → data models → database/file system
- Asynchronous processing of torrent downloads (via libtorrent background threads)
- Infrastructure as code: Dockerfiles + docker-compose for reproducible deployments
- Future extension points: WebSockets for real-time updates, Next.js/Tailwind migration, micro-module (libtorrentx)

- Clear labels: component name, port numbers (e.g., 80, 443, 5000)
- Containers inside a “Docker Compose” boundary to show orchestration

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client["Client\n(Browser/Mobile App)"]:::external
    subgraph "Docker Compose"
        direction TB
        Proxy["Nginx Reverse Proxy\n(Ports 80/443)"]:::container
        UI["React UI\n(Port 3000)"]:::frontend
        API["Flask API\n(Port 5000)"]:::container
        DB["PostgreSQL DB\n(Port 5432)"]:::db
        Storage["Host File Storage\n(Volume)"]:::storage
    end
    ExtServices["External Torrent Trackers\n& Search Providers"]:::external

    Client -->|"HTTPS"| Proxy
    Proxy -->|"/api/*"| API
    Proxy -->|"Static & UI"| UI
    UI -->|"REST API\n(HTTPS)"| API
    API -->|"SQL"| DB
    API -->|"File R/W"| Storage
    API -->|"TCP (libtorrent)"| ExtServices
    API -->|"HTTP REST (Search)"| ExtServices

    click UI "https://github.com/milan-panda/autolycus/tree/main/ui/"
    click Proxy "https://github.com/milan-panda/autolycus/blob/main/proxy/nginx.conf"
    click API "https://github.com/milan-panda/autolycus/tree/main/api/"
    click DB "https://github.com/milan-panda/autolycus/blob/main/docker-compose.yml"
    click Storage "https://github.com/milan-panda/autolycus/blob/main/api/shared/file_system.py"

    classDef frontend fill:#D6EAF8,stroke:#1B4F72,color:#1B2631;
    classDef container fill:#FADBD8,stroke:#922B21,color:#641E16;
    classDef db fill:#ABEBC6,stroke:#1D8348,color:#145A32;
    classDef storage fill:#F9E79F,stroke:#B9770E,color:#7D6608;
    classDef external fill:#F5CBA7,stroke:#D35400,color:#873600;
```
