feat: add database schema, migrations, and API endpoints for span annotations

- Add span_label_types and span_annotations tables to schema
- Seed default span label types (bull_flag, bear_flag, etc.)
- Implement CRUD API endpoints for span label types
- Implement CRUD API endpoints for span annotations
- Add time swap validation in POST endpoint (start_time <= end_time)

src/app/api/span-annotations/[id]/route.ts

@@ -0,0 +1,87 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { db } from '@/lib/db';
+import { spanAnnotations } from '@/lib/db/schema';
+import { eq } from 'drizzle-orm';
+
+// PATCH - Update span annotation
+export async function PATCH(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  try {
+    const { id } = await params;
+    const body = await request.json();
+
+    const { label, confidence, outcome, notes, sub_spans } = body;
+
+    // Check if the span exists
+    const existing = await db
+      .select()
+      .from(spanAnnotations)
+      .where(eq(spanAnnotations.id, parseInt(id)))
+      .limit(1);
+
+    if (existing.length === 0) {
+      return NextResponse.json(
+        { error: 'Span annotation not found' },
+        { status: 404 }
+      );
+    }
+
+    // Build update object with only provided fields
+    const updates: any = {};
+    if (label !== undefined) updates.label = label;
+    if (confidence !== undefined) updates.confidence = confidence;
+    if (outcome !== undefined) updates.outcome = outcome;
+    if (notes !== undefined) updates.notes = notes;
+    if (sub_spans !== undefined) updates.sub_spans = sub_spans ? JSON.stringify(sub_spans) : null;
+
+    const result = await db
+      .update(spanAnnotations)
+      .set(updates)
+      .where(eq(spanAnnotations.id, parseInt(id)))
+      .returning();
+
+    return NextResponse.json(result[0]);
+  } catch (error: any) {
+    console.error('Error updating span annotation:', error);
+    return NextResponse.json(
+      { error: 'Failed to update span annotation' },
+      { status: 500 }
+    );
+  }
+}
+
+// DELETE - Delete span annotation
+export async function DELETE(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  try {
+    const { id } = await params;
+
+    // Check if the span exists
+    const existing = await db
+      .select()
+      .from(spanAnnotations)
+      .where(eq(spanAnnotations.id, parseInt(id)))
+      .limit(1);
+
+    if (existing.length === 0) {
+      return NextResponse.json(
+        { error: 'Span annotation not found' },
+        { status: 404 }
+      );
+    }
+
+    await db.delete(spanAnnotations).where(eq(spanAnnotations.id, parseInt(id)));
+
+    return NextResponse.json({ message: 'Span annotation deleted successfully' });
+  } catch (error) {
+    console.error('Error deleting span annotation:', error);
+    return NextResponse.json(
+      { error: 'Failed to delete span annotation' },
+      { status: 500 }
+    );
+  }
+}

src/app/api/span-annotations/route.ts

@@ -0,0 +1,86 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { db } from '@/lib/db';
+import { spanAnnotations } from '@/lib/db/schema';
+import { eq, desc } from 'drizzle-orm';
+
+// GET - List all span annotations for a chart
+export async function GET(request: NextRequest) {
+  try {
+    const { searchParams } = request.nextUrl;
+    const chartId = searchParams.get('chartId');
+
+    if (!chartId) {
+      return NextResponse.json(
+        { error: 'chartId parameter is required' },
+        { status: 400 }
+      );
+    }
+
+    const spans = await db
+      .select()
+      .from(spanAnnotations)
+      .where(eq(spanAnnotations.chart_id, parseInt(chartId)))
+      .orderBy(desc(spanAnnotations.start_time));
+
+    return NextResponse.json(spans);
+  } catch (error) {
+    console.error('Error fetching span annotations:', error);
+    return NextResponse.json(
+      { error: 'Failed to fetch span annotations' },
+      { status: 500 }
+    );
+  }
+}
+
+// POST - Create new span annotation
+export async function POST(request: NextRequest) {
+  try {
+    const body = await request.json();
+    const {
+      chart_id,
+      start_time,
+      end_time,
+      label,
+      confidence,
+      outcome,
+      notes,
+      sub_spans,
+      color,
+    } = body;
+
+    if (!chart_id || start_time === undefined || end_time === undefined || !label) {
+      return NextResponse.json(
+        { error: 'chart_id, start_time, end_time, and label are required' },
+        { status: 400 }
+      );
+    }
+
+    // Ensure start_time <= end_time (swap if needed)
+    const actualStartTime = Math.min(start_time, end_time);
+    const actualEndTime = Math.max(start_time, end_time);
+
+    const result = await db
+      .insert(spanAnnotations)
+      .values({
+        chart_id,
+        start_time: actualStartTime,
+        end_time: actualEndTime,
+        label,
+        confidence: confidence || null,
+        outcome: outcome || null,
+        notes: notes || null,
+        sub_spans: sub_spans ? JSON.stringify(sub_spans) : null,
+        color: color || '#2196F3',
+        created_at: Math.floor(Date.now() / 1000),
+      })
+      .returning();
+
+    return NextResponse.json(result[0], { status: 201 });
+  } catch (error: any) {
+    console.error('Error creating span annotation:', error);
+    return NextResponse.json(
+      { error: 'Failed to create span annotation' },
+      { status: 500 }
+    );
+  }
+}

