# kefirchk/animatica-ml-engine architecture

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

- Interactive diagram: https://gitdiagram.com/kefirchk/animatica-ml-engine
- Repository: https://github.com/kefirchk/animatica-ml-engine

## Overview

##### Project Type and Purpose
- This is a hybrid ML-inference engine plus REST API service.
- It provides both a CLI entry point for training/reconstruction/animation (run_model.py) and an HTTP server (FastAPI via run_server.py).

##### File Structure
- Top-level “app” directory contains:
- data/configs & data/checkpoints (model checkpoints & YAML configs)
- src/ml – core ML modules, datasets, augmentation, runners, and services
- src/server – FastAPI app, routers, config, exceptions
- Dockerfile, requirements, entrypoints run_model.py & run_server.py
- Outside “app”: test notebook, docs, CI config, license, pyproject, .gitignore.

##### Main Components
a. External Actors
- CLI User (invokes run_model.py)
- HTTP Client (browser or other service hitting API endpoints)
- External Model Store (Google Drive / Yandex-Disk for pretrained checkpoints)
b. Container / Deployment Unit
- Docker Container (or local venv) hosting the engine
c. Subsystems Inside the Container
1. Configuration Loader
- YAML configs under app/data/configs
- Environment variables (ML_ENGINE_KEY, API_MODE, LOG_LEVEL)
2. Data Layer
- Checkpoints directory under app/data/checkpoints
3. ML Core
- Datasets & Augmentations (app/src/ml/datasets)
- Network Blocks (encoder, decoder, dense_motion, discriminator, generator, keypoint_detector under app/src/ml/modules)
- Runners (training, reconstruction, animation under app/src/ml/runners)
- Services (model I/O, training loop orchestration, video_animation, logging, visualization under app/src/ml/services)
4. REST API Layer (app/src/server)
- Routers exposing /api/fomm/video
- Exception handlers, configuration
5. HTTP Server
- Uvicorn running FastAPI application
6. CLI Layer
- run_model.py entrypoint invoking appropriate runner

##### Relationships and Data Flow
- CLI Flow:
User → run_model.py → Config Loader → Selected Runner (train/reconstruction/animation) → Services → Modules → Output (logs, model checkpoints, generated videos)
- REST Flow:
HTTP Client → Uvicorn FastAPI → Router (/api/fomm/video) → Service Layer (animation service) → ML Modules pipeline → Video Writer → HTTP Response

##### Architectural Patterns & Design Principles
- Layered architecture (CLI/API at top, then services, then core ML modules, then data)
- Separation of concerns:
- Runners orchestrate workflows
- Services wrap module calls and I/O
- Modules implement pure neural-network building blocks
- Configs drive behavior, no hard-coded paths
- Modularity for easy extension (e.g., adding new augmentations, models, runners)

##### Technologies & Frameworks to Annotate
- Python 3.x
- PyTorch (in modules)
- FastAPI + Uvicorn (in server)
- Docker + Dockerfile + docker-compose
- YAML for configs
- pre-commit, pytest or Jupyter for testing

## Diagram (Mermaid)

