trentuna/candle-annotator
8
0
Fork 0
Code Issues Pull requests Releases Packages Activity Actions

docs: comprehensive documentation updates for v2.0.0

Browse source 
- Update README.md with Docker quickstart and new features (label management, hacker theme)
- Add detailed Docker deployment section to DEPLOYMENT.md:
  - docker-compose usage
  - Environment configuration
  - Data persistence and backup
  - Container health checks
  - Troubleshooting steps
  - Production deployment guidance
- Create comprehensive CLAUDE_DESCRIPTION.md:
  - Project overview and version info
  - Recent changes in v2.0.0
  - Technical stack details
  - Core features and file structure
  - State management explanation
  - Data flow diagrams
  - API endpoints reference
  - Development workflow
  - Customization points
  - Performance and security notes
This commit is contained in:
Marko Djordjevic 2026-02-12 15:13:59 +01:00
parent a1fa86fe55
commit 83be6bbdfb
4 changed files with 526 additions and 5 deletions
Download patch file Download diff file Expand all files Collapse all files

264
CLAUDE_DESCRIPTION.md Normal file
View file

@ -0,0 +1,264 @@
# Candle Annotator - Project Description
## Project Overview
Candle Annotator is a web-based tool for manually annotating candlestick charts with pattern labels and trend lines. It's designed for traders and ML researchers creating labeled training datasets for trading algorithm development.
**Current Version**: 2.0.0 (Major feature release with label management, hacker theme, and Docker support)
## Recent Changes (v2.0.0)
### Label Management System
- **Label Sidebar**: Comprehensive collapsible sidebar showing all Break Up and Break Down annotations
- **Click Selection**: Click markers on chart or list items to select/highlight them
- **Keyboard Delete**: Press Delete or Backspace to remove selected label
- **Search & Filter**: Search by timestamp, filter by type, count display
- **Individual Delete**: Per-item trash button for quick removal
- **Visual Feedback**: Selected markers display with increased size and bright glow
### Hacker Theme
- **Color Scheme**: Matrix green (#00ff41) on dark background (#0a0e0a)
- **Typography**: Monospace font (JetBrains Mono with fallbacks)
- **Effects**: Glow effects on button hover, pulsing animations for active tools
- **Details**: Custom scrollbars, selection highlighting, terminal aesthetic
- **Accessibility**: High contrast meeting WCAG AA standards
### Docker Deployment
- **Multi-stage Build**: Optimized Dockerfile with ~100MB final image
- **Persistence**: Named volume for SQLite database across restarts
- **Health Check**: Built-in /api/health endpoint for container health
- **Security**: Non-root user (nextjs:1001) for safe execution
- **Convenience**: docker-compose.yml for one-command deployment
### API Enhancements
- **Bulk Delete**: DELETE /api/annotations?type=break_up,break_down for batch operations
- **Health Endpoint**: GET /api/health with optional database check (?check=db)
- **Existing DELETE /api/annotations/[id]**: Handles individual label deletion
## Technical Stack
### Frontend
- **Framework**: Next.js 16 (App Router)
- **UI Library**: React 19
- **Language**: TypeScript 5
- **Styling**: Tailwind CSS 3 + shadcn/ui components
- **Charting**: lightweight-charts v4 (TradingView fork)
- **Icons**: lucide-react
### Backend
- **Runtime**: Node.js 18.x
- **API**: Next.js API Routes
- **Database**: SQLite with better-sqlite3
- **ORM**: Drizzle ORM
- **CSV**: papaparse
### DevOps
- **Containerization**: Docker with multi-stage builds
- **Orchestration**: docker-compose
- **Build**: Next.js standalone output mode
- **Monitoring**: Health check via wget
## Core Features
### Annotation Tools
1. **Break Up Labels**: Click marker on candle to add upward breakout label
2. **Break Down Labels**: Click marker on candle to add downward breakout label
3. **Trend Lines**: Two-click drawing with SVG overlay for custom trend lines
4. **Delete Tool**: Remove any annotation by clicking it
### Data Management
- **CSV Upload**: Import OHLC data (time, open, high, low, close)
- **Persistent Storage**: SQLite database stores all annotations
- **CSV Export**: Download labeled data for ML training
### UI Components
- **Toolbox**: Left sidebar with tool buttons, color picker, label management
- **CandleChart**: Main chart area with interactive candlestick visualization
- **FileUpload**: Drag-and-drop CSV file upload
- **Label Sidebar**: Collapsible section with annotation list, search, filter
## File Structure & Key Files
```
src/
├── app/
│ ├── api/
│ │ ├── annotations/[id]/route.ts # GET label by ID, PATCH update, DELETE remove
│ │ ├── annotations/route.ts # GET all, POST create, DELETE bulk
│ │ ├── candles/route.ts # GET all candles
│ │ ├── export/route.ts # GET CSV export
│ │ ├── health/route.ts # GET health check
│ │ └── upload/route.ts # POST CSV file upload
│ ├── globals.css # Hacker theme CSS variables
│ ├── layout.tsx # Root layout with font loading
│ └── page.tsx # Main app (state management)
├── components/
│ ├── CandleChart.tsx # Chart core with markers
│ ├── SvgOverlay.tsx # Line drawing layer
│ ├── Toolbox.tsx # Sidebar with tools & label list
│ ├── FileUpload.tsx # CSV upload
│ └── ui/ # shadcn/ui components
└── lib/
├── db/
│ ├── index.ts # Drizzle client
│ ├── schema.ts # Table definitions
│ └── migrate.ts # Migration runner
└── utils.ts # Utility functions
Docker files:
├── Dockerfile # Multi-stage build
├── docker-compose.yml # Compose configuration
├── .dockerignore # Exclude from image
└── .env.example # Environment template
```
## State Management
### Page Component (src/app/page.tsx)
- `activeTool`: Current selected tool (break_up, break_down, line, delete)
- `selectedColor`: Color for trend lines
- `selectedLabelId`: Currently selected label marker (null if none)
- `annotations`: Array of all annotations for sidebar
### CandleChart Component
- Fetches candles and annotations from API
- Renders markers with highlight for selectedLabelId
- Handles click events for annotation creation and selection
- Exposes refreshData() method for parent updates
### Toolbox Component
- `labelsExpanded`: Sidebar collapsed/expanded state
- `searchText`: Search query for timestamp filtering
- `filterType`: Label type filter (all, break_up, break_down)
- Renders label list with click selection and delete buttons
## Data Flow
1. **Initialization**:
- Page mounts → fetch /api/candles + /api/annotations
- CandleChart renders with data
2. **Add Label**:
- User clicks Break Up/Break Down tool
- Clicks on chart candle
- POST /api/annotations
- Chart refreshes automatically
3. **Select Label**:
- User clicks marker on chart OR list item in sidebar
- Updates selectedLabelId state
- CandleChart re-renders marker with highlight
- Sidebar highlights matching list item
4. **Delete Label**:
- Option A: Select label + press Delete key
- Option B: Click trash icon in sidebar list
- DELETE /api/annotations/[id]
- Annotations array updated
- Chart refreshes
5. **Export**:
- User clicks Export CSV button
- GET /api/export downloads CSV file
## API Endpoints
### Data Operations
- `POST /api/upload` - Upload CSV with candle data
- `GET /api/candles` - Fetch all candles
- `GET /api/annotations` - Fetch all annotations
- `POST /api/annotations` - Create label
- `DELETE /api/annotations/[id]` - Delete label
- `DELETE /api/annotations?type=break_up,break_down` - Bulk delete by type
- `GET /api/export` - Download CSV export
### Monitoring
- `GET /api/health` - Health check
- `GET /api/health?check=db` - Health check with database verification
## Development Workflow
### Adding Features
1. Update CandleChart/Toolbox components for UI
2. Add API route in src/app/api/ if needed
3. Update state management in page.tsx
4. Test in browser with `npm run dev`
5. Commit with clear message
### Fixing Bugs
1. Locate issue in component or API route
2. Add console.logs or debugger for investigation
3. Write minimal fix
4. Test across all annotation types
5. Commit with bug fix message
### Deployment
1. Test locally: `npm run dev`
2. Build production: `npm run build`
3. Commit changes
4. Docker deploy: `docker-compose up --build -d`
## Known Constraints
- **Single User**: No authentication, local data only
- **No Undo**: Annotations can only be deleted, not undone
- **SQLite Limits**: Not for concurrent multi-user access
- **Memory**: Large CSV files (100k+ rows) slow performance
- **Lines**: Free-form drawing, no snap-to-candle
## Customization Points
### Theme Colors
Edit CSS variables in src/app/globals.css (matrix green to desired color)
### Chart Appearance
- Candlestick colors: CandleChart.tsx line 119-120
- Grid colors: line 96-98
- Font: globals.css body element
### API Routes
- Validation rules: src/app/api/*/route.ts
- Database operations: Use Drizzle ORM syntax
### UI Components
- Button styles: src/components/ui/button.tsx
- Sidebar layout: src/components/Toolbox.tsx
## Performance Notes
- **Chart rendering**: lightweight-charts optimized, 60fps target
- **SVG lines**: Only visible SVG redrawn, minimal overhead
- **Database**: SQLite async operations in server routes only
- **Frontend**: React memoization for chart component
## Security Considerations
- **Input validation**: File upload checks MIME type
- **SQL injection**: Drizzle ORM parameterized queries
- **CORS**: API routes served same-origin only
- **Docker**: Non-root user (nextjs:1001) for container execution
## Testing Checklist
Before marking features complete:
- [ ] All existing features still work (lines, colors, delete, export)
- [ ] New feature functions as designed
- [ ] Error states handled gracefully
- [ ] Browser console shows no errors
- [ ] Docker build and run successful
- [ ] Data persists across container restart
## Version History
### v2.0.0 (Current)
- Label management sidebar with search/filter
- Hacker theme with matrix colors and monospace font
- Docker deployment with compose
- Keyboard delete for labels
- Label selection on chart
### v1.0.0 (Previous)
- Basic annotation tools (Break Up, Break Down, Line, Delete)
- Candlestick chart visualization
- CSV import/export
- SQLite persistence

224
DEPLOYMENT.md
View file

@ -157,9 +157,233 @@ The application doesn't require any environment variables for local development.
└── public/ # Static assets └── public/ # Static assets
``` ```
## Docker Deployment
### Prerequisites
- Docker (20.10+)
- docker-compose (2.0+)
### Build and Run with Docker Compose
The easiest way to deploy is with docker-compose:
```bash
docker-compose up --build
```
This will:
1. Build the Docker image with multi-stage build optimization
2. Create a named volume `candle-data` for persistent database storage
3. Start the container on port 3000
4. Enable automatic restart unless stopped
### Running in Detached Mode
```bash
docker-compose up -d --build
```
View logs:
```bash
docker-compose logs -f candle-annotator
```
Stop the service:
```bash
docker-compose down
```
### Manual Docker Build and Run
If you prefer to build and run manually:
```bash
# Build image
docker build -t candle-annotator .
# Run container
docker run -d \
-p 3000:3000 \
-v candle-data:/app/data \
--restart unless-stopped \
candle-annotator
```
### Environment Configuration
Create a `.env` file in the project root based on `.env.example`:
```bash
cp .env.example .env
```
Edit `.env` to customize:
```
NODE_ENV=production
PORT=3000
DATABASE_PATH=/app/data/candles.db
```
Pass environment variables to docker-compose:
```bash
docker-compose --env-file .env up -d
```
### Data Persistence
The application stores the SQLite database in a Docker named volume `candle-data`. This ensures data persists across container restarts:
```bash
# View volumes
docker volume ls | grep candle
# Backup database
docker cp candle-annotator:/app/data/candles.db ./backup.db
# Restore database
docker cp ./backup.db candle-annotator:/app/data/candles.db
```
### Accessing the Application
Once running, access the application at:
```
http://localhost:3000
```
Health check endpoint:
```bash
curl http://localhost:3000/api/health
```
With database check:
```bash
curl http://localhost:3000/api/health?check=db
```
### Port Mapping
To run on a different port (e.g., 8080), modify docker-compose.yml:
```yaml
services:
candle-annotator:
ports:
- "8080:3000"
```
Or use environment variable in docker-compose:
```yaml
services:
candle-annotator:
ports:
- "${HOST_PORT:-3000}:3000"
```
Then run:
```bash
HOST_PORT=8080 docker-compose up -d
```
### Container Health Checks
Docker automatically checks container health every 30 seconds using the `/api/health` endpoint. The container will restart if:
- Health check fails 3 times consecutively
- Takes longer than 3 seconds to respond
View health status:
```bash
docker ps
```
Look for the `STATUS` column - it should show `healthy`.
### Troubleshooting
**Port already in use:**
```bash
docker-compose down # Stop any existing containers
docker-compose up -d -p 8080:3000/tcp
```
**Database permission errors:**
```bash
# Ensure volume has correct permissions
docker-compose down
docker volume rm candle-data
docker-compose up --build
```
**Rebuild without cache:**
```bash
docker-compose build --no-cache
docker-compose up -d
```
**View container logs:**
```bash
docker-compose logs -f --tail=100
```
### Update Procedure
To update the application:
```bash
git pull origin master
docker-compose down
docker-compose up --build -d
```
Or with no-cache rebuild:
```bash
git pull
docker-compose down
docker-compose build --no-cache
docker-compose up -d
```
### Production Deployment
For production deployments, consider:
1. **Use a container registry** (Docker Hub, ECR, GCR):
```bash
docker tag candle-annotator myregistry/candle-annotator:v1.0.0
docker push myregistry/candle-annotator:v1.0.0
```
2. **Run on a remote server** (AWS, DigitalOcean, etc.):
```bash
# SSH into server, clone repo, then:
docker-compose up -d
```
3. **Add reverse proxy** (nginx, traefik) for HTTPS:
```yaml
# docker-compose.yml
services:
nginx:
image: nginx:alpine
ports:
- "443:443"
volumes:
- ./nginx.conf:/etc/nginx/nginx.conf
```
4. **Enable Docker logging** for production monitoring:
```bash
docker-compose logs -f --tail=1000 > app.log &
```
## Notes ## Notes
- This application is designed for **single-user local use** only - This application is designed for **single-user local use** only
- There is no authentication or user management - There is no authentication or user management
- The SQLite database is stored locally and not intended for concurrent access - The SQLite database is stored locally and not intended for concurrent access
- For production multi-user deployments, consider migrating to PostgreSQL or similar - For production multi-user deployments, consider migrating to PostgreSQL or similar
- Docker deployment provides lightweight containerization ideal for standalone instances
- The multi-stage Dockerfile keeps image size minimal (~100MB)

41
README.md
View file

@ -33,9 +33,29 @@ Candle Annotator provides a TradingView-like charting interface that allows trad
- **Delete Tool**: Remove any annotation (markers or lines) by clicking on them - **Delete Tool**: Remove any annotation (markers or lines) by clicking on them
- **Tool Toggle**: Click tool button again to deactivate - **Tool Toggle**: Click tool button again to deactivate
### Export ### Label Management
- **Label Sidebar**: View all annotations in collapsible sidebar with:
- **Click Selection**: Click markers on chart or in sidebar to select/highlight
- **Keyboard Delete**: Press Delete or Backspace to remove selected label
- **Individual Delete**: Delete button on each list item
- **Search**: Search annotations by timestamp
- **Filter**: Filter by Break Up, Break Down, or All types
- **Count Display**: See how many Break Up vs Break Down markers exist
- **Visual Highlight**: Selected markers highlighted with glow effect
### UI Theme
- **Hacker Theme**: Terminal-inspired dark aesthetic with:
- Matrix green (#00ff41) on dark background (#0a0e0a)
- Monospace font (JetBrains Mono) throughout
- Glow effects on button hover and active states
- Custom scrollbars styled to match theme
- High contrast for accessibility
### Export & Deployment
- **CSV Export**: Download all annotations with timestamp, label type, and price data - **CSV Export**: Download all annotations with timestamp, label type, and price data
- **ML-Ready Format**: Structured data suitable for training ML models - **ML-Ready Format**: Structured data suitable for training ML models
- **Docker Deployment**: One-command deployment with persistent data volume
- **Health Check**: Built-in /api/health endpoint for monitoring
## Tech Stack ## Tech Stack
@ -50,13 +70,26 @@ Candle Annotator provides a TradingView-like charting interface that allows trad
## Getting Started ## Getting Started
### Docker Quickstart (Recommended)
The fastest way to get running with Docker:
```bash
docker-compose up --build
```
Then open http://localhost:3000
See [DEPLOYMENT.md](./DEPLOYMENT.md#docker-deployment) for detailed Docker instructions.
### Prerequisites ### Prerequisites
- Node.js 18.x or higher - Node.js 18.x or higher (for local development)
- npm 9.x or higher - npm 9.x or higher (for local development)
- Docker & docker-compose (for containerized deployment)
- Build tools for native modules (see DEPLOYMENT.md) - Build tools for native modules (see DEPLOYMENT.md)
### Installation ### Local Development Installation
1. Clone the repository: 1. Clone the repository:
```bash ```bash

2
next-env.d.ts vendored
View file

@ -1,6 +1,6 @@
/// <reference types="next" /> /// <reference types="next" />
/// <reference types="next/image-types/global" /> /// <reference types="next/image-types/global" />
import "./.next/types/routes.d.ts"; import "./.next/dev/types/routes.d.ts";
// NOTE: This file should not be edited // NOTE: This file should not be edited
// see https://nextjs.org/docs/app/api-reference/config/typescript for more information. // see https://nextjs.org/docs/app/api-reference/config/typescript for more information.