How lokwkin/steps-track works
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.