Architecture - NOVOSKY Docs

Repository layout

The repo is a Turborepo monorepo. The Python bot lives at the root; the website and shared design system are under apps/ and packages/.

apps/
  website/               SvelteKit public website (@novosky/website)
    src/
      lib/components/    UI components (Navbar, Hero, MacWindow, …)
      routes/            SvelteKit routes + API endpoints
    svelte.config.js
    vite.config.ts
    package.json

packages/
  design/                Shared design system (@novosky/design)
    src/lib/tokens.css   @theme tokens + reusable component classes
    src/lib/components/  Base Svelte components (Button, MacWindow, …)
    tokens.css           Re-export shim for CSS imports
  configs/               Shared ESLint + Prettier configs (@novosky/configs)
    eslint.js            Base ESLint flat config (TS + prettier)
    eslint-svelte.js     Svelte ESLint extension
    prettier.js          Shared Prettier config

turbo.json               Turborepo task pipeline
package.json             Workspace root (yarn workspaces)
.yarnrc.yml              Yarn Berry — nodeLinker: node-modules

trading/
  bot.py                Main trading loop — all execution logic
  logger.py             Structured logging helpers
  supabase.py           Supabase write helpers
  telegram_commands.py  Telegram command handler

ml/
  feature_engineering.py   62 features + ATR-aware labeling
  ensemble_trainer.py      RF + XGB + LGB signal model training
  ensemble_predictor.py    Signal model inference (majority vote)
  position_trainer.py      Position model training (EXIT/HOLD/ADD)
  position_predictor.py    Position model inference
  sltp_trainer.py          Dynamic SL/TP LightGBM training
  sltp_predictor.py        Dynamic SL/TP inference
  risk_trainer.py          Risk multiplier LightGBM training
  risk_predictor.py        Risk inference: equity-state → [0.10, 1.25]
  model_trainer.py         Shared training utilities + ONNX export
  model_predictor.py       Shared inference base class
  data_preparation.py      Dataset loading + IS/OOS split
  calibration_check.py     Model calibration diagnostics
  news_features.py         News event feature computation
  shap_analysis.py         SHAP feature importance analysis
  hf_hub.py                Hugging Face Hub push / pull / tag
  tune/
    hyperparams.py         Optuna signal model tuning
    position.py            Optuna position model tuning

backtest/
  run.py                 Config-faithful bar-by-bar backtester

scripts/
  onboarding.py              First-time setup wizard (8-step)
  weekly_optimize.py         Autonomous 13-phase weekly pipeline
  retrain.py                 Standalone retrain dispatcher (all 4 models)
  sweep.py                   Unified config parameter sweep (signal + pos)
  optimize_loop.py           Iterative SHAP → tune → retrain → OOS loop
  config_sync.py             Config authority helpers (imported by other scripts)
  notify.py                  Send manual Telegram notification
  export_scalers.py          Export PKL scalers → JSON (required for Go binary)
  export_onnx_regression.py  Export risk/SLTP LGB .txt → .onnx (required for Go binary)
  pack_embedded.sh           Copy models + configs into internal/embedded/ for go:embed

models/
  model_compat.json      Feature hash + model paths — compatibility gate
  risk_metadata.json     Risk model metadata

config/
  brokers.json           Broker registry (symbol, spread, leverage, pip_value)

config.json              Runtime config (active broker, risk, SL/TP, filters)
ml_config.json           ML config (62 features, model paths, labeling params)
trading.py               Entry point — calls trading/bot.py
scripts/retrain.py       Training dispatcher — always trains all 4 models
backtest.py              Entry point — calls backtest/run.py

# Go binary (cmd/ and internal/)
cmd/
  novosky/main.go        Go binary entry point — signal handling, retry loop
  licgen/main.go         License generator (owner only — never shipped to customers)

