# keval2609/expense-splitter architecture

> Architecture diagram of the GitHub repository keval2609/expense-splitter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/keval2609/expense-splitter
- Repository: https://github.com/keval2609/expense-splitter

## Overview

Expense Splitter is a REST API for shared group expenses. Its principal flow is user authentication, group setup, expense entry with split rules, balance calculation, debt-simplification suggestions, and settlement recording. The graph includes the API entry point, authentication and domain handlers, split and balance logic, and persistence. Some endpoint and schema details are represented from the README and source index; unsampled implementation links are omitted where the evidence does not establish them.

Main entry points: [`app/api/deps.py`](https://github.com/keval2609/expense-splitter/blob/main/app/api/deps.py) (Auth Dependencies), [`app/main.py`](https://github.com/keval2609/expense-splitter/blob/main/app/main.py) (FastAPI App), [`app/api/endpoints/expenses.py`](https://github.com/keval2609/expense-splitter/blob/main/app/api/endpoints/expenses.py) (Expense Routes), [`app/models`](https://github.com/keval2609/expense-splitter/tree/main/app/models) (Domain Models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API Layer"]
  node_application["FastAPI App<br/>[main.py]"]
  node_user_routes["User Routes<br/>[users.py]"]
  node_group_routes["Group Routes<br/>[groups.py]"]
  node_expense_routes["Expense Routes<br/>[expenses.py]"]
  node_settlement_routes["Settlement Routes<br/>[settlements.py]"]
  node_balance_routes["Balance Routes<br/>[balances.py]"]
  node_simplify_routes["Simplify Routes<br/>[simplify.py]"]
  node_schemas["Request Schemas"]
end

subgraph group_domain["Expense Domain"]
end

subgraph group_logic["Calculation Logic"]
  node_split_engine["Split Engine<br/>[core.py]"]
  node_balance_service["Balance Ledger<br/>[balance.py]"]
  node_exact_solver["Exact Simplifier<br/>[exact.py]"]
  node_greedy_solver["Greedy Simplifier<br/>[greedy.py]"]
end

subgraph group_identity["Identity"]
  node_auth_deps["Auth Dependencies<br/>[deps.py]"]
  node_auth_service["Token Service<br/>[auth.py]"]
end

subgraph group_persistence["Persistence"]
  node_orm_models["Domain Models"]
  node_db_session["DB Sessions<br/>[db.py]"]
end

node_client(("API Client"))
node_postgres[("PostgreSQL")]

node_client -->|"sends requests"| node_application
node_application -->|"registers router"| node_user_routes
node_application -->|"registers router"| node_group_routes
node_application -->|"registers router"| node_expense_routes
node_application -->|"registers router"| node_settlement_routes
node_application -->|"registers router"| node_balance_routes
node_application -->|"registers router"| node_simplify_routes
node_user_routes -->|"uses tokens"| node_auth_service
node_auth_deps -->|"decodes token"| node_auth_service
node_user_routes -->|"uses dependency"| node_auth_deps
node_group_routes -->|"uses dependency"| node_auth_deps
node_expense_routes -->|"uses dependency"| node_auth_deps
node_settlement_routes -->|"uses dependency"| node_auth_deps
node_balance_routes -->|"uses dependency"| node_auth_deps
node_simplify_routes -->|"uses dependency"| node_auth_deps
node_expense_routes -->|"calculates splits"| node_split_engine
node_expense_routes -->|"validates input"| node_schemas
node_group_routes -->|"uses schemas"| node_schemas
node_user_routes -->|"uses schemas"| node_schemas
node_settlement_routes -->|"uses schemas"| node_schemas
node_balance_routes -->|"reads balances"| node_balance_service
node_simplify_routes -->|"computes balances"| node_balance_service
node_simplify_routes -->|"requests simplification"| node_exact_solver
node_simplify_routes -->|"requests simplification"| node_greedy_solver
node_exact_solver -->|"solves subsets"| node_greedy_solver
node_auth_deps -->|"queries users"| node_orm_models
node_expense_routes -->|"reads and writes"| node_orm_models
node_group_routes -->|"reads and writes"| node_orm_models
node_settlement_routes -->|"reads and writes"| node_orm_models
node_balance_service -->|"aggregates ledger"| node_orm_models
node_user_routes -->|"reads and writes"| node_orm_models
node_auth_deps -->|"gets session"| node_db_session
node_application -->|"checks readiness"| node_db_session
node_db_session -->|"opens sessions"| node_postgres
node_expense_routes -->|"commits records"| node_postgres
node_settlement_routes -->|"records payments"| node_postgres

click node_application "https://github.com/keval2609/expense-splitter/blob/main/app/main.py"
click node_user_routes "https://github.com/keval2609/expense-splitter/blob/main/app/api/endpoints/users.py"
click node_group_routes "https://github.com/keval2609/expense-splitter/blob/main/app/api/endpoints/groups.py"
click node_expense_routes "https://github.com/keval2609/expense-splitter/blob/main/app/api/endpoints/expenses.py"
click node_settlement_routes "https://github.com/keval2609/expense-splitter/blob/main/app/api/endpoints/settlements.py"
click node_balance_routes "https://github.com/keval2609/expense-splitter/blob/main/app/api/endpoints/balances.py"
click node_simplify_routes "https://github.com/keval2609/expense-splitter/blob/main/app/api/endpoints/simplify.py"
click node_schemas "https://github.com/keval2609/expense-splitter/tree/main/app/schemas"
click node_auth_deps "https://github.com/keval2609/expense-splitter/blob/main/app/api/deps.py"
click node_auth_service "https://github.com/keval2609/expense-splitter/blob/main/app/services/auth.py"
click node_split_engine "https://github.com/keval2609/expense-splitter/blob/main/app/split_engine/core.py"
click node_balance_service "https://github.com/keval2609/expense-splitter/blob/main/app/services/balance.py"
click node_exact_solver "https://github.com/keval2609/expense-splitter/blob/main/app/simplify/exact.py"
click node_greedy_solver "https://github.com/keval2609/expense-splitter/blob/main/app/simplify/greedy.py"
click node_orm_models "https://github.com/keval2609/expense-splitter/tree/main/app/models"
click node_db_session "https://github.com/keval2609/expense-splitter/blob/main/app/db.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_application,node_user_routes,node_group_routes,node_expense_routes,node_settlement_routes,node_balance_routes,node_simplify_routes,node_schemas,node_client toneBlue
class node_split_engine,node_balance_service,node_exact_solver,node_greedy_solver toneMint
class node_auth_deps,node_auth_service toneRose
class node_orm_models,node_db_session toneIndigo
class node_postgres toneAmber
```

## Components

### API Layer

- [FastAPI App](https://github.com/keval2609/expense-splitter/blob/main/app/main.py): `app/main.py`
- [User Routes](https://github.com/keval2609/expense-splitter/blob/main/app/api/endpoints/users.py): `app/api/endpoints/users.py`
- [Group Routes](https://github.com/keval2609/expense-splitter/blob/main/app/api/endpoints/groups.py): `app/api/endpoints/groups.py`
- [Expense Routes](https://github.com/keval2609/expense-splitter/blob/main/app/api/endpoints/expenses.py): `app/api/endpoints/expenses.py`
- [Settlement Routes](https://github.com/keval2609/expense-splitter/blob/main/app/api/endpoints/settlements.py): `app/api/endpoints/settlements.py`
- [Balance Routes](https://github.com/keval2609/expense-splitter/blob/main/app/api/endpoints/balances.py): `app/api/endpoints/balances.py`
- [Simplify Routes](https://github.com/keval2609/expense-splitter/blob/main/app/api/endpoints/simplify.py): `app/api/endpoints/simplify.py`
- [Request Schemas](https://github.com/keval2609/expense-splitter/tree/main/app/schemas): `app/schemas`

### Calculation Logic

- [Split Engine](https://github.com/keval2609/expense-splitter/blob/main/app/split_engine/core.py): `app/split_engine/core.py`
- [Balance Ledger](https://github.com/keval2609/expense-splitter/blob/main/app/services/balance.py): `app/services/balance.py`
- [Exact Simplifier](https://github.com/keval2609/expense-splitter/blob/main/app/simplify/exact.py): `app/simplify/exact.py`
- [Greedy Simplifier](https://github.com/keval2609/expense-splitter/blob/main/app/simplify/greedy.py): `app/simplify/greedy.py`

### Identity

- [Auth Dependencies](https://github.com/keval2609/expense-splitter/blob/main/app/api/deps.py): `app/api/deps.py`
- [Token Service](https://github.com/keval2609/expense-splitter/blob/main/app/services/auth.py): `app/services/auth.py`

### Persistence

- [Domain Models](https://github.com/keval2609/expense-splitter/tree/main/app/models): `app/models`
- [DB Sessions](https://github.com/keval2609/expense-splitter/blob/main/app/db.py): `app/db.py`

### Other components

- **API Client**
- **PostgreSQL**

## Connections

- API Client → FastAPI App: sends requests (evidence: `README.md`)
- FastAPI App → User Routes: registers router (evidence: `app/main.py`)
- FastAPI App → Group Routes: registers router (evidence: `app/main.py`)
- FastAPI App → Expense Routes: registers router (evidence: `app/main.py`)
- FastAPI App → Settlement Routes: registers router (evidence: `app/main.py`)
- FastAPI App → Balance Routes: registers router (evidence: `app/main.py`)
- FastAPI App → Simplify Routes: registers router (evidence: `app/main.py`)
- User Routes → Token Service: uses tokens (evidence: `app/api/endpoints/users.py`)
- Auth Dependencies → Token Service: decodes token (evidence: `app/api/deps.py`)
- User Routes → Auth Dependencies: uses dependency (evidence: `app/api/endpoints/users.py`)
- Group Routes → Auth Dependencies: uses dependency (evidence: `app/api/endpoints/groups.py`)
- Expense Routes → Auth Dependencies: uses dependency (evidence: `app/api/endpoints/expenses.py`)
- Settlement Routes → Auth Dependencies: uses dependency (evidence: `app/api/endpoints/settlements.py`)
- Balance Routes → Auth Dependencies: uses dependency (evidence: `app/api/endpoints/balances.py`)
- Simplify Routes → Auth Dependencies: uses dependency (evidence: `app/api/endpoints/simplify.py`)
- Expense Routes → Split Engine: calculates splits (evidence: `app/api/endpoints/expenses.py`)
- Expense Routes → Request Schemas: validates input (evidence: `app/api/endpoints/expenses.py`)
- Group Routes → Request Schemas: uses schemas (evidence: `app/api/endpoints/groups.py`)
- User Routes → Request Schemas: uses schemas (evidence: `app/api/endpoints/users.py`)
- Settlement Routes → Request Schemas: uses schemas (evidence: `app/api/endpoints/settlements.py`)
- Balance Routes → Balance Ledger: reads balances (evidence: `app/api/endpoints/balances.py`)
- Simplify Routes → Balance Ledger: computes balances (evidence: `app/api/endpoints/simplify.py`)
- Simplify Routes → Exact Simplifier: requests simplification (evidence: `app/api/endpoints/simplify.py`)
- Simplify Routes → Greedy Simplifier: requests simplification (evidence: `app/api/endpoints/simplify.py`)
- Exact Simplifier → Greedy Simplifier: solves subsets (evidence: `app/simplify/exact.py`)
- Auth Dependencies → Domain Models: queries users (evidence: `app/api/deps.py`)
- Expense Routes → Domain Models: reads and writes (evidence: `app/api/endpoints/expenses.py`)
- Group Routes → Domain Models: reads and writes (evidence: `app/api/endpoints/groups.py`)
- Settlement Routes → Domain Models: reads and writes (evidence: `app/api/endpoints/settlements.py`)
- Balance Ledger → Domain Models: aggregates ledger (evidence: `app/services/balance.py`)
- User Routes → Domain Models: reads and writes (evidence: `app/api/endpoints/users.py`)
- Auth Dependencies → DB Sessions: gets session (evidence: `app/api/deps.py`)
- FastAPI App → DB Sessions: checks readiness (evidence: `app/main.py`)
- DB Sessions → PostgreSQL: opens sessions (evidence: `app/db.py`)
- Expense Routes → PostgreSQL: commits records (evidence: `README.md`)
- Settlement Routes → PostgreSQL: records payments (evidence: `README.md`)
