# wat-street/ledger-instances architecture

> Architecture diagram of the GitHub repository wat-street/ledger-instances, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wat-street/ledger-instances
- Repository: https://github.com/wat-street/ledger-instances

## Overview

##### Main Components
- API Backend: At the core is the Flask-based API (app.py) which exposes endpoints like create_ledger, view_ledger, and delete_ledger.
- Database: A PostgreSQL instance (even if currently named “postgres”) stores ledger and possibly trade order data. The README lists planned tables (order_books_v2, trades).
- Model Interaction: The project is designed to integrate with algorithm models that implement the “trade()” and “update_book_status()” functions. Illustrate how these models interact with the ledger data.
- Utility Modules: Several utility modules (in the “utils” folder) manage configurations (db_config), ledger management (ledger_manager, ledger_utils), and integrations with GitHub and Docker. These support the API and database operations.
- SQL Statements: The “sql_statements” directory holds initialization and testing statements essential for setting up and populating the database.
- Containerization: The Dockerfile suggests that containerization/deployment is considered, so include this as an external component enabling smooth deployment.

##### Relationships and Interactions
- Utility modules as supporting the API logic. For example, “ledger_manager” encapsulates the creation, update, deletion, and viewing of ledgers, and “db_config” initializes connections to the Postgres DB.
- Integration of external algorithms (using the defined Model interface) by showing that the API passes ledger details and receives trading actions in return.
- Optionally, note the scheduler (Celery or similar) as an upcoming component that will trigger periodic tasks (like “update_book_status”).

##### Architectural Patterns and Important Technologies
- Use a layered architecture: Present the API layer interfacing with lower-level services (database, utilities, integration with trading models).
- A loosely coupled design where each component – the Flask app, database, utility modules, and external algorithm models – interacts via clearly defined interfaces.
- Technologies/Frameworks: Python (Flask), PostgreSQL, Celery (for scheduling, if adopted), Docker (for containerization), and pytest (for testing).

##### Detailed Elements
- Clear, descriptive labels for components such as “API Endpoints (create, view, delete ledger)”, “Utility Modules (helper functions and integrations)”, “Database (Postgres – order_books_v2, trades)” and “Scheduler (pending Celery integration)”.
– API receives a request → ledger_manager module performs ledger creation logic → SQL scripts or direct queries update the Postgres DB.
– A triggered trade via the API flows into the algorithm’s trade() function and sends back trade execution data.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Services Subgraph
    subgraph "Core Services"
        A1["Flask API – app.py"]:::core
        A2["PostgreSQL DB (order_books_v2, trades)"]:::core
    end

    %% Utility Modules Subgraph
    subgraph "Utility Modules"
        U1["DB Config – utils/db_config.py"]:::utility
        U2["Ledger Manager – utils/ledger_manager.py"]:::utility
        U3["Ledger Utils – utils/ledger_utils.py"]:::utility
        U4["Docker Utils – utils/docker_utils.py"]:::utility
        U5["GitHub Utils – utils/github_utils.py"]:::utility
        U6["Scheduled Tasks – utils/tasks.py"]:::utility
    end

    %% SQL Scripts Subgraph
    subgraph "SQL Scripts"
        S1["SQL Initialization – sql_statements/initialization_stmts.sql"]:::sql
        S2["SQL Testing – sql_statements/testing_stmts.sql"]:::sql
    end

    %% Testing Subgraph
    subgraph "Testing"
        T1["Test Suite – tests/test_functions"]:::test
        T1a["test_create_ledger.py"]:::test
        T1b["test_delete_ledger.py"]:::test
        T1c["test_update_ledger.py"]:::test
        T1d["test_view_ledger.py"]:::test
    end

    %% Containerization/Deployment Subgraph
    subgraph "Containerization"
        D["Docker Deployment – Dockerfile"]:::external
    end

    %% External Integrations
    IM["Trading Models (trade(),update_book_status())"]:::external

    %% Relationships
    A1 -->|"calls"| U2
    A1 -->|"sends ledger data"| IM
    U2 -->|"utilizes"| U3
    U2 -->|"uses connection"| U1
    U1 -->|"connects to"| A2
    U2 -->|"performs db operations"| A2
    S1 -->|"initializes"| A2
    S2 -->|"populates/tests"| A2
    U6 -->|"triggers status update"| A2
    D -->|"deploys"| A1
    D -->|"uses"| U4
    U5 -->|"supports"| D
    T1 -->|"validates API & Ledger Ops"| A1
    T1 -->|"tests"| U2

    %% Testing files hierarchy
    T1 --> T1a
    T1 --> T1b
    T1 --> T1c
    T1 --> T1d

    %% Styles
    classDef core fill:#FFD700,stroke:#8B8000,stroke-width:2px,color:#000;
    classDef utility fill:#90EE90,stroke:#228B22,stroke-width:2px,color:#000;
    classDef sql fill:#FFA07A,stroke:#CD5C5C,stroke-width:2px,color:#000;
    classDef test fill:#ADD8E6,stroke:#00008B,stroke-width:2px,color:#000;
    classDef external fill:#87CEFA,stroke:#4682B4,stroke-width:2px,color:#000;

    %% Click Events
    click A1 "https://github.com/wat-street/ledger-instances/blob/main/app.py"
    click U1 "https://github.com/wat-street/ledger-instances/blob/main/utils/db_config.py"
    click U2 "https://github.com/wat-street/ledger-instances/blob/main/utils/ledger_manager.py"
    click U3 "https://github.com/wat-street/ledger-instances/blob/main/utils/ledger_utils.py"
    click S1 "https://github.com/wat-street/ledger-instances/blob/main/sql_statements/initialization_stmts.sql"
    click S2 "https://github.com/wat-street/ledger-instances/blob/main/sql_statements/testing_stmts.sql"
    click T1 "https://github.com/wat-street/ledger-instances/tree/main/tests/test_functions"
    click D "https://github.com/wat-street/ledger-instances/tree/main/Dockerfile"
    click U4 "https://github.com/wat-street/ledger-instances/blob/main/utils/docker_utils.py"
    click U5 "https://github.com/wat-street/ledger-instances/blob/main/utils/github_utils.py"
    click U6 "https://github.com/wat-street/ledger-instances/blob/main/utils/tasks.py"
```
