candle-annotator/openspec/changes/archive/2026-02-13-multi-chart-management/proposal.md

Why

The application currently supports only a single dataset at a time — uploading a new CSV replaces all existing candle data and leaves annotations orphaned. Users lose their previous work every time they load new data. To support iterative analysis across multiple instruments or timeframes, the app needs to manage multiple charts with independent annotation sets.

What Changes

• New "charts" entity: Introduce a charts table to represent named datasets. Each chart holds its own set of candles and annotations.
• Upload creates a new chart: Uploading a CSV creates a new chart (named from the filename) rather than replacing global candle data. BREAKING — existing candle/annotation data will need a migration to belong to a default chart.
• Chart selector UI: A dropdown or list in the sidebar lets users switch between previously uploaded charts. The selected chart's candles and annotations load into the view.
• Per-chart annotations: Annotations are scoped to a chart via a foreign key. Switching charts loads only that chart's annotations.
• Manage Annotation Types link restyled: The "Manage Annotation Types" link is restyled to match the app's theme system (uses theme-aware CSS variables instead of hardcoded blue).

Capabilities

New Capabilities

• chart-management: Managing multiple named charts — creating, selecting, listing, and deleting chart datasets. Includes the chart selector UI component and the charts data model.

Modified Capabilities

• data-ingestion: Upload now creates a new chart instead of replacing all candle data. Candles are associated with a specific chart ID.
• backend-api: All candle and annotation endpoints gain a chartId scope. New endpoints for listing/deleting charts.
• chart-canvas: Chart rendering loads candles filtered by the active chart ID.
• label-management: Annotations are scoped to a chart. Switching charts loads/saves the correct annotation set.
• ui-shell: Sidebar gains a chart selector component. "Manage Annotation Types" link is restyled to use theme-aware styling.

Impact

• Database schema: New charts table. candles and annotations tables gain a chart_id foreign key column. Requires a migration.
• API routes: /api/upload, /api/candles, /api/annotations all change to be chart-scoped. New /api/charts endpoint for CRUD operations.
• Frontend state: page.tsx needs an activeChartId state. Components receive chart context for data fetching.
• Data migration: Existing candles and annotations are migrated into a default chart so no data is lost on upgrade.