# 4z0n4s/callisto architecture

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

- Interactive diagram: https://gitdiagram.com/4z0n4s/callisto
- Repository: https://github.com/4z0n4s/callisto

## Overview

##### Project type and purpose
- This is an open‑source, containerized automation tool that records live streams from the Naver 치지직(CHZZK) platform.
- It comprises two cooperating micro‑services: one to detect and record live streams, and another to post‑process the recordings.

##### File structure
- Dockerfile: builds a Python 3.12.2 environment with Streamlink and FFmpeg
- callisto.py: “recorder” service that polls the CHZZK API, starts/stops Streamlink sessions, produces .ts + .lock files
- callisto_ffmpeg.py: “post‑processor” service that runs FFmpeg every 5 minutes to correct stream duration, outputs final .mp4, cleans up intermediates
- docker-compose.yml: defines two services (callisto, callisto‑ffmpeg) sharing a volume
- default.env: CHANNEL_ID, NID_AUT, NID_SES environment variables
- requirements.txt: Python dependencies (Streamlink)

##### README for additional insights
- Poll CHZZK API every 1 min for stream start; during recording poll every 10 sec for stop
- callisto‑ffmpeg polls for .lock files every 5 min to trigger FFmpeg correction
- Final .mp4 stored; intermediate .ts/.lock files removed

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External API
    api["Naver CHZZK API"]:::external

    %% Infrastructure
    subgraph "Docker Infrastructure"
        compose["Docker Compose"]:::orchestration
        dockerEngine["Docker Engine"]:::orchestration
    end

    %% Configuration files
    subgraph "Configuration"
        dockerfile["Dockerfile"]:::config
        env["default.env"]:::config
        req["requirements.txt"]:::config
        readme["README.md"]:::config
    end

    %% Containers
    subgraph "Microservices"
        direction TB
        callistoRecorder["callisto Recorder Service"]:::container
        callistoFFmpeg["callisto-ffmpeg Post-processor Service"]:::container
    end

    %% Shared Volume
    volume[(Shared Volume)]:::storage

    %% Interactions
    callistoRecorder -.->|"poll every 1min (start) / 10s (stop)"| api
    callistoRecorder -->|"writes .ts & .lock files"| volume
    callistoFFmpeg -.->|"poll every 5min"| volume
    callistoFFmpeg -->|"runs FFmpeg, writes .mp4, cleans intermediates"| volume

    %% Orchestration relationships
    compose -->|orchestrates| callistoRecorder
    compose -->|orchestrates| callistoFFmpeg
    dockerEngine -->|runs containers| compose

    %% Configuration usage
    dockerfile -->|builds image| callistoRecorder
    dockerfile -->|builds image| callistoFFmpeg
    env -->|provides env vars| callistoRecorder
    env -->|provides env vars| callistoFFmpeg
    req -->|installs deps| callistoRecorder
    req -->|installs deps| callistoFFmpeg
    readme -->|documents usage| compose

    %% Click Events
    click callistoRecorder "https://github.com/4z0n4s/callisto/blob/main/callisto.py"
    click callistoFFmpeg "https://github.com/4z0n4s/callisto/blob/main/callisto_ffmpeg.py"
    click dockerfile "https://github.com/4z0n4s/callisto/tree/main/Dockerfile"
    click compose "https://github.com/4z0n4s/callisto/blob/main/docker-compose.yml"
    click env "https://github.com/4z0n4s/callisto/blob/main/default.env"
    click req "https://github.com/4z0n4s/callisto/blob/main/requirements.txt"
    click readme "https://github.com/4z0n4s/callisto/blob/main/README.md"

    %% Styles
    classDef external fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef orchestration fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef config fill:#F5DEB3,stroke:#333,stroke-width:1px
    classDef container fill:#B0E0E6,stroke:#333,stroke-width:1px
    classDef storage fill:#FFA07A,stroke:#333,stroke-width:1px
```
