# ADR-003: Historical warehouse storage (Phase E)

**Status:** Accepted  
**Date:** 2026-10-02

## Context

Phase E requires local, $0 recurring storage for multi-year OHLCV across symbols/timeframes, with range queries for future backtests. Options: SQLite, PostgreSQL, Parquet files.

## Decision

Use **SQLite** (single file) at `data/tradingbite-warehouse.sqlite` (gitignored).

**Access:** Node `better-sqlite3` (server-side and CLI scripts only).

## Rationale

| Criterion | SQLite |
|-----------|--------|
| Long history, range queries | Indexed `(symbol, timeframe, timestamp_ms)` — sufficient for millions of rows locally |
| Incremental sync | UPSERT / INSERT OR IGNORE + metadata table |
| $0 cost | File on disk, no server |
| Backup | File copy (documented) |
| Portability | One file moves with project |
| Complexity | Lower than Postgres ops for solo dev |

**PostgreSQL** deferred until multi-user or remote warehouse is required.  
**Parquet** deferred as primary store (may export later for analytics).

## Consequences

- Warehouse code lives under `lib/warehouse/`
- Import/sync via `npm run warehouse:*` scripts (tsx)
- Next.js API routes query SQLite server-side only
- `/data/` remains gitignored

## UTC

All `timestamp_iso` stored as OANDA UTC; `timestamp_ms` for range indexes.