# yellowbean/hastructure architecture

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

- Interactive diagram: https://gitdiagram.com/yellowbean/hastructure
- Repository: https://github.com/yellowbean/hastructure

## Overview

##### Project’s Main Components
- Core Business Engine: Represented by the “src” directory. This contains all modules related to the core financial logic—modules for Accounts, Analytics, Asset classes (submodules like FixedAsset, Lease, Loan, etc.), Deals (with deal actions, validations, queries), Waterfall, Cashflow, and more. This layer is the heart of the modeling computations and cashflow generation.
- Application Entry Point and Orchestration: The “app” directory holds Main.hs and MainBase.hs, signifying the primary executable entry points and bootstrapping logic. This layer initializes the engine and ties together various business components.
- Web/REST API: The presence of “src/WebUI.hs” along with swagger.json and Docker-related files indicate a built-in REST API service that exposes the engine’s functionality. This component is critical for integration with external systems (including Python wrappers, Java, etc.) and for providing the demo UI.
- Integration & Docker Support: Dockerfile, docker-compose.yml, and GitHub workflows point to containerization and automated deployment processes. These elements should be shown as part of the deployment/integration environment where the engine is made available as a service.
- Testing Infrastructure: The “test” directory (with both unit tests and deal-specific tests) indicates a strong emphasis on testing. While not a runtime component, it is worth noting for understanding the architectural rigor and ensuring that the functional flows (e.g., dealing with cashflow and deal validations) are well verified.

##### Relationships and Interactions
- UI/Client Layer: External clients (or the integrated web frontend) send input requests (such as deal descriptions in JSON format) to the REST API.
- API Layer: The WebUI component receives these API calls and then interacts with the Core Business Engine, invoking various modules (e.g., Deal, Asset Class, Accounts, Waterfall) to compute outputs.
- Docker and CI/CD: Visual cues can be added to show that the whole application is containerized and continuously integrated through GitHub workflows.

##### Architectural Patterns and Principles
- Modularity/Layering: Describe how the project separates concerns by isolating core financial logic (in “src”) from the application/startup sequence (in “app”), and the REST API service layers.
- Composability: Emphasize the building block nature where smaller modules (like different asset class handling) are composed to form the complete cashflow engine.
- Integration-ready APIs: Note the adherence to RESTful practices (with Swagger documentation), which allows easy integration with various languages and environments.
- Testing and Continuous Integration: Recognize that unit tests and integration tests (in the “test” folder) ensure reliability and are part of the architectural considerations.

##### Additional Detail Suggestions

End of instructions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "External Clients"
        CLIENT["External Clients"]:::external
    end

    subgraph "API Layer"
        API["REST API (WebUI)"]:::api
        SWAGGER["Swagger Doc"]:::api
    end

    subgraph "Application Orchestration"
        MAIN["Main.hs Entry"]:::entry
        MAINBASE["MainBase.hs Entry"]:::entry
    end

    subgraph "Core Financial Modules (src)"
        ACC["Accounts Module"]:::core
        ANA["Analytics Module"]:::core
        ASM["Asset Module"]:::core
        DEAL["Deal Module"]:::core
        CASH["Cashflow Module"]:::core
        WATER["Waterfall Module"]:::core
        AC["AssetClass Submodules"]:::core
        D2["Deal Submodules"]:::core
    end

    subgraph "Deployment & Integration"
        DOCKER["Dockerfile"]:::integration
        COMPOSE["docker-compose.yml"]:::integration
        WORKFLOWS["GitHub Workflows"]:::integration
    end

    subgraph "Testing Infrastructure"
        TEST["Testing Suite (test)"]:::testing
    end

    %% Connections
    CLIENT -->|"calls"| API
    API -->|"routes"| MAIN
    API -->|"routes"| MAINBASE
    
    %% API Layer invoking core modules
    API -->|"invokes"| ACC
    API -->|"invokes"| DEAL
    API -->|"invokes"| CASH

    %% Application Orchestration calling core modules
    MAIN -->|"calls"| ACC
    MAIN -->|"calls"| DEAL
    MAIN -->|"calls"| CASH

    MAINBASE -->|"calls"| ANA
    MAINBASE -->|"calls"| ASM
    MAINBASE -->|"calls"| WATER

    %% Core modules inter-relations (illustrative)
    DEAL -->|"triggers"| CASH
    CASH -->|"updates"| WATER
    AC -->|"supports"| ASM
    D2 -->|"extends"| DEAL

    %% Deployment & Integration supporting API Layer
    DOCKER --- COMPOSE
    COMPOSE --- WORKFLOWS
    WORKFLOWS --- API

    %% Testing interacts with core modules
    TEST --- ACC
    TEST --- ANA
    TEST --- ASM
    TEST --- DEAL
    TEST --- CASH
    TEST --- WATER
    TEST --- AC
    TEST --- D2

    %% Click Events for Core Business Engine
    click ACC "https://github.com/yellowbean/hastructure/blob/master/src/Accounts.hs"
    click ANA "https://github.com/yellowbean/hastructure/blob/master/src/Analytics.hs"
    click ASM "https://github.com/yellowbean/hastructure/blob/master/src/Asset.hs"
    click DEAL "https://github.com/yellowbean/hastructure/blob/master/src/Deal.hs"
    click CASH "https://github.com/yellowbean/hastructure/blob/master/src/Cashflow.hs"
    click WATER "https://github.com/yellowbean/hastructure/blob/master/src/Waterfall.hs"
    click AC "https://github.com/yellowbean/hastructure/tree/master/src/AssetClass"
    click D2 "https://github.com/yellowbean/hastructure/tree/master/src/Deal"

    %% Click Events for Application Entry Point
    click MAIN "https://github.com/yellowbean/hastructure/blob/master/app/Main.hs"
    click MAINBASE "https://github.com/yellowbean/hastructure/blob/master/app/MainBase.hs"

    %% Click Events for Web/REST API
    click API "https://github.com/yellowbean/hastructure/blob/master/src/WebUI.hs"
    click SWAGGER "https://github.com/yellowbean/hastructure/blob/master/swagger.json"

    %% Click Events for Integration & Docker Support
    click DOCKER "https://github.com/yellowbean/hastructure/tree/master/Dockerfile"
    click COMPOSE "https://github.com/yellowbean/hastructure/blob/master/docker-compose.yml"
    click WORKFLOWS "https://github.com/yellowbean/hastructure/tree/master/.github/workflows"

    %% Click Event for Testing Infrastructure
    click TEST "https://github.com/yellowbean/hastructure/tree/master/test"

    %% Styles
    classDef external fill:#AED6F1,stroke:#333,stroke-width:2px;
    classDef api fill:#82E0AA,stroke:#333,stroke-width:2px;
    classDef entry fill:#F9E79F,stroke:#333,stroke-width:2px;
    classDef core fill:#85C1E9,stroke:#333,stroke-width:2px;
    classDef integration fill:#BB8FCE,stroke:#333,stroke-width:2px;
    classDef testing fill:#F5CBA7,stroke:#333,stroke-width:2px;
```
