# 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: Apache ECharts
- 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:

```bash
npm install --prefix root-files
npm install --prefix server
```

Run frontend + backend:

```bash
npm --prefix root-files run app
```

Main checks and tests:

```bash
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:ui:chart-zoom-anchor # zoom/scroll anchor stability regression (M1 + incremental history)
npm --prefix root-files run test:ui:chart-debugger-repro # automated chart navigation repro runner (M1/M5/M15/H1 + debugger logs)
npm --prefix root-files run test:ui:chart-nav-surgical-regressions # surgical regression matrix (scroll/zoom/history/time-travel)
npm --prefix root-files run test:ui:chart-nav-runner-hardening-v2 # hardened end-to-end runner (UI+debugger+regression, isolated backend, emits tmp/chart-nav-runner-hardening-v2-{report,metrics}.json)
npm --prefix root-files run test:ui:chart-runner-interactions-hardening-v4 # interaction hardening runner (zoom/scroll/back-to-present), emits tmp/chart-runner-interactions-hardening-v4-report.json
npm --prefix root-files run test:chart:perf # chart perf smoke (requires debug mode + backend on :4800)
```

## Debugging (CLI)

### Chart navigation debugger (zoom/scroll/load observability)

Frontend runtime debugger for reproducible viewport-jump investigations:

- Enable: `VITE_CHART_DEBUGGER=1` (or `localStorage.setItem('thelab.chartDebugger','1')`)
- Optional guardrails:
  - `VITE_CHART_DEBUGGER_SAMPLE_RATE`
  - `VITE_CHART_DEBUGGER_VISIBLE_SAMPLE_RATE`
  - `VITE_CHART_DEBUGGER_BACKEND` / `VITE_CHART_DEBUGGER_BACKEND_SAMPLE_RATE`
  - `VITE_CHART_DEBUGGER_SNAPSHOTS` / `VITE_CHART_DEBUGGER_SNAPSHOT_SAMPLE_RATE`
  - `VITE_CHART_DEBUGGER_BUFFER_SIZE`
- Runtime export: `window.__AERA_CHART_DEBUGGER__.exportJson()` / `.downloadJson()`
- Backend correlation: events go to `POST /api/debug/client-log` (`module=chart-debugger`), with optional `POST /api/debug/chart/snapshot` capture.

Run the Debug Doctor:

```bash
npm --prefix root-files run debug:doctor
```

Lean diagnostics (CLI + Docker + local engine):

```bash
npm --prefix root-files run debug:lean
```

Generate an agent report (Top gargalos + tendências):

```bash
npm --prefix root-files run debug:report
```

Full JSON bundle:

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

Execute a debug command:

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

Replay anchor (headless):

```bash
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 BTCUSDT history from Binance USDT-M into SQLite and create meta files:

```bash
npm --prefix server run import:binance:m1
```

To import higher timeframes directly (H1/H4/D1), pass intervals:

```bash
npm --prefix server run import:binance:m1 -- --intervals=1m,1h,4h,1d
```

This stores the selected intervals in `server/db/market.db`. M5/M15 remain derivable from M1 unless you import them too.

## Desktop (Electron)

```bash
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):

```bash
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`

## Lean (Backtesting)

- Lean CLI runs Docker-based backtests (`pip install lean` + Docker Desktop).
- To run the local open-source engine instead, clone https://github.com/QuantConnect/Lean, build `Launcher`, and set `LEAN_ENGINE_PATH` to the repo root.
- Python strategies require `PYTHONNET_PYDLL` pointing to your Python DLL (see `Algorithm.Python/readme.md` in the Lean repo).
- Quick diagnostics: `npm --prefix root-files run debug:lean`.
- Optional timeout (ms): `LEAN_BACKTEST_TIMEOUT_MS`.

## 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)