# katanaml/katana-skipper architecture

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

- Interactive diagram: https://gitdiagram.com/katanaml/katana-skipper
- Repository: https://github.com/katanaml/katana-skipper

## Overview

##### Project Type and Purpose
- Katana ML Skipper is an event-driven, microservice-based ML workflow engine.
- It provides a FastAPI Web API (“api”) and a generic workflow engine (“workflow”) that orchestrate a set of ML microservices via RabbitMQ.
- Sample ML services (Boston Housing data): data ingestion, model training, model serving, plus a JavaScript “mobilenetservice” and a “logger” service demonstrate extensibility.

##### File Structure Analysis
- Top level:
- api/            → FastAPI Web API implementation
- workflow/       → Workflow logic, JSON definitions
- services/       → Sample ML microservices (dataservice, trainingservice, servingservice, mobilenetservice)
- rabbitmq/       → RabbitMQ broker deployment definitions
- logger/         → Dedicated logging microservice
- skipper-lib/    → Python client library for event communication
- skipper-lib-js/ → Node.js client library for event communication
- Kubernetes and Docker Compose manifests at root (docker-compose.yml, .yaml under api/, rabbitmq/, services, workflow).
- Persistent volumes/persistent volume claims for services that write artifacts (servingservice, trainingservice).
- Standard patterns: Pub/Sub via RabbitMQ, microservice separation by functionality, containerized deployments.

##### Key Components
a. Ingress & API Layer
- NGINX Ingress / Load Balancer
- Skipper FastAPI service (“api” pods/deployment)
- Swagger UI / HTTP interface
b. Workflow Engine
- “workflow” service reading workflow.json, communicating tasks to microservices
c. Message Broker
- RabbitMQ cluster (statefulset, service)
- Exchanges & Queues defined by skipper-lib
d. Microservices
- DataService (Python)
- TrainingService (Python, writes to PV)
- ServingService (Python, two replicas, reads from PV)
- MobileNetService (Node.js)
- Logger service (Python)
e. Supporting Libraries
- skipper-lib (Python)
- skipper-lib-js (JavaScript)
f. Storage & Model Artifacts
- Persistent Volume / PVC for models
- Model zip files under services/models (for reference)

##### Relationships & Data Flows
- HTTP request → NGINX → API → calls Workflow Engine
- Workflow Engine publishes “task created” events to RabbitMQ exchanges
- Each microservice subscribes to its queue, processes events, publishes “task complete” or intermediate events
- Logger service subscribes to all event exchanges for auditing
- API polls or subscribes to results via RabbitMQ (or queries state via Workflow Engine)
- ServingService responds to external prediction requests (optionally via API)

##### Architectural Patterns & Principles
- Event-driven, asynchronous communication (Pub/Sub)
- Microservices: each service independently containerized, language-agnostic
- Repository of reusable communication libraries (skipper-lib, skipper-lib-js)
- Separation of concerns: API, orchestration (workflow), compute (services), messaging (RabbitMQ), logging
- Declarative deployment with Docker Compose and Kubernetes manifests

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global entities
    U["User"]:::external
    Nginx["NGINX Ingress"]:::platform
    API["FastAPI Service<br/>(api/)"]:::platform
    Swagger["Swagger UI"]:::platform
    Workflow["Workflow Engine<br/>(workflow/)"]:::platform
    Doc["workflow.json"]:::document
    Rabbit["RabbitMQ Cluster"]:::messaging
    Storage["Model Artifact Storage<br/>(PVC)"]:::storage

    subgraph "Microservices" 
        direction TB
        DataService["DataService<br/>(Python)"]:::micro
        TrainingService["TrainingService<br/>(Python)"]:::micro
        ServingService["ServingService<br/>(Python)"]:::micro
        MobileNetService["MobileNetService<br/>(Node.js)"]:::micro
        Logger["Logger Service"]:::micro
    end

    subgraph "Client Libraries"
        direction TB
        PythonLib["skipper-lib (Python)"]:::platform
        JSLib["skipper-lib-js (JavaScript)"]:::platform
    end

    %% Connections
    U -->|"HTTP"| Nginx
    Nginx -->|"HTTP"| API
    API -->|"Docs UI"| Swagger
    API -->|"calls Workflow API"| Workflow
    Workflow -->|"reads definition"| Doc
    Workflow -->|"AMQP publish"| Rabbit

    Rabbit -->|"consume"| DataService
    Rabbit -->|"consume"| TrainingService
    Rabbit -->|"consume"| ServingService
    Rabbit -->|"consume"| MobileNetService
    Rabbit -->|"consume"| Logger

    DataService -->|"writes data"| Storage
    TrainingService -->|"writes model"| Storage
    ServingService -->|"reads model"| Storage

    PythonLib -->|"AMQP"| Rabbit
    JSLib -->|"AMQP"| Rabbit

    %% Click Events
    click Nginx "https://github.com/katanaml/katana-skipper/blob/master/nginx_config.conf"
    click API "https://github.com/katanaml/katana-skipper/tree/master/api/"
    click Swagger "https://github.com/katanaml/katana-skipper/blob/master/api/api-ingress.yaml"
    click Workflow "https://github.com/katanaml/katana-skipper/blob/master/workflow/api/workflow.py"
    click Doc "https://github.com/katanaml/katana-skipper/blob/master/workflow/api/workflow.json"
    click Rabbit "https://github.com/katanaml/katana-skipper/blob/master/rabbitmq/rabbit-statefulset.yaml"
    click DataService "https://github.com/katanaml/katana-skipper/blob/master/services/dataservice/app/data_service.py"
    click TrainingService "https://github.com/katanaml/katana-skipper/blob/master/services/trainingservice/app/training_service.py"
    click ServingService "https://github.com/katanaml/katana-skipper/blob/master/services/servingservice/app/serving_service.py"
    click MobileNetService "https://github.com/katanaml/katana-skipper/blob/master/services/mobilenetservice/src/app/mobilenet_service.js"
    click Logger "https://github.com/katanaml/katana-skipper/blob/master/logger/api/logger.py"
    click PythonLib "https://github.com/katanaml/katana-skipper/blob/master/skipper-lib/skipper_lib/events/event_producer.py"
    click JSLib "https://github.com/katanaml/katana-skipper/blob/master/skipper-lib-js/skipper/events/event_producer.js"
    click Storage "https://github.com/katanaml/katana-skipper/blob/master/services/servingservice/servingservice-pv.yaml"

    %% Styles
    classDef platform fill:#cce5ff,stroke:#004085,color:#004085;
    classDef messaging fill:#ffe5b4,stroke:#cc7000,color:#cc7000;
    classDef micro fill:#d4edda,stroke:#155724,color:#155724;
    classDef storage fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef document fill:#fff3cd,stroke:#856404,color:#856404;
    classDef external fill:#f8f9fa,stroke:#6c757d,color:#6c757d;
```
