# tolluset/cauter architecture

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

- Interactive diagram: https://gitdiagram.com/tolluset/cauter
- Repository: https://github.com/tolluset/cauter

## Overview

##### Project type and purpose
- From the README and file tree, this is a backend‐focused, monorepo TypeScript project (“Cauter”) that ingests coin/stock prices (“scheduler”), stores them in a database, and exposes APIs plus analysis logic via an “API server.”
- It’s neither a classic UI-centric full-stack app nor a compiler; it’s more of a microservices/data-pipeline system.

##### File structure
- Top-level: pnpm workspace with three packages:
- packages/scheduler – data collector & batch jobs
- packages/server – REST/HTTP API + analysis routines
- packages/shared – common utilities, types, data models
- Docker Compose files for the database and scheduler service indicate containerized deployment.
- The scheduler package embeds DB migrations, connection code, and a Binance API client.
- No “frontend” directory implies that clients (UI or CLI) are external.

##### Key architectural insights from README
- server handles API endpoints and data analysis.
- scheduler runs cron-style jobs to fetch and persist market data.
- shared holds code reuse points (e.g., database schemas, type definitions).

a. Main components
- Scheduler Service (Node.js + TypeScript)
- API Server (Node.js + TypeScript)
- Shared Library (code module)
- Relational Database (e.g., PostgreSQL)
- External Market Data API (Binance)
- External Clients (e.g., Dashboard, CLI, BI tools)
b. Relationships & data flows
1. Scheduler → (HTTP) → Binance API → market data
2. Scheduler → (ORM/SQL) → Database (writes raw klines)
3. API Server → (ORM/SQL) → Database (reads/aggregates data)
4. Clients → (REST/HTTP) → API Server → responses
5. Both Scheduler & Server import shared code
c. Architectural patterns & principles
- Modular separation (collector vs. API)
- Code sharing via a monorepo (packages/shared)
- Containerized microservices with Docker Compose
- Cron-like scheduling for data ingestion
- Database migrations for schema management
d. Relevant technologies
- TypeScript, Node.js
- PNPM workspace
- Docker Compose (docker-compose.db.yml, docker-compose.scheduler.yml)
- PostgreSQL (or similar SQL database)
- Binance REST API
- ts-node, migration scripts

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    Clients["External Clients"]:::external
    BinanceAPI["Binance REST API"]:::external

    %% Shared Module
    Shared["Shared Library\n(packages/shared)"]:::code
    click Shared "https://github.com/tolluset/cauter/tree/main/packages/shared"

    %% Scheduler Service Container
    subgraph "Scheduler Service Container" 
        direction TB
        SchedulerIndex["Entry Point\n(index.ts)"]:::service
        click SchedulerIndex "https://github.com/tolluset/cauter/blob/main/packages/scheduler/index.ts"
        SchedulerJobs["Cron Jobs\n(jobs/scheduler.ts)"]:::service
        click SchedulerJobs "https://github.com/tolluset/cauter/blob/main/packages/scheduler/jobs/scheduler.ts"
        CollectorService["Binance Collector\n(services/binance-collector.ts)"]:::service
        click CollectorService "https://github.com/tolluset/cauter/blob/main/packages/scheduler/services/binance-collector.ts"
        BinanceClient["Binance API Client\n(clients/binance.client.ts)"]:::service
        click BinanceClient "https://github.com/tolluset/cauter/blob/main/packages/scheduler/clients/binance.client.ts"
        DBConnection["DB Connection\n(db/connection.ts)"]:::service
        click DBConnection "https://github.com/tolluset/cauter/blob/main/packages/scheduler/db/connection.ts"
        Migrations["DB Migrations\n(db/migrations/01_create_binance_klines.ts)"]:::service
        click Migrations "https://github.com/tolluset/cauter/blob/main/packages/scheduler/db/migrations/01_create_binance_klines.ts"

        SchedulerIndex --> SchedulerJobs
        SchedulerJobs --> CollectorService
        CollectorService --> BinanceClient
        CollectorService --> DBConnection
        DBConnection --> Migrations
    end
    click SchedulerService "https://github.com/tolluset/cauter/tree/main/packages/scheduler"

    %% API Server Container
    subgraph "API Server Container"
        direction TB
        APIServer["API Server\n(packages/server)"]:::service
        click APIServer "https://github.com/tolluset/cauter/tree/main/packages/server"
    end

    %% Database
    Database["PostgreSQL Database"]:::db
    click DBCompose "https://github.com/tolluset/cauter/blob/main/docker-compose.db.yml"
    click SchedulerCompose "https://github.com/tolluset/cauter/blob/main/docker-compose.scheduler.yml"
    click PNPMConfig "https://github.com/tolluset/cauter/blob/main/pnpm-workspace.yaml"
    click TSConfig "https://github.com/tolluset/cauter/blob/main/tsconfig.json"

    %% Configs & Compose
    ComposeDB["Docker Compose\n(db)"]:::config
    ComposeScheduler["Docker Compose\n(scheduler)"]:::config
    PNPM["Monorepo Config\n(pnpm-workspace.yaml)"]:::config
    TSConfigNode["TS Config\n(tsconfig.json)"]:::config

    %% Flows
    BinanceAPI -->|Fetch Market Data| SchedulerJobs
    SchedulerJobs -->|Write Kliness| Database
    Database -->|Query/Aggregate| APIServer
    Clients -->|HTTP Requests| APIServer
    APIServer -->|Uses Shared Code| Shared
    SchedulerIndex -->|Uses Shared Code| Shared

    %% Deployment Configs
    ComposeDB --> Database
    ComposeScheduler --> SchedulerIndex
    PNPM --> Shared
    PNPM --> APIServer
    PNPM --> SchedulerIndex
    TSConfigNode --> Shared
    TSConfigNode --> APIServer
    TSConfigNode --> SchedulerIndex

    %% Styles
    classDef service fill:#d1e7dd,stroke:#0f5132,color:#0f5132
    classDef db fill:#cff4fc,stroke:#055160,color:#055160
    classDef external fill:#f8d7da,stroke:#842029,color:#842029
    classDef code fill:#e2e3e5,stroke:#41464b,color:#41464b
    classDef config fill:#fff3cd,stroke:#664d03,color:#664d03
```
