How zhvny/finance-tracker works
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: gateway/main.py API gateway · routers Domain routers · ledger/main.py Ledger service · market/main.py Market service
Components 23
User Clients
- Web dashboard
apps/web/src/app - Local CLI
apps/cli
Service Runtime
- API gateway
services/gateway/main.py - Platform service
services/platform/main.py - Ledger service
services/ledger/main.py - Portfolio service
services/portfolio/main.py - Market service
services/market/main.py - Insights service
services/insights/main.py - Engagement service
services/engagement/main.py - Domain routers
packages/api/backend/routers
Finance Ledger
- Finance activity
packages/api/backend/finance/ledger_engine.py - Finance services
packages/api/backend/finance - Persistence adapters
packages/core/infrastructure/persistence
Insights and OCR
- Receipt OCR
packages/core/application/receipt_reader - AI and analytics
packages/api/backend/ai
Markets
- Stock analysis
apps/cli/stock_analyzer - Stock ML inference
apps/cli/stock_ml/use_cases/predictor.py
Engagement
- Behavioral scoring
packages/web/src/behavioral/behavioralEngine.js - Reward unlock rules
packages/core/domain/services/reward_engine.py - Reward service
packages/core/application/reward_service.py - Rewards interface
packages/web/src/rewards
Other components
- Finance user
- Shared PostgreSQL
Connections 29
- 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