# lokwkin/steps-track architecture

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

- Interactive diagram: https://gitdiagram.com/lokwkin/steps-track
- Repository: https://github.com/lokwkin/steps-track

## Overview

##### Project Type and Purpose
- This is a **monorepo** for an observability tool (“StepsTrack”) that provides:
– Language-agnostic libraries (TypeScript + Python) for instrumenting and visualizing pipeline steps
– A standalone dashboard service (Node.js + Express + SQLite) to ingest, store, and display step data

##### Top-Level Components
A. “Client Libraries”
– **lib-ts** (packages/lib-ts)
– **lib-py** (packages/lib-py)
B. “Dashboard Service” (packages/dashboard)
C. “External/Infrastructure”

1. **StepsTrack Core** (Pipeline, Step, Decorators, Extensions)
– TS code under `packages/lib-ts/src/*`
– Py code under `packages/lib-py/src/steps_track/*`
2. **Transports & Chart Generators**
– HTTP transport (`http-transport.ts`, `http_transport.py`)
– QuickChart/GoogleChart helper functions
- Inside, show optional decorator layer (`@WithStep` / `@with_step`) wrapping business methods.

- Sub-components:
1. **API Layer** – two routers:
– `ingestion-router.ts` (POST step data)
– `dashboard-router.ts` (GET dashboards, history, stats)
2. **Storage Layer**
– `StorageAdapter` interface + `SqlStorageAdapter` implementation (SQLite)
3. **Static Web UI**
– HTML/CSS/JS under `src/public/*`
– JS modules: api.js, app.js, charts.js, ui.js, utils.js
– Ingestion router → Storage adapter → SQLite
– Dashboard router → Storage adapter → SQLite
– Static UI → Dashboard router (AJAX/fetch)

- **QuickChart.io** (optional external service for chart rendering)
- **Google Charts** (external)
- **Docker** (dashboard runs in `Dockerfile-dashboard`)
- **CI/CD** (GitHub Actions workflows for test & publish)

##### Relationships and Data Flows
1. Your App calls StepsTrack API (in-process) to record steps.
2. If using local chart export → StepsTrack libs call QuickChart/GoogleChart clients directly.
3. If using HTTP transport → StepsTrack batches events → POSTs to Dashboard `/ingest`.
4. Dashboard ingests → persists in SQLite → UI polls or websockets for real-time updates.
5. UI presents Gantt, graphs, stats.

##### Architectural Patterns & Principles
- **Monorepo** with clearly separated packages.
- **Adapter Pattern** for storage and transport (abstract interfaces + concrete impls).
- **Decorator Pattern** for step instrumentation in both TS and Python.
- **Publisher–Subscriber** style: pipeline emits events, transport/ingestion consumes.
- **Separation of Concerns**: libs do instrumentation, dashboard does persistence & display.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application Entry
    App["TS or Python App"]:::app

    %% Client Libraries
    subgraph "Client Libraries"
        direction TB
        subgraph "StepsTrack Core"
            direction TB
            CoreTS["StepsTrack Core (TS)"]:::client
            CorePy["StepsTrack Core (Py)"]:::client
        end
        subgraph "Transports & Chart Generators"
            direction TB
            HTTPTS["HTTP Transport (TS)"]:::client
            HTTPPy["HTTP Transport (Py)"]:::client
            ChartTS["Chart Generators (TS)"]:::client
            ChartPy["Chart Generators (Py)"]:::client
        end
    end

    App -->|"calls API"| CoreTS
    App -->|"calls API"| CorePy
    CoreTS -->|uses HTTP transport| HTTPTS
    CorePy -->|uses HTTP transport| HTTPPy
    CoreTS -->|uses chart helper| ChartTS
    CorePy -->|uses chart helper| ChartPy

    %% Dashboard Service
    subgraph "Dashboard Service"
        direction TB
        subgraph "API Layer"
            direction TB
            Ingest["Ingestion Router"]:::service
            DashboardAPI["Dashboard Router"]:::service
        end
        subgraph "Storage Layer"
            direction TB
            StorageInt["StorageAdapter Interface"]:::service
            SqlStorage["SqlStorageAdapter"]:::service
            DB["SQLite DB"]:::db
        end
        subgraph "Static Web UI"
            direction TB
            UI["Public Assets"]:::ui
        end
    end

    HTTPTS -->|"HTTP POST /ingest"| Ingest
    HTTPPy -->|"HTTP POST /ingest"| Ingest
    Ingest -->|"calls interface"| StorageInt
    DashboardAPI -->|"calls interface"| StorageInt
    StorageInt -->|implements| SqlStorage
    SqlStorage -->|"reads/writes"| DB
    UI -->|"fetch /api"| DashboardAPI

    %% External Infrastructure
    subgraph "External/Infrastructure"
        direction TB
        QuickChart["QuickChart.io"]:::external
        GoogleCharts["Google Charts"]:::external
        Docker["Docker"]:::external
        CICD["CI/CD Workflows"]:::external
    end

    ChartTS -->|optional HTTP| QuickChart
    ChartPy -->|optional HTTP| QuickChart
    ChartTS -->|optional local| GoogleCharts
    ChartPy -->|optional local| GoogleCharts

    Docker -->|"runs Dashboard"| DashboardAPI
    CICD -->|"build & publish"| CoreTS

    %% Click Events
    click CoreTS "https://github.com/lokwkin/steps-track/tree/main/packages/lib-ts/src"
    click CorePy "https://github.com/lokwkin/steps-track/tree/main/packages/lib-py/src/steps_track"
    click HTTPTS "https://github.com/lokwkin/steps-track/blob/main/packages/lib-ts/src/transport/http-transport.ts"
    click HTTPPy "https://github.com/lokwkin/steps-track/blob/main/packages/lib-py/src/steps_track/transport/http_transport.py"
    click ChartTS "https://github.com/lokwkin/steps-track/blob/main/packages/lib-ts/src/chart.ts"
    click ChartPy "https://github.com/lokwkin/steps-track/blob/main/packages/lib-py/src/steps_track/chart.py"
    click Ingest "https://github.com/lokwkin/steps-track/blob/main/packages/dashboard/src/routes/ingestion-router.ts"
    click DashboardAPI "https://github.com/lokwkin/steps-track/blob/main/packages/dashboard/src/routes/dashboard-router.ts"
    click StorageInt "https://github.com/lokwkin/steps-track/blob/main/packages/dashboard/src/storage/storage-adapter.ts"
    click SqlStorage "https://github.com/lokwkin/steps-track/blob/main/packages/dashboard/src/storage/sql-storage-adapter.ts"
    click UI "https://github.com/lokwkin/steps-track/tree/main/packages/dashboard/src/public"
    click Docker "https://github.com/lokwkin/steps-track/tree/main/Dockerfile-dashboard"
    click CICD "https://github.com/lokwkin/steps-track/tree/main/.github/workflows"

    %% Styling
    classDef client fill:#cce5ff,stroke:#4da3ff,color:#003366
    classDef service fill:#d4edda,stroke:#28a745,color:#155724
    classDef db fill:#fff3cd,stroke:#ffc107,color:#856404
    classDef ui fill:#f5c6cb,stroke:#d9534f,color:#721c24
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#383d41
    classDef app fill:#e8daef,stroke:#a64ca6,color:#4b0082
```
