candle-annotator/PLAN.md

This is a great project. Combining financial charting with manual labeling is the first step toward building a custom machine-learning model for trading.

To give you the best "TradingView" feel, we will use Next.js for the framework and Lightweight Charts (by TradingView) for the engine. For the drawing and labeling layer, we’ll implement a custom "Overlay" system to handle clicks and coordinate mapping.

---

🛠 Technical Architecture

1. The Stack

• Framework: Next.js (App Router) for a full-stack React experience.
• Charting Engine: lightweight-charts (the library behind TradingView's lightweight version).
• Database: SQLite using Drizzle ORM (lightweight, fast, and type-safe).
• State Management: React useState and useRef to track the "Active Labeling Mode."
• Data Ingestion: papaparse for fast CSV parsing.

2. Data Schema

We need two main tables in SQLite:

• candles: Stores the OHLC data (Open, High, Low, Close, Time).
• annotations: Stores the labels.
• id: Primary key.
• timestamp: The exact candle time the label belongs to.
• label_type: "break_up", "trend_down", etc.
• geometry: JSON string (to store line coordinates if drawing lines).

3. The "Annotation Overlay" Logic

Lightweight Charts is optimized for performance, not "drawing" by default. To make it feel interactive:

1. Coordinate Mapping: We use the chart.timeScale().coordinateToTime() and series.priceToCoordinate() methods to convert a user's mouse click on the screen into a specific price and time in the database.
2. Visual Markers: We use the built-in setMarkers API to show icons (up/down arrows) for specific patterns like "Break Up."
3. Drawing Lines: For lines, we will use "Price Lines" or a transparent SVG Overlay that sits on top of the chart and scales as the user zooms.

---

📝 Coding Instructions for LLM

Copy and paste the following prompt into your coding LLM (e.g., Claude 3.5 Sonnet or GPT-4o):

---

Prompt for AI Developer

Objective: Build a Next.js web application for EUR/USD candle annotation. Tech Stack: Next.js (App Router), TypeScript, Tailwind CSS, lightweight-charts, lucide-react, papaparse, and SQLite (using Drizzle ORM).

Core Features to Implement:

1. Data Ingestion:

• Create a file upload component that accepts a CSV.
• CSV Format: time, open, high, low, close.
• Parse the CSV and store the records in a local SQLite database.

2. The Chart Canvas:

• Use lightweight-charts to render a candlestick chart.
• Implement a "Toolbox" sidebar with buttons: "Label: Break Up", "Label: Break Down", "Draw Line", "Delete".
• When a user clicks "Label: Break Up" and then clicks a candle on the chart, save that timestamp and label to the annotations table.

3. Interaction Logic:

• Markers: If an annotation exists at a timestamp, display it on the chart using the series.setMarkers() API (e.g., a green 'aboveBar' arrow for Break Up).
• Line Drawing: Implement a basic "two-click" line tool. Click 1 sets start point (Price/Time); Click 2 sets end point. Save coordinates as JSON in SQLite.

4. Backend API:

• POST /api/upload: Parse CSV and populate DB.
• GET /api/annotations: Fetch all saved labels for the current chart.
• POST /api/annotations: Save a new label or drawing.

5. UI Requirements:

• Dark mode theme (Slate-900).
• Sidebar for tool selection.
• Main area for the chart (responsive height).
• Simple "Export" button to download the annotations table as a new CSV (Timestamp, Label, Price).

Please provide the code in a modular structure: /components, /lib/db, and /app/api.

---

🚀 Next Steps

1. Prepare your CSV: Ensure your EUR/USD data has headers named time (in 'YYYY-MM-DD' or Unix format), open, high, low, and close.
2. Initialize the project: If you are running this locally, you will need to run npx create-next-app@latest first.

Would you like me to generate the database schema file (Drizzle/SQLite) for you to get started?