# monoxti/sololevel architecture

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

- Interactive diagram: https://gitdiagram.com/monoxti/sololevel
- Repository: https://github.com/monoxti/sololevel

## Overview

SoloLevel is a self-hosted finance and productivity platform with a web dashboard and Telegram bot. Users log transactions, manage savings goals and daily habits, and maintain notes and time-limited todos; the dashboard presents financial summaries, insights, and trading views. The dashboard calls the Python API, while Telegram messages are parsed and dispatched by the Node backend. Python also runs scheduled insight and forex work, and Node manages notes/todos and Telegram notifications. Several deeper trading components are indexed but unsampled, so their internal connections are omitted.

Main entry points: [`python-backend/app/services/forex/v2/engine.py`](https://github.com/monoxti/sololevel/blob/main/python-backend/app/services/forex/v2/engine.py) (Forex v2 engine), [`node-backend/src/index.ts`](https://github.com/monoxti/sololevel/blob/main/node-backend/src/index.ts) (Bot runtime), [`python-backend/app/routers`](https://github.com/monoxti/sololevel/tree/main/python-backend/app/routers) (API routes), [`python-backend/app/main.py`](https://github.com/monoxti/sololevel/blob/main/python-backend/app/main.py) (API startup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dashboard["Web dashboard"]
  node_dashboard_app["Dashboard pages<br/>[page.tsx]"]
  node_dashboard_api["API client<br/>[api.ts]"]
end

subgraph group_python["Finance API"]
  node_fastapi["API routes"]
  node_python_main["API startup<br/>[main.py]"]
  node_finance_routes["Finance endpoints<br/>[finance.py]"]
  node_python_db[("SQLAlchemy database<br/>[database.py]")]
  node_domain_models["Finance models"]
  node_daily_goals["Daily goals<br/>[daily_goals.py]"]
  node_ml_engine["ML insights<br/>[engine.py]"]
  node_ml_scheduler["ML scheduler<br/>[scheduler.py]"]
end

subgraph group_node["Telegram backend"]
  node_bot_runtime["Bot runtime<br/>[index.ts]"]
  node_intent_parser["Intent parser<br/>[brain.ts]"]
  node_bot_handlers["Command handlers<br/>[handlers.ts]"]
  node_node_finance["Bot finance<br/>[finance.ts]"]
  node_notes_todos["Notes and todos<br/>[notesAndTodos.ts]"]
  node_todo_scheduler["Todo reminders<br/>[todoScheduler.ts]"]
  node_notify["Telegram notifications<br/>[notify.ts]"]
  node_prisma[("Prisma client<br/>[prisma.ts]")]
end

subgraph group_trading["Trading systems"]
  node_forex_api["Forex endpoints<br/>[forex.py]"]
  node_forex_scheduler["Forex scheduler<br/>[scheduler.py]"]
  node_forex_engine["Forex v2 engine<br/>[engine.py]"]
  node_forex_data["Market data<br/>[data.py]"]
  node_forex_strategies["Trading strategies<br/>[strategies.py]"]
  node_forex_risk["Trade risk<br/>[risk.py]"]
  node_forex_indicators["Indicators<br/>[indicators.py]"]
  node_forex_performance["Strategy performance<br/>[performance.py]"]
end

node_web_user(("Dashboard user"))
node_telegram_user(("Telegram user"))
node_telegram["Telegram"]
node_market_data["Market data provider"]
node_postgres[("PostgreSQL")]

node_web_user -->|"uses"| node_dashboard_app
node_dashboard_app -->|"requests data"| node_dashboard_api
node_dashboard_api -->|"calls API"| node_fastapi
node_telegram_user -->|"sends commands"| node_telegram
node_telegram -->|"delivers messages"| node_bot_runtime
node_bot_runtime -->|"parses text"| node_intent_parser
node_bot_runtime -->|"dispatches intents"| node_bot_handlers
node_bot_handlers -->|"calls finance"| node_node_finance
node_bot_handlers -->|"calls notes/todos"| node_notes_todos
node_todo_scheduler -->|"reads todos"| node_notes_todos
node_todo_scheduler -->|"sends reminders"| node_notify
node_notes_todos -->|"queries data"| node_prisma
node_bot_runtime -->|"starts scheduler"| node_todo_scheduler
node_bot_runtime -->|"registers bot"| node_notify
node_notify -->|"sends messages"| node_telegram
node_python_main -->|"registers routes"| node_fastapi
node_fastapi -->|"includes router"| node_finance_routes
node_finance_routes -->|"queries database"| node_python_db
node_python_db -->|"persists data"| node_postgres
node_python_main -->|"starts jobs"| node_ml_scheduler
node_ml_scheduler -.->|"schedules analysis"| node_ml_engine
node_ml_engine -->|"reads and saves"| node_domain_models
node_python_main -->|"sets up trader"| node_forex_scheduler
node_fastapi -->|"includes router"| node_forex_api
node_forex_api -->|"runs analysis"| node_forex_engine
node_forex_engine -->|"fetches data"| node_forex_data
node_forex_engine -->|"runs strategies"| node_forex_strategies
node_forex_engine -->|"builds trade risk"| node_forex_risk
node_forex_engine -->|"calculates indicators"| node_forex_indicators
node_forex_engine -->|"gets weights"| node_forex_performance
node_forex_data -.->|"fetches prices"| node_market_data

click node_dashboard_app "https://github.com/monoxti/sololevel/blob/main/dashboard/app/dashboard/overview/page.tsx"
click node_dashboard_api "https://github.com/monoxti/sololevel/blob/main/dashboard/lib/api.ts"
click node_fastapi "https://github.com/monoxti/sololevel/tree/main/python-backend/app/routers"
click node_python_main "https://github.com/monoxti/sololevel/blob/main/python-backend/app/main.py"
click node_finance_routes "https://github.com/monoxti/sololevel/blob/main/python-backend/app/routers/finance.py"
click node_python_db "https://github.com/monoxti/sololevel/blob/main/python-backend/app/db/database.py"
click node_domain_models "https://github.com/monoxti/sololevel/tree/main/python-backend/app/models"
click node_daily_goals "https://github.com/monoxti/sololevel/blob/main/python-backend/app/routers/daily_goals.py"
click node_ml_engine "https://github.com/monoxti/sololevel/blob/main/python-backend/app/services/ml/engine.py"
click node_ml_scheduler "https://github.com/monoxti/sololevel/blob/main/python-backend/app/services/ml/scheduler.py"
click node_bot_runtime "https://github.com/monoxti/sololevel/blob/main/node-backend/src/index.ts"
click node_intent_parser "https://github.com/monoxti/sololevel/blob/main/node-backend/src/ai/brain.ts"
click node_bot_handlers "https://github.com/monoxti/sololevel/blob/main/node-backend/src/bot/handlers.ts"
click node_node_finance "https://github.com/monoxti/sololevel/blob/main/node-backend/src/services/finance.ts"
click node_notes_todos "https://github.com/monoxti/sololevel/blob/main/node-backend/src/services/notesAndTodos.ts"
click node_todo_scheduler "https://github.com/monoxti/sololevel/blob/main/node-backend/src/services/todoScheduler.ts"
click node_notify "https://github.com/monoxti/sololevel/blob/main/node-backend/src/webhooks/notify.ts"
click node_prisma "https://github.com/monoxti/sololevel/blob/main/node-backend/src/db/prisma.ts"
click node_forex_api "https://github.com/monoxti/sololevel/blob/main/python-backend/app/routers/forex.py"
click node_forex_scheduler "https://github.com/monoxti/sololevel/blob/main/python-backend/app/services/forex/scheduler.py"
click node_forex_engine "https://github.com/monoxti/sololevel/blob/main/python-backend/app/services/forex/v2/engine.py"
click node_forex_data "https://github.com/monoxti/sololevel/blob/main/python-backend/app/services/forex/v2/data.py"
click node_forex_strategies "https://github.com/monoxti/sololevel/blob/main/python-backend/app/services/forex/v2/strategies.py"
click node_forex_risk "https://github.com/monoxti/sololevel/blob/main/python-backend/app/services/forex/v2/risk.py"
click node_forex_indicators "https://github.com/monoxti/sololevel/blob/main/python-backend/app/services/forex/v2/indicators.py"
click node_forex_performance "https://github.com/monoxti/sololevel/blob/main/python-backend/app/services/forex/v2/performance.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_dashboard_app,node_dashboard_api,node_web_user,node_telegram_user toneBlue
class node_fastapi,node_python_main,node_finance_routes,node_python_db,node_domain_models,node_daily_goals,node_ml_engine,node_ml_scheduler,node_postgres toneAmber
class node_bot_runtime,node_intent_parser,node_bot_handlers,node_node_finance,node_notes_todos,node_todo_scheduler,node_notify,node_prisma toneMint
class node_forex_api,node_forex_scheduler,node_forex_engine,node_forex_data,node_forex_strategies,node_forex_risk,node_forex_indicators,node_forex_performance toneRose
class node_telegram,node_market_data toneIndigo
```

## Components

### Web dashboard

- [Dashboard pages](https://github.com/monoxti/sololevel/blob/main/dashboard/app/dashboard/overview/page.tsx): `dashboard/app/dashboard/overview/page.tsx`
- [API client](https://github.com/monoxti/sololevel/blob/main/dashboard/lib/api.ts): `dashboard/lib/api.ts`

### Finance API

- [API routes](https://github.com/monoxti/sololevel/tree/main/python-backend/app/routers): `python-backend/app/routers`
- [API startup](https://github.com/monoxti/sololevel/blob/main/python-backend/app/main.py): `python-backend/app/main.py`
- [Finance endpoints](https://github.com/monoxti/sololevel/blob/main/python-backend/app/routers/finance.py): `python-backend/app/routers/finance.py`
- [SQLAlchemy database](https://github.com/monoxti/sololevel/blob/main/python-backend/app/db/database.py): `python-backend/app/db/database.py`
- [Finance models](https://github.com/monoxti/sololevel/tree/main/python-backend/app/models): `python-backend/app/models`
- [Daily goals](https://github.com/monoxti/sololevel/blob/main/python-backend/app/routers/daily_goals.py): `python-backend/app/routers/daily_goals.py`
- [ML insights](https://github.com/monoxti/sololevel/blob/main/python-backend/app/services/ml/engine.py): `python-backend/app/services/ml/engine.py`
- [ML scheduler](https://github.com/monoxti/sololevel/blob/main/python-backend/app/services/ml/scheduler.py): `python-backend/app/services/ml/scheduler.py`

### Telegram backend

- [Bot runtime](https://github.com/monoxti/sololevel/blob/main/node-backend/src/index.ts): `node-backend/src/index.ts`
- [Intent parser](https://github.com/monoxti/sololevel/blob/main/node-backend/src/ai/brain.ts): `node-backend/src/ai/brain.ts`
- [Command handlers](https://github.com/monoxti/sololevel/blob/main/node-backend/src/bot/handlers.ts): `node-backend/src/bot/handlers.ts`
- [Bot finance](https://github.com/monoxti/sololevel/blob/main/node-backend/src/services/finance.ts): `node-backend/src/services/finance.ts`
- [Notes and todos](https://github.com/monoxti/sololevel/blob/main/node-backend/src/services/notesAndTodos.ts): `node-backend/src/services/notesAndTodos.ts`
- [Todo reminders](https://github.com/monoxti/sololevel/blob/main/node-backend/src/services/todoScheduler.ts): `node-backend/src/services/todoScheduler.ts`
- [Telegram notifications](https://github.com/monoxti/sololevel/blob/main/node-backend/src/webhooks/notify.ts): `node-backend/src/webhooks/notify.ts`
- [Prisma client](https://github.com/monoxti/sololevel/blob/main/node-backend/src/db/prisma.ts): `node-backend/src/db/prisma.ts`

### Trading systems

- [Forex endpoints](https://github.com/monoxti/sololevel/blob/main/python-backend/app/routers/forex.py): `python-backend/app/routers/forex.py`
- [Forex scheduler](https://github.com/monoxti/sololevel/blob/main/python-backend/app/services/forex/scheduler.py): `python-backend/app/services/forex/scheduler.py`
- [Forex v2 engine](https://github.com/monoxti/sololevel/blob/main/python-backend/app/services/forex/v2/engine.py): `python-backend/app/services/forex/v2/engine.py`
- [Market data](https://github.com/monoxti/sololevel/blob/main/python-backend/app/services/forex/v2/data.py): `python-backend/app/services/forex/v2/data.py`
- [Trading strategies](https://github.com/monoxti/sololevel/blob/main/python-backend/app/services/forex/v2/strategies.py): `python-backend/app/services/forex/v2/strategies.py`
- [Trade risk](https://github.com/monoxti/sololevel/blob/main/python-backend/app/services/forex/v2/risk.py): `python-backend/app/services/forex/v2/risk.py`
- [Indicators](https://github.com/monoxti/sololevel/blob/main/python-backend/app/services/forex/v2/indicators.py): `python-backend/app/services/forex/v2/indicators.py`
- [Strategy performance](https://github.com/monoxti/sololevel/blob/main/python-backend/app/services/forex/v2/performance.py): `python-backend/app/services/forex/v2/performance.py`

### Other components

- **Dashboard user**
- **Telegram user**
- **Telegram**
- **Market data provider**
- **PostgreSQL**

## Connections

- Dashboard user → Dashboard pages: uses
- Dashboard pages → API client: requests data
- API client → API routes: calls API
- Telegram user → Telegram: sends commands
- Telegram → Bot runtime: delivers messages
- Bot runtime → Intent parser: parses text (evidence: `node-backend/src/index.ts`)
- Bot runtime → Command handlers: dispatches intents (evidence: `node-backend/src/index.ts`)
- Command handlers → Bot finance: calls finance (evidence: `node-backend/src/bot/handlers.ts`)
- Command handlers → Notes and todos: calls notes/todos (evidence: `node-backend/src/bot/handlers.ts`)
- Todo reminders → Notes and todos: reads todos (evidence: `node-backend/src/services/todoScheduler.ts`)
- Todo reminders → Telegram notifications: sends reminders (evidence: `node-backend/src/services/todoScheduler.ts`)
- Notes and todos → Prisma client: queries data (evidence: `node-backend/src/services/notesAndTodos.ts`)
- Bot runtime → Todo reminders: starts scheduler (evidence: `node-backend/src/index.ts`)
- Bot runtime → Telegram notifications: registers bot (evidence: `node-backend/src/index.ts`)
- Telegram notifications → Telegram: sends messages (evidence: `node-backend/src/webhooks/notify.ts`)
- API startup → API routes: registers routes (evidence: `python-backend/app/main.py`)
- API routes → Finance endpoints: includes router (evidence: `python-backend/app/main.py`)
- Finance endpoints → SQLAlchemy database: queries database (evidence: `python-backend/app/routers/finance.py`)
- SQLAlchemy database → PostgreSQL: persists data
- API startup → ML scheduler: starts jobs (evidence: `python-backend/app/main.py`)
- ML scheduler → ML insights: schedules analysis
- ML insights → Finance models: reads and saves (evidence: `python-backend/app/services/ml/engine.py`)
- API startup → Forex scheduler: sets up trader (evidence: `python-backend/app/main.py`)
- API routes → Forex endpoints: includes router (evidence: `python-backend/app/main.py`)
- Forex endpoints → Forex v2 engine: runs analysis (evidence: `python-backend/app/routers/forex.py`)
- Forex v2 engine → Market data: fetches data (evidence: `python-backend/app/services/forex/v2/engine.py`)
- Forex v2 engine → Trading strategies: runs strategies (evidence: `python-backend/app/services/forex/v2/engine.py`)
- Forex v2 engine → Trade risk: builds trade risk (evidence: `python-backend/app/services/forex/v2/engine.py`)
- Forex v2 engine → Indicators: calculates indicators (evidence: `python-backend/app/services/forex/v2/engine.py`)
- Forex v2 engine → Strategy performance: gets weights (evidence: `python-backend/app/services/forex/v2/engine.py`)
- Market data → Market data provider: fetches prices