AERA (quant-lab)

Advanced Engineering for Research and Analytics — a local platform for quantitative trading research, visualization, and backtesting.

• Frontend: React + Vite (Lumina UI)
• Backend: Node/Express (API + Python indicator execution)
• Chart: TradingView Lightweight Charts
• Desktop (optional): Electron shell

Quickstart (dev)

Note: frontend config lives in root-files/ now; use npm --prefix root-files ... (or cd root-files) for frontend scripts.

Install dependencies:

npm install --prefix root-files
npm install --prefix server

Run frontend + backend:

npm --prefix root-files run app

Main checks and tests:

npm --prefix root-files run check        # minimal lint + typecheck
npm --prefix root-files run test         # backend tests (includes smoke)
npm --prefix root-files run test:ui:smoke # Playwright UI smoke (expects backend serving dist on :4800)
npm --prefix root-files run test:chart:perf # chart perf smoke (requires debug mode + backend on :4800)

Debugging (CLI)

Run the Debug Doctor:

npm --prefix root-files run debug:doctor

Generate an agent report:

npm --prefix root-files run debug:cli report --json --out agent-report.json

Execute a debug command:

npm --prefix root-files run debug:cli "list indicators"

Replay anchor (headless):

npm --prefix root-files run debug:cli replay --asset=CL1! --tf=M15 --back=1d

Override the backend URL with THELAB_DEBUG_URL (for the CLI).

Backend URL

• Default: same-origin /api requests (works with npm --prefix root-files run app and the Electron shell).
• Non-HTTP origins (e.g. opening dist/index.html via file://): falls back to http://127.0.0.1:4800.
• Override: set VITE_BACKEND_URL (and rebuild).

Economic Calendar

The economic calendar syncs macro events into a local SQLite cache with automatic live refresh.

Optional env vars:

• THELAB_FMP_API_KEY
• THELAB_ECON_SAMPLE
• THELAB_ECON_LIVE_SYNC_ENABLED
• THELAB_ECON_LIVE_SYNC_INTERVAL_MS
• THELAB_ECON_LIVE_SYNC_PAST_DAYS
• THELAB_ECON_LIVE_SYNC_FUTURE_DAYS
• THELAB_ECON_LIVE_SYNC_PROVIDER_MODE

See docs/public/economic-calendar.md for details.

Binance USDT-M (BTCUSDT)

Fetch full BTCUSDT M1 history from Binance USDT-M into SQLite and create meta files:

npm --prefix server run import:binance:m1

This stores M1 in server/db/market.db and makes M5/M15/H1/H4/D1 available via derived windows.

Desktop (Electron)

npm install --prefix desktop
npm run build --prefix root-files
npm run dev --prefix desktop

See desktop/README.md and docs/private/core/desktop-shell.md.

Fonts (local, optional)

The UI supports local-first fonts (not committed by default).

• Suisse Int'l (default UI font when present):
  • Copy files into: public/assets/fonts/suisse-intl/
  • Expected filenames (any of: .woff2 / .woff / .otf / .ttf):
    • SuisseIntl-Regular.* (400)
    • SuisseIntl-Medium.* (500)
    • SuisseIntl-SemiBold.* (600)
• SF Pro (optional alternative):
  • Copy files into: public/assets/fonts/sf-pro/
  • Source (not bundled): https://github.com/sahibjotsaggu/San-Francisco-Pro-Fonts (check licensing before distributing)
  • Expected filenames:
    • SF-Pro-Text-Regular.* (400)
    • SF-Pro-Text-Medium.* (500)
    • SF-Pro-Text-Semibold.* (600)

If fonts are missing, the app falls back to the system UI font stack without console errors.

Python (Indicator Engine)

The backend resolves Python in the following order:

1. THELAB_PYTHON_PATH (if set)
2. Workspace-local venv (.venv or .thelab/venv at repo root)
3. python on PATH

Default indicator timeout: 10s (override via THELAB_INDICATOR_TIMEOUT_MS, in ms).

Recommended setup (repo-root venv):

python -m venv .venv
.\.venv\Scripts\activate  # Windows (PowerShell)
pip install -r server/indicator_runner/requirements.txt

Full docs:

• Public (exposed in the app):
• docs/public/indicators.md
• docs/public/plot-api-v1.md
• docs/public/manifest.md
• docs/public/economic-calendar.md
• Private (engineering):
  • docs/private/indicators/indicator-api.md
  • docs/private/indicators/plot-api-v1.md
  • docs/private/indicators/manifest-api.md

Documentation

Inside the app:

• Documentation view (Docs Explorer)

In the repo:

• docs/architecture/ (LLM-friendly architecture index + deep dives)
• docs/public/ (public docs, exposed in the app)
• docs/private/ (engineering docs)
• architecture.md (top-level architecture index)
• ROADMAP.md (product roadmap)