# lakhan-nad/splitwise architecture

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

- Interactive diagram: https://gitdiagram.com/lakhan-nad/splitwise
- Repository: https://github.com/lakhan-nad/splitwise

## Overview

##### Project type and purpose
- This is a backend service (a Go-based library or microservice) implementing the core “Splitwise” debt‐splitting logic at low‐level design (LLD) for group expense management.
- The README calls it “splitwise LLD” and mentions TODOs around “debt simplification” and “minimum transactions” algorithms, confirming its focus on business logic rather than a full UI.

##### File structure
- Top-level modules:
- core/        → core algorithms and models (balance mapping, heap‐based minimization, payable simplification)
- splits/      → split‐calculation strategies and strategy interface
- splitwise/   → high-level “manager” or façade to orchestrate splits and contributions
- transaction/ → domain for Transaction, TransactionHistory, Account, plus their repository interfaces
- user/        → User entity and UserRepository
- Supporting files:
- go.mod       → module dependencies
- README.md    → project description and TODOs
- Patterns:
- Layered design—separation of domain models, repositories, business algorithms, and orchestration.
- Strategy pattern in splits/strategies.go
- Repository pattern for persistence interfaces.

##### README for additional insights
- Core focus is on two algorithmic features: “debt simplification like actual splitwise” and “subset‐sum minimum transactions.”
- No existing API layer or database choice is specified; those would be external integrations.

##### Elements
- Blue: API/Manager (orchestration)
- Green: Strategy & Core algorithm modules (business logic)
- Yellow: Domain entities (models)
- Gray: Repositories & database (persistence)
- Notes on key interfaces: splits.Strategy, UserRepo, TransactionRepo

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation/API Layer
    API["HTTP API / CLI"]:::orchestration

    %% Orchestration Layer
    Manager["splitwise.Manager"]:::orchestration
    Contribution["splitwise.Contribution"]:::orchestration

    %% Strategy Layer
    subgraph "Strategy Layer"
        StrategyIF["Strategy Interface"]:::logic
        Strategies["Strategy Implementations"]:::logic
        SplitModel["Split Domain Model"]:::logic
    end

    %% Core Algorithms Layer
    subgraph "Core Algorithms"
        CoreEntry["Core Algorithm Entry-Point"]:::logic
        BalanceMap["Balance Map Simplification"]:::logic
        HeapMin["Heap Cash-Flow Minimisation"]:::logic
        PayableSimplify["Payable Simplification Logic"]:::logic
    end

    %% Domain Models
    subgraph "Domain Models"
        User["User Entity"]:::domain
        TransactionEnt["Transaction Entity"]:::domain
        TransHistory["TransactionHistory Entity"]:::domain
        TransAccountEnt["Transaction-Account Entity"]:::domain
        PayableModel["Payable Model"]:::domain
    end

    %% Repository Interfaces
    subgraph "Repository Interfaces"
        UserRepo["UserRepository Interface"]:::persistence
        TransRepo["TransactionRepository Interface"]:::persistence
        AccountRepo["TransactionAccountRepository Interface"]:::persistence
    end

    %% Persistence Layer
    Database["Database (SQL/NoSQL)"]:::persistence

    %% Data Flows
    API -->|calls| Manager
    Manager -->|loads| UserRepo
    Manager -->|loads| TransRepo
    Manager -->|loads| AccountRepo
    Manager -->|orchestrates| Contribution
    Manager -->|selects strategy| StrategyIF
    StrategyIF -->|implemented by| Strategies
    Manager -->|uses| Strategies
    Strategies -->|invoke| CoreEntry
    CoreEntry -->|executes| BalanceMap
    CoreEntry -->|executes| HeapMin
    BalanceMap -->|simplifies| PayableSimplify
    HeapMin -->|simplifies| PayableSimplify
    PayableSimplify -->|produces| PayableModel
    Manager -->|returns| PayableModel
    Manager -->|saves| TransRepo
    Manager -->|saves| AccountRepo
    UserRepo -->|persists to| Database
    TransRepo -->|persists to| Database
    AccountRepo -->|persists to| Database

    %% Click events
    click Manager "https://github.com/lakhan-nad/splitwise/blob/main/splitwise/manager.go"
    click Contribution "https://github.com/lakhan-nad/splitwise/blob/main/splitwise/contribution.go"
    click StrategyIF "https://github.com/lakhan-nad/splitwise/blob/main/splits/strategy.go"
    click Strategies "https://github.com/lakhan-nad/splitwise/blob/main/splits/strategies.go"
    click SplitModel "https://github.com/lakhan-nad/splitwise/blob/main/splits/split.go"
    click CoreEntry "https://github.com/lakhan-nad/splitwise/blob/main/core/algo.go"
    click BalanceMap "https://github.com/lakhan-nad/splitwise/blob/main/core/balance_map_simplify.go"
    click HeapMin "https://github.com/lakhan-nad/splitwise/blob/main/core/heap_cash_flow_minimise.go"
    click PayableSimplify "https://github.com/lakhan-nad/splitwise/blob/main/core/payable_simplify.go"
    click PayableModel "https://github.com/lakhan-nad/splitwise/blob/main/core/model.go"
    click User "https://github.com/lakhan-nad/splitwise/blob/main/user/user.go"
    click UserRepo "https://github.com/lakhan-nad/splitwise/blob/main/user/user_repo.go"
    click TransactionEnt "https://github.com/lakhan-nad/splitwise/blob/main/transaction/transaction.go"
    click TransHistory "https://github.com/lakhan-nad/splitwise/blob/main/transaction/transaction_history.go"
    click TransRepo "https://github.com/lakhan-nad/splitwise/blob/main/transaction/transaction_repo.go"
    click TransAccountEnt "https://github.com/lakhan-nad/splitwise/blob/main/transaction/account/transaction_account.go"
    click AccountRepo "https://github.com/lakhan-nad/splitwise/blob/main/transaction/account/transaction_account_repo.go"

    %% Styles
    classDef orchestration fill:#blue,stroke:#333,stroke-width:1px,color:#fff
    classDef logic fill:#9f6,stroke:#333,stroke-width:1px
    classDef domain fill:#ffeb3b,stroke:#333,stroke-width:1px
    classDef persistence fill:#ccc,stroke:#333,stroke-width:1px
```