src/app/api/span-label-types/[id]/route.ts

@@ -0,0 +1,110 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { db } from '@/lib/db';
+import { spanLabelTypes, spanAnnotations } from '@/lib/db/schema';
+import { eq } from 'drizzle-orm';
+
+// PATCH - Update span label type
+export async function PATCH(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  try {
+    const { id } = await params;
+    const body = await request.json();
+
+    const { name, display_name, color, hotkey, is_active, sort_order } = body;
+
+    // Check if the type exists
+    const existing = await db
+      .select()
+      .from(spanLabelTypes)
+      .where(eq(spanLabelTypes.id, parseInt(id)))
+      .limit(1);
+
+    if (existing.length === 0) {
+      return NextResponse.json(
+        { error: 'Span label type not found' },
+        { status: 404 }
+      );
+    }
+
+    // Build update object with only provided fields
+    const updates: any = {};
+    if (name !== undefined) updates.name = name;
+    if (display_name !== undefined) updates.display_name = display_name;
+    if (color !== undefined) updates.color = color;
+    if (hotkey !== undefined) updates.hotkey = hotkey;
+    if (is_active !== undefined) updates.is_active = is_active;
+    if (sort_order !== undefined) updates.sort_order = sort_order;
+
+    const result = await db
+      .update(spanLabelTypes)
+      .set(updates)
+      .where(eq(spanLabelTypes.id, parseInt(id)))
+      .returning();
+
+    return NextResponse.json(result[0]);
+  } catch (error: any) {
+    console.error('Error updating span label type:', error);
+
+    if (error.message?.includes('UNIQUE constraint failed')) {
+      return NextResponse.json(
+        { error: 'Span label type with this name already exists' },
+        { status: 409 }
+      );
+    }
+
+    return NextResponse.json(
+      { error: 'Failed to update span label type' },
+      { status: 500 }
+    );
+  }
+}
+
+// DELETE - Delete span label type (only if no span annotations use it)
+export async function DELETE(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  try {
+    const { id } = await params;
+
+    // Check if the type exists
+    const type = await db
+      .select()
+      .from(spanLabelTypes)
+      .where(eq(spanLabelTypes.id, parseInt(id)))
+      .limit(1);
+
+    if (type.length === 0) {
+      return NextResponse.json(
+        { error: 'Span label type not found' },
+        { status: 404 }
+      );
+    }
+
+    // Check if any span annotations use this label
+    const existingSpans = await db
+      .select()
+      .from(spanAnnotations)
+      .where(eq(spanAnnotations.label, type[0].name))
+      .limit(1);
+
+    if (existingSpans.length > 0) {
+      return NextResponse.json(
+        { error: 'Cannot delete span label type: span annotations exist with this label' },
+        { status: 409 }
+      );
+    }
+
+    await db.delete(spanLabelTypes).where(eq(spanLabelTypes.id, parseInt(id)));
+
+    return NextResponse.json({ message: 'Span label type deleted successfully' });
+  } catch (error) {
+    console.error('Error deleting span label type:', error);
+    return NextResponse.json(
+      { error: 'Failed to delete span label type' },
+      { status: 500 }
+    );
+  }
+}

src/app/api/span-label-types/route.ts

@@ -0,0 +1,67 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { db } from '@/lib/db';
+import { spanLabelTypes } from '@/lib/db/schema';
+import { eq } from 'drizzle-orm';
+
+// GET - List all span label types (active only, sorted by sort_order)
+export async function GET() {
+  try {
+    const types = await db
+      .select()
+      .from(spanLabelTypes)
+      .where(eq(spanLabelTypes.is_active, 1))
+      .orderBy(spanLabelTypes.sort_order);
+    
+    return NextResponse.json(types);
+  } catch (error) {
+    console.error('Error fetching span label types:', error);
+    return NextResponse.json(
+      { error: 'Failed to fetch span label types' },
+      { status: 500 }
+    );
+  }
+}
+
+// POST - Create new span label type
+export async function POST(request: NextRequest) {
+  try {
+    const body = await request.json();
+    const { name, display_name, color, hotkey, sort_order } = body;
+
+    if (!name || !display_name || !color) {
+      return NextResponse.json(
+        { error: 'name, display_name, and color are required' },
+        { status: 400 }
+      );
+    }
+
+    const result = await db
+      .insert(spanLabelTypes)
+      .values({
+        name,
+        display_name,
+        color,
+        hotkey: hotkey || null,
+        is_active: 1,
+        sort_order: sort_order ?? 0,
+        created_at: Math.floor(Date.now() / 1000),
+      })
+      .returning();
+
+    return NextResponse.json(result[0], { status: 201 });
+  } catch (error: any) {
+    console.error('Error creating span label type:', error);
+    
+    if (error.message?.includes('UNIQUE constraint failed')) {
+      return NextResponse.json(
+        { error: 'Span label type with this name already exists' },
+        { status: 409 }
+      );
+    }
+
+    return NextResponse.json(
+      { error: 'Failed to create span label type' },
+      { status: 500 }
+    );
+  }
+}

