Architecture

System Overview

milmil is a monolithic Go backend with a React SPA frontend, designed for self-hosted deployment.

┌─────────────────────────────────────────────────┐
│                   Clients                       │
│         Browser (PWA)  │  Telegram/Discord Bot  │
└───────────┬─────────────────────┬───────────────┘
            │ HTTP/WS             │ Bot API
┌───────────▼─────────────────────▼───────────────┐
│                milmil-api (Go)                  │
│  ┌──────────┐ ┌──────────┐ ┌──────────────────┐│
│  │ REST API │ │WebSocket │ │ Bot Engine       ││
│  └────┬─────┘ └────┬─────┘ └───────┬──────────┘│
│       │             │               │           │
│  ┌────▼─────────────▼───────────────▼──────────┐│
│  │              Service Layer                  ││
│  │  Library │ Stream │ Download │ Discover     ││
│  │  Collection │ Auth │ Notification           ││
│  └────┬────────────────────────────────────────┘│
│       │                                         │
│  ┌────▼────────────────────────────────────────┐│
│  │           Infrastructure Layer              ││
│  │  PostgreSQL/SQLite │ Redis │ FFmpeg │ Rclone││
│  └─────────────────────────────────────────────┘│
└─────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────┐
│              milmil-web (React SPA)             │
│  Served via Nginx or dev server                 │
└─────────────────────────────────────────────────┘

Component Overview

Component	Description
REST API	Echo router serving JSON endpoints. Handles auth, CRUD, streaming, and search.
WebSocket	Real-time event push for danmaku, notifications, and scan progress.
Bot Engine	Platform-agnostic bot with adapters for Telegram and Discord.
Service Layer	Business logic for library scanning, metadata matching, download management, and collection sync.
FFmpeg	Media probing, container remuxing, and HLS transcoding.
Rclone	Cloud storage abstraction for 40+ providers.

Data Flow: Library Scan

File Discovery

Walk the storage backend (local, SMB, rclone, etc.) to enumerate all media files.

Media Probing

FFmpeg probes each file for codec info, resolution, duration, embedded subtitles, and audio tracks.

Metadata Matching

Match files to anime entries using the provider pipeline: DandanPlay (hash) → Bangumi (title) → AniList (title) → TMDB (fallback).

Enrichment

Fetch cover images, episode titles, descriptions, and ratings from matched providers.

Persistence

Store all metadata in the database. Send scan completion notification.

Data Flow: Streaming

Client request
    │
    ▼
┌─────────────────┐
│ Codec supported? │──yes──▶ Direct Play (byte-range)
└────────┬────────┘
         │ no
         ▼
┌─────────────────┐
│ Container only?  │──yes──▶ Remux (MKV→MP4, no re-encode)
└────────┬────────┘
         │ no
         ▼
    HLS Transcode (FFmpeg)

Technology Stack

Technology	Description
Backend	Go — Chi router, sqlc, golang-migrate, anacrolix/torrent
Frontend	React — Vite, TanStack Router, TanStack Query, Tailwind CSS
Database	PostgreSQL/SQLite — Schema managed with golang-migrate
Cache	Redis — Optional, in-memory fallback available
Media	FFmpeg — Probing, remuxing, HLS transcoding
Storage	Rclone — 40+ cloud provider backends
Docs	Fumadocs — Next.js-based documentation with i18n

Repository Structure

go.mod

Makefile

docker-compose.yml

Makefile

On this page