# tsukumijima/konomitv architecture

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

- Interactive diagram: https://gitdiagram.com/tsukumijima/konomitv
- Repository: https://github.com/tsukumijima/konomitv

## Overview

##### Main system components
- Client Application – a Vue.js SPA (with its source code under client/) that covers the UI layer, interacts as a PWA and supports installation as desktop or mobile apps.
- API/Backend Server – built with FastAPI. It serves not only the REST APIs (documented by automatically generated Swagger docs) but also the static assets produced by the client’s build (client/dist/). This backend is responsible for orchestrating streaming, handling user management, settings, and connecting to the tuner backends.
- Tuner/Hardware Integration – The backend communicates with external TV tuner systems such as EDCB (or recently, Mirakurun/mirakc) via TCP API (or HTTP API for Mirakurun) as detailed in the configuration (see “一般設定” and “バックエンドの設定”). It will need to deal with tuner management and switching between live engagements.
- Streaming and Encoding Layer – Within the server there are modules that manage video capturing and encoding. Submodules are found in server/app/streams/ and server/app/utils/edcb/. This layer is in charge of invoking FFmpeg or the various hardware encoders to generate streams (including low‑latency or HLS streaming in real time).
- Installer & Deployment Components – The installer directory and Dockerfile plus GitHub Actions workflows indicate that the system comes with a CLI installer/updater that automates installation (in both Windows and Linux) and container builds.
- Logging, Metadata, and Service Management – The server has dedicated directories for logs (server/logs/), migrations (server/app/migrations/), and service monitor components (like PM2 for Linux or Windows Service scripts). This helps maintain an audit trail and supports troubleshooting.
- External Services & Infrastructure – There is also integration with third-party tools such as Let’s Encrypt–related technologies via the “Akebi” component that lets the private network service be accessible over HTTPS via special DNS naming; Tailscale is recommended for external remote access; and support for multiple external dependencies like GPU drivers.

##### Relationships and interactions between components
- The Client (Frontend) communicates with the backend server via HTTPS – note that the system uses a special URL format (mapping the local IP with dashes into a trusted domain) to support secure connections without manual certificate installation.
- The API server acts as the gateway into the system by exposing endpoints for authentication, settings management, scheduling, real‑time streaming and static file access.
- When a user selects a channel or recorded program, the backend will use the appropriate tuner integration (EDCB or Mirakurun) to grab the live or stored media. It then triggers the streaming/encoding layer which may launch an FFmpeg (or hardware encoder) process.
- The streaming module then interacts with Akebi HTTPS Server, which acts as a reverse proxy and “HTTPS‐ifies” the connection before delivering the stream to the client.
- Deployment and service orchestration (via the installer, Docker Compose files, and service scripts) ensure that the backend (and related external processes like the audio/video encoders) are running on supported platforms with proper logging.

##### Important architectural design principles and patterns
- Separation of Concerns is clear: the client is entirely decoupled from the backend API, and the backend further separates routing, models, streaming tasks, and utility functions.
- Modular design – The project structure separates concerns into clear folders (e.g., client for UI, server for API and streaming backend, installer for installation scripts).
- Use of containerization and CI/CD – Dockerfiles and GitHub workflows indicate that deployment and third-party dependency management is automated.
- Scalability in terms of multiple simultaneous streams is considered, especially regarding hardware encoder session constraints.
- Security by design – the unusual Akebi solution and reliance on HTTPS even on a local network shows attention to modern browser security requirements.

##### Key technologies, frameworks, and libraries
- Client: Vue.js 3, Vuetify 3, SCSS custom styles, and service workers for PWA features.
- Backend: Python 3.11, FastAPI, Tortoise ORM, Uvicorn, and a series of Python modules for metadata and streaming.
- Streaming/Encoding: FFmpeg, QSVEncC, NVEncC, VCEEncC, rkmppenc.
- Deployment: Docker, Windows Service scripts, PM2 for Linux, GitHub Workflows for continuous builds.
- External: EDCB/Mirakurun, Tailscale, Let’s Encrypt–based Akebi, third‑party GPU drivers.

- Connections to note protocols (such as “HTTPS”, “TCP API”, “HTTP API”, “Inter-process Communication”).

- Break the overall system into as many logical components as possible so that interactions are clearly visible.
- Do include details such as the special HTTPS reverse proxy (Akebi) as part of the streaming delivery chain.
- Dual nature of the system (supporting both live TV and recorded video playback) and mark where the respective workflows diverge.

## Diagram (Mermaid)

```mermaid
flowchart TD 
    subgraph "Client Layer"
        A["Vue.js Client"]:::client
    end

    subgraph "Backend / API Layer"
        B["FastAPI Backend"]:::backend
        C["API Router & Static Assets"]:::backend
        D["Tuner Adapter (EDCB/Mirakurun)"]:::integration
        E["Streaming Controller"]:::backend
        F["Streaming & Encoding Manager"]:::streaming
        G["Logging, Metadata & Service Management"]:::logging
    end

    subgraph "External Services"
        H["Tuner Systems (EDCB,Mirakurun)"]:::external
        I["Hardware Encoders (FFmpeg,etc.)"]:::external
        J["Akebi HTTPS Proxy"]:::external
        K["Tailscale & GPU Drivers"]:::external
    end

    subgraph "Deployment"
        L["Installer & Deployment"]:::deployment
    end

    A -->|"HTTPS_API"| B
    B -->|"API_Router"| C
    B -->|"Controls"| D
    B -->|"Triggers"| E
    B -->|"Logs_Metadata"| G
    E -->|"Calls_Stream_Manager"| F
    F -->|"Invokes"| I
    F -->|"Routes_Stream"| J
    D -->|"TCP_API"| H
    J -->|"Stream_to_Client"| A
    L -->|"Deploys"| B

    %% Click Events
    click A "https://github.com/tsukumijima/konomitv/tree/master/client/"
    click B "https://github.com/tsukumijima/konomitv/tree/master/server/"
    click D "https://github.com/tsukumijima/konomitv/tree/master/server/app/utils/edcb/"
    click F "https://github.com/tsukumijima/konomitv/tree/master/server/app/streams/"
    click F "https://github.com/tsukumijima/konomitv/tree/master/server/app/utils/"
    click L "https://github.com/tsukumijima/konomitv/tree/master/installer/"
    click G "https://github.com/tsukumijima/konomitv/tree/master/server/logs/"
    click G "https://github.com/tsukumijima/konomitv/tree/master/server/app/metadata/"
    click G "https://github.com/tsukumijima/konomitv/tree/master/server/app/migrations/"

    %% Styles
    classDef client fill:#AED6F1,stroke:#1F78B4,stroke-width:2px;
    classDef backend fill:#A3E4D7,stroke:#2E8B57,stroke-width:2px;
    classDef integration fill:#F9E79F,stroke:#D4AC0D,stroke-width:2px;
    classDef streaming fill:#D7BDE2,stroke:#8E44AD,stroke-width:2px;
    classDef logging fill:#F5CBA7,stroke:#C0392B,stroke-width:2px;
    classDef external fill:#F9D5E5,stroke:#E74C3C,stroke-width:2px;
    classDef deployment fill:#D6EAF8,stroke:#3498DB,stroke-width:2px;
```