internal/
  bot/bot.go             Main Go trading loop
  ml/                    ONNX predictors (ensemble, position, risk, sltp) + scalers
  embedded/              go:embed declarations — all model assets baked in at build time
    embed.go             //go:embed directives
    license.json         Placeholder ({}); overwritten by licgen before production build
    models/              Populated by pack_embedded.sh (gitignored)
  config/                config.json, ml_config.json, strategy_params.json loaders
  api/                   MT5 REST API client
  telegram/              Telegram command bot
  assistant/             AI assistant (OpenAI-compatible, tool-calling)
  license/               HMAC-SHA256 license validation
  supabase/              Supabase REST client
  logger/                Trade, signal, and daily CSV logger

Monorepo commands

yarn dev               # dev server for all apps
yarn dev:website       # website only
yarn build:website     # production build (website)
yarn check:website     # svelte-check (website)
yarn lint              # ESLint all packages
yarn format            # Prettier all packages

The three-file rule

Any ML feature change touches exactly three files:

ml/feature_engineering.py — add the feature computation
ml_config.json → features array — add the name in the correct position
Retrain all 4 models — Signal, Position, SLTP, Risk (in that order)

Changing any one without the others breaks inference. The models/model_compat.json file stores a hash of the feature list. On startup, EnsemblePredictor verifies the hash against the current ml_config.json. A mismatch raises ModelCompatibilityError immediately.

Strict training order

Models must always be trained in this order:

Signal → Position → SLTP → Risk

Model	Depends on
Signal	Nothing (first)
Position	Signal model paths (saved to disk)
SLTP	Signal + position models (saved to disk)
Risk	Completed backtest using SLTP models

Training out of order produces either import errors or silent data contamination in the Risk model’s training labels.

Backtester / live parity

backtest/run.py must always mirror trading/bot.py. Every change to execution logic in the bot must be reflected in the backtester, and vice versa. Key parity invariants:

Same feature engineering (ml/feature_engineering.py)
Same model inference chain (calibrated pkl → ONNX → raw pkl)
Same position sizing formula
Same equity-aware SL cap
Same circuit breakers and gates
Same position model evaluation timing

If these diverge, backtest scores become unreliable as live performance predictors.

Lane discipline

The codebase has two clearly separated lanes:

Lane	Who	What
Client/user lane	Trader on their machine	Pull approved models, run `trading.py`
Developer lane	Developer on their machine	Retrain, optimize, validate OOS, publish to HF Hub

Clients should never retrain. The live trading host should stay simple — it does not need a GPU or the full ML dependency stack (just pip install -r requirements.txt is fine).

Go binary — embedded asset system

The Go binary uses Go’s //go:embed directive to bake all ML models, scalers, and configs into the compiled binary at build time. The scripts/pack_embedded.sh script copies the necessary files into internal/embedded/ before each build.

internal/embedded/
  embed.go              //go:embed declarations
  license.json          Placeholder in git; replaced before production build
  models/               Populated by pack_embedded.sh (gitignored)
    ensemble_rf.onnx    ← copied from models/
    ensemble_xgb.onnx
    ensemble_lgb.onnx
    position_rf.onnx
    ...
    ensemble_scaler.json
    ...
  ml_config.json        Copied from repo root
  strategy_params.json  Copied from repo root

Because everything is embedded, customers do not need a models/ directory, Hugging Face Hub access, or any Python tooling. See Go binary for the full build and license reference.

Config files

Two config files govern all behavior:

File	What it controls	Tracked in git
`config.json`	Runtime params: symbol, risk, SL/TP, profile, filters, broker	Yes
`ml_config.json`	Features, model paths, labeling, training params	Yes

Both are committed to git. When weekly_optimize.py updates config.json, the change appears in git history. This makes every optimization run fully auditable.

Documentation Index

​Repository layout

​Monorepo commands

​The three-file rule

​Strict training order

​Backtester / live parity

​Lane discipline

​Go binary — embedded asset system

​Config files