candle-annotator/DEPLOYMENT.md

Deployment Guide

Prerequisites

• Node.js 18.x or higher
• npm 9.x or higher
• Python and build tools (for native module compilation)

Local Development Setup

1. Install Dependencies

npm install

Note: The better-sqlite3 package requires native compilation. If you encounter build errors, ensure you have the necessary build tools:

Linux:

sudo apt-get install build-essential python3

macOS:

xcode-select --install

Windows:

npm install --global windows-build-tools

2. Database Setup

The SQLite database will be automatically created when you start the application. The database file is located at:

./data/candles.db

To run migrations manually:

npx drizzle-kit generate
npx drizzle-kit migrate

3. Start Development Server

npm run dev

The application will be available at:

• http://localhost:3000

4. Verify Setup

1. Open the application in your browser
2. Upload a sample CSV file with OHLC data (columns: time, open, high, low, close)
3. Verify the candlestick chart renders correctly
4. Test annotation tools (Break Up, Break Down, Draw Line, Delete)
5. Export annotations as CSV

CSV File Format

The application expects CSV files with the following format:

time,open,high,low,close
1700000000,1.0500,1.0520,1.0490,1.0510
1700000060,1.0510,1.0530,1.0505,1.0525

Time column formats:

• Unix timestamp (seconds): 1700000000
• Date string: 2024-01-15

Building for Production

npm run build

Note: Production builds with better-sqlite3 require the native module to be compiled for the target platform.

Running Production Build

npm run build
npm start

The production server will run on port 3000 by default.

Troubleshooting

better-sqlite3 Build Issues

If you encounter errors related to better-sqlite3 not finding bindings:

1. Rebuild the module:

   npm rebuild better-sqlite3
   

2. If that fails, reinstall:

   npm uninstall better-sqlite3
   npm install better-sqlite3
   

3. For development, you can use npm run dev which handles the module better than production builds.

Database Issues

If the database becomes corrupted or you want to start fresh:

1. Stop the application
2. Delete the database file:

   rm -f data/candles.db
   

3. Restart the application (it will recreate the database)

Port Already in Use

If port 3000 is already in use, you can specify a different port:

PORT=3001 npm run dev

Environment Variables

The application doesn't require any environment variables for local development. All configuration is hardcoded for simplicity.

File Structure

.
├── src/
│   ├── app/              # Next.js app router
│   │   ├── api/          # API routes
│   │   ├── layout.tsx    # Root layout
│   │   └── page.tsx      # Main page
│   ├── components/       # React components
│   │   ├── CandleChart.tsx
│   │   ├── SvgOverlay.tsx
│   │   ├── Toolbox.tsx
│   │   └── FileUpload.tsx
│   └── lib/              # Utilities
│       └── db/           # Database configuration
├── data/                 # SQLite database directory
├── drizzle/              # Database migrations
└── public/               # Static assets

Notes

• This application is designed for single-user local use only
• There is no authentication or user management
• The SQLite database is stored locally and not intended for concurrent access
• For production multi-user deployments, consider migrating to PostgreSQL or similar