How milan-panda/autolycus works
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