```mermaid
graph TB
    %% External Actors
    CLI_User["CLI User"]:::external
    HTTP_Client["HTTP Client"]:::external
    Model_Store["External Model Store"]:::external

    %% Container Boundary
    subgraph "Container / Virtual Env"
        direction TB

        %% Layer 1: Entry Points
        subgraph "Layer 1: Entry Points"
            direction TB
            CLI["CLI Entry Point\n(run_model.py)"]:::entry
            HTTP["HTTP Server Entry Point\n(run_server.py)"]:::entry
        end

        %% Layer 2: Orchestration
        subgraph "Layer 2: Orchestration"
            direction TB
            subgraph "Runners"
                direction TB
                TrainingRunner["Training Runner"]:::orch
                ReconstructionRunner["Reconstruction Runner"]:::orch
                AnimationRunner["Animation Runner"]:::orch
            end
            Router["API Router\n(/api/fomm/video)"]:::orch
            subgraph "Services"
                direction TB
                ModelIO["Model I/O Service"]:::orch
                TrainingService["Training Service"]:::orch
                ReconstructionService["Reconstruction Service"]:::orch
                AnimationService["Animation Service"]:::orch
                VideoAnimation["Video Animation Service"]:::orch
                LoggingService["Logging Service"]:::orch
                VisualizationService["Visualization Service"]:::orch
            end
        end

        %% Layer 3: Core ML Modules & Data
        subgraph "Layer 3: Core ML Modules & Data"
            direction TB
            Config["Configuration Loader\n(YAML configs)"]:::data
            Checkpoints["Data Layer\n(Checkpoints)"]:::data
            Datasets["Datasets & Augmentation"]:::core
            Transforms["Augmentation Transforms"]:::core
            Blocks["Network Blocks"]:::core
            Keypoint["Keypoint Detector Module"]:::core
            DenseMotion["Dense Motion Module"]:::core
            Generator["Generator Modules"]:::core
            Discriminator["Discriminator Modules"]:::core
            Utils["Utility Functions"]:::core
        end

        %% Infrastructure file
        Dockerfile["Dockerfile"]:::infra
    end

    %% Connections: CLI Flow
    CLI_User -->|"invoke"| CLI
    CLI -->|run_model.py| TrainingRunner
    CLI -->|run_model.py| ReconstructionRunner
    CLI -->|run_model.py| AnimationRunner
    Config -->|load config| TrainingRunner
    Config -->|load config| ReconstructionRunner
    Config -->|load config| AnimationRunner

    TrainingRunner -->|orchestrate| ModelIO
    ReconstructionRunner -->|orchestrate| ModelIO
    AnimationRunner -->|orchestrate| ModelIO

    ModelIO -->|load weights| Checkpoints
    ModelIO -->|save weights| Checkpoints

    ModelIO -->|start training| TrainingService
    ModelIO -->|start reconstruction| ReconstructionService
    ModelIO -->|start animation| AnimationService

    TrainingService -->|use dataset| Datasets
    TrainingService -->|use transforms| Transforms
    ReconstructionService -->|use dataset| Datasets
    AnimationService -->|use dataset| Datasets

    TrainingService -->|call| Keypoint
    ReconstructionService -->|call| Keypoint
    AnimationService -->|call| Keypoint

    Keypoint -->|features| DenseMotion
    DenseMotion -->|motion map| Generator
    Generator -->|output frames| Discriminator
    Discriminator -->|feedback| TrainingService

    Generator -->|frames| VideoAnimation
    VideoAnimation -->|video file| CLI
    VideoAnimation -->|video file| HTTP

    LoggingService -->|log events| TrainingService
    VisualizationService -->|visualize| TrainingService

    %% Connections: REST Flow
    HTTP_Client -->|"HTTP request"| HTTP
    HTTP -->|"uvicorn"| Router
    Config -->|load config| Router
    Router -->|call animation| AnimationService
    AnimationService -->|pipeline| VideoAnimation
    VideoAnimation -->|HTTP response| HTTP_Client

    %% Model Store
    Model_Store -->|download| ModelIO

    %% Infrastructure
    Dockerfile -->|defines image| CLI
    Dockerfile -->|defines image| HTTP

    %% Click Events
    click CLI "https://github.com/kefirchk/animatica-ml-engine/blob/main/app/src/run_model.py"
    click HTTP "https://github.com/kefirchk/animatica-ml-engine/blob/main/app/src/run_server.py"
    click Dockerfile "https://github.com/kefirchk/animatica-ml-engine/tree/main/app/Dockerfile"
    click Config "https://github.com/kefirchk/animatica-ml-engine/blob/main/app/data/configs/vox-256.yaml"
    click Checkpoints "https://github.com/kefirchk/animatica-ml-engine/tree/main/app/data/checkpoints"
    click Datasets "https://github.com/kefirchk/animatica-ml-engine/tree/main/app/src/ml/datasets"
    click Transforms "https://github.com/kefirchk/animatica-ml-engine/tree/main/app/src/ml/datasets/augmentation/transforms"
    click Blocks "https://github.com/kefirchk/animatica-ml-engine/tree/main/app/src/ml/modules/blocks"
    click DenseMotion "https://github.com/kefirchk/animatica-ml-engine/blob/main/app/src/ml/modules/dense_motion/dense_motion.py"
    click Keypoint "https://github.com/kefirchk/animatica-ml-engine/blob/main/app/src/ml/modules/keypoint_detector/keypoint_detector.py"
    click Generator "https://github.com/kefirchk/animatica-ml-engine/tree/main/app/src/ml/modules/generator"
    click Discriminator "https://github.com/kefirchk/animatica-ml-engine/tree/main/app/src/ml/modules/discriminator"
    click Utils "https://github.com/kefirchk/animatica-ml-engine/tree/main/app/src/ml/modules/utils"
    click TrainingRunner "https://github.com/kefirchk/animatica-ml-engine/blob/main/app/src/ml/runners/training.py"
    click ReconstructionRunner "https://github.com/kefirchk/animatica-ml-engine/blob/main/app/src/ml/runners/reconstruction.py"
    click AnimationRunner "https://github.com/kefirchk/animatica-ml-engine/blob/main/app/src/ml/runners/animation.py"
    click ModelIO "https://github.com/kefirchk/animatica-ml-engine/blob/main/app/src/ml/services/model.py"
    click TrainingService "https://github.com/kefirchk/animatica-ml-engine/blob/main/app/src/ml/services/training.py"
    click ReconstructionService "https://github.com/kefirchk/animatica-ml-engine/blob/main/app/src/ml/services/reconstruction.py"
    click AnimationService "https://github.com/kefirchk/animatica-ml-engine/blob/main/app/src/ml/services/animation.py"
    click VideoAnimation "https://github.com/kefirchk/animatica-ml-engine/blob/main/app/src/ml/services/video_animation.py"
    click LoggingService "https://github.com/kefirchk/animatica-ml-engine/blob/main/app/src/ml/services/logging.py"
    click VisualizationService "https://github.com/kefirchk/animatica-ml-engine/blob/main/app/src/ml/services/visualization.py"
    click Router "https://github.com/kefirchk/animatica-ml-engine/blob/main/app/src/server/routers.py"
    click Config "https://github.com/kefirchk/animatica-ml-engine/blob/main/app/src/server/config.py"
    click ExceptionHandlers "https://github.com/kefirchk/animatica-ml-engine/blob/main/app/src/server/exceptions.py"
    click Model_Store "https://github.com/kefirchk/animatica-ml-engine/tree/main/app/data/checkpoints"

    %% Styles
    classDef entry fill:#add8e6,stroke:#333;
    classDef orch fill:#90ee90,stroke:#333;
    classDef core fill:#ffa500,stroke:#333;
    classDef data fill:#d3d3d3,stroke:#333;
    classDef infra fill:#f0e68c,stroke:#333;
    classDef external fill:#ececec,stroke:#333,stroke-dasharray: 2 2;
```
