TradingView

Build a local-first market charting app called "deskchart". Single user, runs on my machine, no accounts, no telemetry, no cloud.

Stack, not negotiable:
- Vite + React + TypeScript for the UI
- lightweight-charts (MIT, from TradingView) for rendering candles and overlays
- A small Express + TypeScript server in the same repo as a data proxy and cache
- SQLite via better-sqlite3 for candle cache, watchlists and alerts
- pnpm workspaces, one command to run both: pnpm dev

Data:
- Crypto: Binance public REST klines endpoint, no key needed, treat this as the real-time path
- Equities and ETFs: Stooq daily CSV as the default source, with an optional adapter interface so another provider can be dropped in via .env
- Cache every fetched candle range in SQLite and only request the missing tail on reload
- Put any API keys in .env, read via a single config module, ship .env.example. Never hardcode secrets
- Print a visible "DELAYED" badge on any symbol whose source is not real time. Do not pretend otherwise

Features in scope:
- Symbol search over a locally seeded symbol list, watchlists stored in SQLite
- Candlestick chart with timeframe switcher: 1m, 5m, 1h, 1d, 1w
- Indicator overlays computed client side: SMA, EMA, VWAP, RSI and MACD in a lower pane
- Persisted horizontal price lines and trendlines per symbol, saved to SQLite
- Simple alerts: price crosses above or below a level. Server polls every 60s and fires a desktop notification via node-notifier plus a row in an alerts log
- Dark theme, keyboard shortcuts for timeframe and symbol switching

Explicitly out of scope, do not attempt:
- Any scripting language or Pine Script compatibility
- Broker connections or order entry
- Social feed, published ideas, comments
- Multi-user auth, hosted deployment, mobile apps
- Scraping any paid or authenticated data feed

Deliverables: working repo, README with setup and a blunt "data limitations" section, seed script for symbols, and vitest coverage on the indicator math and the cache-gap logic.

# AGENTS.md — Build guide for TradingView

## Project scope
A local charting app that pulls daily and intraday candles from free public endpoints, caches them in SQLite, renders them with lightweight-charts, and polls a handful of price alerts you define yourself.

Catalogue verdict: no. The chart widget itself is not the product, and TradingView proved that by open sourcing a perfectly good one: lightweight-charts is MIT licensed and you can have candles on screen in an afternoon. What you cannot build is the data pipe behind it. Real-time consolidated equity, futures and options feeds are licensed per exchange, per user, with entitlement checks and redistribution rules, and the free endpoints you will end up scraping are delayed, rate limited and quietly break. On top of that sits Pine Script and roughly a decade of community published indicators and strategies, plus screeners over every listed symbol, alerts that fire while your laptop is shut, and broker order routing. A local build gives you crypto in real time and equities on a delay, which is either fine or completely useless depending on your time horizon.
Use the implementation prompt below to define the deliverable. Complete each phase's acceptance checks before extending the scope.

## Working agreement
- Inspect the repository and its existing instructions before choosing paths, dependencies or commands. Keep one coherent stack and explain changes to the proposed architecture.
- Plan a vertical slice that accepts a real input and produces the useful output described below. Persist only the state the prompt calls for; respect memory-only and upstream-managed workflows. Use fixtures only when they are clearly labelled.
- After scaffolding, document the actual install, development, check and build commands in README and keep them synchronized with the package or project manifest. Do not report commands as successful unless they ran.
- Work in small steps. At handoff, list implemented flows, checks actually performed, remaining blockers, and any credentials or provider setup the owner must supply.
- Do not publish, spend money, contact customers, delete source data or run irreversible migrations without the project owner's authorization.

## Prerequisites
- Node 20 plus
- A machine left running if you want alerts to fire
- Tolerance for delayed or rate limited free equity data
- Binance or similar public API for anything that needs to be genuinely real time

## Stack and architecture
- Vite + React + TypeScript for the UI.
- Model accounts, source transactions, ledger entries, reconciliations, and reports; keep stable source IDs and timestamps.
- Interface for this market charting and analysis workflow: a local web page with input, progress, review, and export views.

## Security and data integrity
- If Binance or similar public API for anything that needs to be genuinely real time is unavailable, keep the source record and show a recoverable error instead of a fabricated result.
- Validate imported records and file paths; keep user data within the storage location named in the prompt.
- State the practical limit: Licensed real-time exchange data for equities, futures and options; free sources are delayed and fragile.

## Agent implementation rules
- Project rule, data: Model accounts, source transactions, ledger entries, reconciliations, and reports; keep stable source IDs and timestamps.
- Project rule, behavior: Crypto: Binance public REST klines endpoint, no key needed, treat this as the real-time path.
- Project rule, recovery: If Binance or similar public API for anything that needs to be genuinely real time is unavailable, keep the source record and show a recoverable error instead of a fabricated result.

