# zhvny/finance-tracker architecture

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

- Interactive diagram: https://gitdiagram.com/zhvny/finance-tracker
- Repository: https://github.com/zhvny/finance-tracker

## Overview

Alpha is a personal-finance and investment platform delivered through a public API gateway, six domain services, and web/CLI clients. A typical user submits financial activity or requests analysis; the platform routes the request to the owning domain service, which uses shared finance logic and PostgreSQL, then returns dashboards, reports, insights, or rewards. The README documents service responsibilities and gateway routing; sampled code additionally supports the ledger, OCR, behavioral scoring, and reward-engine layers. Some service internals are represented by their documented router directory because individual implementations were not sampled.

Main entry points: [`services/gateway/main.py`](https://github.com/zhvny/finance-tracker/blob/main/services/gateway/main.py) (API gateway), [`packages/api/backend/routers`](https://github.com/zhvny/finance-tracker/tree/main/packages/api/backend/routers) (Domain routers), [`services/ledger/main.py`](https://github.com/zhvny/finance-tracker/blob/main/services/ledger/main.py) (Ledger service), [`services/market/main.py`](https://github.com/zhvny/finance-tracker/blob/main/services/market/main.py) (Market service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User Clients"]
  node_web["Web dashboard"]
  node_cli["Local CLI"]
end

subgraph group_runtime["Service Runtime"]
  node_gateway["API gateway<br/>[main.py]"]
  node_platform["Platform service<br/>[main.py]"]
  node_ledger_svc["Ledger service<br/>[main.py]"]
  node_portfolio["Portfolio service<br/>[main.py]"]
  node_market["Market service<br/>[main.py]"]
  node_insights["Insights service<br/>[main.py]"]
  node_engagement["Engagement service<br/>[main.py]"]
  node_routers["Domain routers"]
end

subgraph group_ledger["Finance Ledger"]
  node_finance_data["Finance activity<br/>[ledger_engine.py]"]
  node_finance_services["Finance services"]
  node_persistence["Persistence adapters"]
end

subgraph group_insights["Insights and OCR"]
  node_receipt["Receipt OCR"]
  node_ai_insights["AI and analytics"]
end

subgraph group_markets["Markets"]
  node_stock_analysis["Stock analysis"]
  node_stock_ml["Stock ML inference<br/>[predictor.py]"]
end

subgraph group_engagement["Engagement"]
  node_behavioral["Behavioral scoring"]
  node_reward_engine["Reward unlock rules<br/>[reward_engine.py]"]
  node_reward_service["Reward service<br/>[reward_service.py]"]
  node_reward_ui["Rewards interface"]
end

node_user(("Finance user"))
node_postgres[("Shared PostgreSQL")]

node_user -->|"uses"| node_web
node_user -->|"uses"| node_cli
node_web -->|"sends API requests"| node_gateway
node_cli -.->|"sends API requests"| node_gateway
node_gateway -->|"proxies routes"| node_platform
node_gateway -->|"proxies routes"| node_ledger_svc
node_gateway -->|"proxies routes"| node_portfolio
node_gateway -->|"proxies routes"| node_market
node_gateway -->|"proxies routes"| node_insights
node_gateway -->|"proxies routes"| node_engagement
node_platform -->|"mounts routes"| node_routers
node_ledger_svc -->|"mounts routes"| node_routers
node_portfolio -->|"mounts routes"| node_routers
node_market -->|"mounts routes"| node_routers
node_insights -->|"mounts routes"| node_routers
node_engagement -->|"mounts routes"| node_routers
node_ledger_svc -->|"handles ledger requests"| node_finance_data
node_ledger_svc -->|"uses finance logic"| node_finance_services
node_portfolio -->|"serves portfolio data"| node_finance_services
node_finance_data -->|"reads and writes"| node_persistence
node_persistence -->|"persists data"| node_postgres
node_insights -->|"handles receipt OCR"| node_receipt
node_insights -->|"provides AI insights"| node_ai_insights
node_market -->|"serves market analysis"| node_stock_analysis
node_market -->|"serves ML stocks"| node_stock_ml
node_engagement -->|"provides behavior scoring"| node_behavioral
node_engagement -->|"handles rewards"| node_reward_service
node_reward_service -->|"checks unlocks"| node_reward_engine
node_reward_ui -.->|"requests reward data"| node_gateway

click node_web "https://github.com/zhvny/finance-tracker/tree/main/apps/web/src/app"
click node_cli "https://github.com/zhvny/finance-tracker/tree/main/apps/cli"
click node_gateway "https://github.com/zhvny/finance-tracker/blob/main/services/gateway/main.py"
click node_platform "https://github.com/zhvny/finance-tracker/blob/main/services/platform/main.py"
click node_ledger_svc "https://github.com/zhvny/finance-tracker/blob/main/services/ledger/main.py"
click node_portfolio "https://github.com/zhvny/finance-tracker/blob/main/services/portfolio/main.py"
click node_market "https://github.com/zhvny/finance-tracker/blob/main/services/market/main.py"
click node_insights "https://github.com/zhvny/finance-tracker/blob/main/services/insights/main.py"
click node_engagement "https://github.com/zhvny/finance-tracker/blob/main/services/engagement/main.py"
click node_routers "https://github.com/zhvny/finance-tracker/tree/main/packages/api/backend/routers"
click node_finance_data "https://github.com/zhvny/finance-tracker/blob/main/packages/api/backend/finance/ledger_engine.py"
click node_finance_services "https://github.com/zhvny/finance-tracker/tree/main/packages/api/backend/finance"
click node_persistence "https://github.com/zhvny/finance-tracker/tree/main/packages/core/infrastructure/persistence"
click node_receipt "https://github.com/zhvny/finance-tracker/tree/main/packages/core/application/receipt_reader"
click node_ai_insights "https://github.com/zhvny/finance-tracker/tree/main/packages/api/backend/ai"
click node_stock_analysis "https://github.com/zhvny/finance-tracker/tree/main/apps/cli/stock_analyzer"
click node_stock_ml "https://github.com/zhvny/finance-tracker/blob/main/apps/cli/stock_ml/use_cases/predictor.py"
click node_behavioral "https://github.com/zhvny/finance-tracker/blob/main/packages/web/src/behavioral/behavioralEngine.js"
click node_reward_engine "https://github.com/zhvny/finance-tracker/blob/main/packages/core/domain/services/reward_engine.py"
click node_reward_service "https://github.com/zhvny/finance-tracker/blob/main/packages/core/application/reward_service.py"
click node_reward_ui "https://github.com/zhvny/finance-tracker/tree/main/packages/web/src/rewards"

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_web,node_cli,node_user toneBlue
class node_gateway,node_platform,node_ledger_svc,node_portfolio,node_market,node_insights,node_engagement,node_routers,node_postgres toneAmber
class node_finance_data,node_finance_services,node_persistence toneMint
class node_receipt,node_ai_insights toneRose
class node_stock_analysis,node_stock_ml toneIndigo
class node_behavioral,node_reward_engine,node_reward_service,node_reward_ui toneTeal
```

## Components

### User Clients

- [Web dashboard](https://github.com/zhvny/finance-tracker/tree/main/apps/web/src/app): `apps/web/src/app`
- [Local CLI](https://github.com/zhvny/finance-tracker/tree/main/apps/cli): `apps/cli`

### Service Runtime

- [API gateway](https://github.com/zhvny/finance-tracker/blob/main/services/gateway/main.py): `services/gateway/main.py`
- [Platform service](https://github.com/zhvny/finance-tracker/blob/main/services/platform/main.py): `services/platform/main.py`
- [Ledger service](https://github.com/zhvny/finance-tracker/blob/main/services/ledger/main.py): `services/ledger/main.py`
- [Portfolio service](https://github.com/zhvny/finance-tracker/blob/main/services/portfolio/main.py): `services/portfolio/main.py`
- [Market service](https://github.com/zhvny/finance-tracker/blob/main/services/market/main.py): `services/market/main.py`
- [Insights service](https://github.com/zhvny/finance-tracker/blob/main/services/insights/main.py): `services/insights/main.py`
- [Engagement service](https://github.com/zhvny/finance-tracker/blob/main/services/engagement/main.py): `services/engagement/main.py`
- [Domain routers](https://github.com/zhvny/finance-tracker/tree/main/packages/api/backend/routers): `packages/api/backend/routers`

### Finance Ledger

- [Finance activity](https://github.com/zhvny/finance-tracker/blob/main/packages/api/backend/finance/ledger_engine.py): `packages/api/backend/finance/ledger_engine.py`
- [Finance services](https://github.com/zhvny/finance-tracker/tree/main/packages/api/backend/finance): `packages/api/backend/finance`
- [Persistence adapters](https://github.com/zhvny/finance-tracker/tree/main/packages/core/infrastructure/persistence): `packages/core/infrastructure/persistence`

### Insights and OCR

- [Receipt OCR](https://github.com/zhvny/finance-tracker/tree/main/packages/core/application/receipt_reader): `packages/core/application/receipt_reader`
- [AI and analytics](https://github.com/zhvny/finance-tracker/tree/main/packages/api/backend/ai): `packages/api/backend/ai`

### Markets

- [Stock analysis](https://github.com/zhvny/finance-tracker/tree/main/apps/cli/stock_analyzer): `apps/cli/stock_analyzer`
- [Stock ML inference](https://github.com/zhvny/finance-tracker/blob/main/apps/cli/stock_ml/use_cases/predictor.py): `apps/cli/stock_ml/use_cases/predictor.py`

### Engagement

- [Behavioral scoring](https://github.com/zhvny/finance-tracker/blob/main/packages/web/src/behavioral/behavioralEngine.js): `packages/web/src/behavioral/behavioralEngine.js`
- [Reward unlock rules](https://github.com/zhvny/finance-tracker/blob/main/packages/core/domain/services/reward_engine.py): `packages/core/domain/services/reward_engine.py`
- [Reward service](https://github.com/zhvny/finance-tracker/blob/main/packages/core/application/reward_service.py): `packages/core/application/reward_service.py`
- [Rewards interface](https://github.com/zhvny/finance-tracker/tree/main/packages/web/src/rewards): `packages/web/src/rewards`

### Other components

- **Finance user**
- **Shared PostgreSQL**

## Connections

- Finance user → Web dashboard: uses
- Finance user → Local CLI: uses
- Web dashboard → API gateway: sends API requests
- Local CLI → API gateway: sends API requests
- API gateway → Platform service: proxies routes
- API gateway → Ledger service: proxies routes
- API gateway → Portfolio service: proxies routes
- API gateway → Market service: proxies routes
- API gateway → Insights service: proxies routes
- API gateway → Engagement service: proxies routes
- Platform service → Domain routers: mounts routes
- Ledger service → Domain routers: mounts routes
- Portfolio service → Domain routers: mounts routes
- Market service → Domain routers: mounts routes
- Insights service → Domain routers: mounts routes
- Engagement service → Domain routers: mounts routes
- Ledger service → Finance activity: handles ledger requests
- Ledger service → Finance services: uses finance logic
- Portfolio service → Finance services: serves portfolio data
- Finance activity → Persistence adapters: reads and writes
- Persistence adapters → Shared PostgreSQL: persists data
- Insights service → Receipt OCR: handles receipt OCR
- Insights service → AI and analytics: provides AI insights
- Market service → Stock analysis: serves market analysis
- Market service → Stock ML inference: serves ML stocks
- Engagement service → Behavioral scoring: provides behavior scoring
- Engagement service → Reward service: handles rewards
- Reward service → Reward unlock rules: checks unlocks
- Rewards interface → API gateway: requests reward data