src/lib/db/schema.ts

@@ -38,3 +38,28 @@ export const annotations = sqliteTable('annotations', {
   color: text('color').default('#3b82f6'), // hex color code
   created_at: integer('created_at').notNull(),
 });
+
+export const spanLabelTypes = sqliteTable('span_label_types', {
+  id: integer('id').primaryKey({ autoIncrement: true }),
+  name: text('name').notNull().unique(), // internal name (e.g., 'bull_flag')
+  display_name: text('display_name').notNull(), // UI label (e.g., 'Bull Flag')
+  color: text('color').notNull(), // hex color for rectangle fill
+  hotkey: text('hotkey'), // keyboard shortcut (e.g., '1')
+  is_active: integer('is_active').notNull().default(1), // 1 = active, 0 = inactive
+  sort_order: integer('sort_order').notNull().default(0), // display order
+  created_at: integer('created_at').notNull(),
+});
+
+export const spanAnnotations = sqliteTable('span_annotations', {
+  id: integer('id').primaryKey({ autoIncrement: true }),
+  chart_id: integer('chart_id').notNull().references(() => charts.id),
+  start_time: integer('start_time').notNull(), // Unix timestamp of first candle
+  end_time: integer('end_time').notNull(), // Unix timestamp of last candle
+  label: text('label').notNull(), // pattern name referencing span_label_types.name
+  confidence: integer('confidence'), // 1-5 scale, nullable
+  outcome: text('outcome'), // 'win'|'loss'|'breakeven'|null
+  notes: text('notes'), // free-text, nullable
+  sub_spans: text('sub_spans'), // JSON array of sub-span objects, nullable
+  color: text('color').notNull().default('#2196F3'), // hex color
+  created_at: integer('created_at').notNull(),
+});

src/lib/db/seed-span-label-types.ts

@@ -0,0 +1,82 @@
+import { db } from './index';
+import { spanLabelTypes } from './schema';
+
+export async function seedSpanLabelTypes() {
+  const now = Math.floor(Date.now() / 1000);
+
+  const defaultTypes = [
+    {
+      name: 'bull_flag',
+      display_name: 'Bull Flag',
+      color: '#4CAF50',
+      hotkey: '1',
+      is_active: 1,
+      sort_order: 1,
+      created_at: now,
+    },
+    {
+      name: 'bear_flag',
+      display_name: 'Bear Flag',
+      color: '#F44336',
+      hotkey: '2',
+      is_active: 1,
+      sort_order: 2,
+      created_at: now,
+    },
+    {
+      name: 'head_and_shoulders',
+      display_name: 'Head and Shoulders',
+      color: '#9C27B0',
+      hotkey: '3',
+      is_active: 1,
+      sort_order: 3,
+      created_at: now,
+    },
+    {
+      name: 'double_bottom',
+      display_name: 'Double Bottom',
+      color: '#2196F3',
+      hotkey: '4',
+      is_active: 1,
+      sort_order: 4,
+      created_at: now,
+    },
+    {
+      name: 'wedge_up',
+      display_name: 'Wedge Up',
+      color: '#FF9800',
+      hotkey: '5',
+      is_active: 1,
+      sort_order: 5,
+      created_at: now,
+    },
+    {
+      name: 'wedge_down',
+      display_name: 'Wedge Down',
+      color: '#FF5722',
+      hotkey: '6',
+      is_active: 1,
+      sort_order: 6,
+      created_at: now,
+    },
+    {
+      name: 'custom',
+      display_name: 'Custom',
+      color: '#607D8B',
+      hotkey: '7',
+      is_active: 1,
+      sort_order: 7,
+      created_at: now,
+    },
+  ];
+
+  // Check if types already exist
+  const existing = await db.select().from(spanLabelTypes);
+  
+  if (existing.length === 0) {
+    await db.insert(spanLabelTypes).values(defaultTypes);
+    console.log('Seeded default span label types');
+  } else {
+    console.log('Span label types already exist, skipping seed');
+  }
+}