## Optional agent skills and references
No installable skill is listed for this guide; use the project rules and the stack documentation.

Read the linked SKILL.md and its dependencies before adding a skill. Select only the skills matching this project's runtime and task; their documentation does not supply API access, credentials or approval to perform external actions. Pin the reviewed revision where the tool supports it. Follow the chosen agent's documented project-level installation mechanism.

## Distribution ideas
These are optional planning notes. Obtain the owner's approval before publishing or contacting anyone.
- Demonstrate this market charting and analysis operation with sample or user-owned data: Crypto: Binance public REST klines endpoint, no key needed, treat this as the real-time path.
- Show a concrete result or export: Deliverables: working repo, README with setup and a blunt "data limitations" section, seed script for symbols, and vitest coverage on the indicator math and the cache-gap logic.
- State the practical limit: Licensed real-time exchange data for equities, futures and options; free sources are delayed and fragile.

## Engineering roadmap
1. Phase 1, architecture and data: Vite + React + TypeScript for the UI. Model accounts, source transactions, ledger entries, reconciliations, and reports; keep stable source IDs and timestamps.
2. Phase 2, implement: Crypto: Binance public REST klines endpoint, no key needed, treat this as the real-time path.
3. Phase 3, implement: Equities and ETFs: Stooq daily CSV as the default source, with an optional adapter interface so another provider can be dropped in via .env.
4. Phase 4, review and output: Candlestick chart with timeframe switcher: 1m, 5m, 1h, 1d, 1w. Deliverables: working repo, README with setup and a blunt "data limitations" section, seed script for symbols, and vitest coverage on the indicator math and the cache-gap logic.
5. Phase 5, recovery and acceptance: If Binance or similar public API for anything that needs to be genuinely real time is unavailable, keep the source record and show a recoverable error instead of a fabricated result. Verify this invariant with a saved fixture: The sum of debits and credits must balance for posted entries; an import retry cannot change the closing balance. State the practical limit: Licensed real-time exchange data for equities, futures and options; free sources are delayed and fragile.

## Paid-product capabilities outside this build
- Licensed real-time exchange data for equities, futures and options; free sources are delayed and fragile
- Pine Script and the enormous library of published indicators and strategies other people already wrote
- Server side alerts that fire when your device is off, plus push and email delivery
- Screeners and scanners over every listed symbol, and multi-market symbol coverage in general
- Polished mobile and desktop apps with drawings and watchlists synced across all of them
- Broker connections and one click order entry from the chart

## Implementation prompt
Build a local-first market charting app called "deskchart". Single user, runs on my machine, no accounts, no telemetry, no cloud.

Stack, not negotiable:
- Vite + React + TypeScript for the UI
- lightweight-charts (MIT, from TradingView) for rendering candles and overlays
- A small Express + TypeScript server in the same repo as a data proxy and cache
- SQLite via better-sqlite3 for candle cache, watchlists and alerts
- pnpm workspaces, one command to run both: pnpm dev

Data:
- Crypto: Binance public REST klines endpoint, no key needed, treat this as the real-time path
- Equities and ETFs: Stooq daily CSV as the default source, with an optional adapter interface so another provider can be dropped in via .env
- Cache every fetched candle range in SQLite and only request the missing tail on reload
- Put any API keys in .env, read via a single config module, ship .env.example. Never hardcode secrets
- Print a visible "DELAYED" badge on any symbol whose source is not real time. Do not pretend otherwise

Features in scope:
- Symbol search over a locally seeded symbol list, watchlists stored in SQLite
- Candlestick chart with timeframe switcher: 1m, 5m, 1h, 1d, 1w
- Indicator overlays computed client side: SMA, EMA, VWAP, RSI and MACD in a lower pane
- Persisted horizontal price lines and trendlines per symbol, saved to SQLite
- Simple alerts: price crosses above or below a level. Server polls every 60s and fires a desktop notification via node-notifier plus a row in an alerts log
- Dark theme, keyboard shortcuts for timeframe and symbol switching

Explicitly out of scope, do not attempt:
- Any scripting language or Pine Script compatibility
- Broker connections or order entry
- Social feed, published ideas, comments
- Multi-user auth, hosted deployment, mobile apps
- Scraping any paid or authenticated data feed

Deliverables: working repo, README with setup and a blunt "data limitations" section, seed script for symbols, and vitest coverage on the indicator math and the cache-gap logic.

## Completion evidence
Demonstrate the prompt's acceptance scenarios against the scoped workflow. Include setup from a clean checkout and failure recovery. Check persistence across restart and export/restore only for the state the prompt says to store; for memory-only tools, confirm that temporary content is discarded as specified. Record actual results and remaining limitations. A detailed plan alone does not establish a working replacement.