Project Setup & Implementation Roadmap

This document outlines the current project setup (what has been built) and tracks the progress of upcoming development tasks.

1. What Has Been Built (Bootstrap Status)

The repository scaffolding, local SQLite schemas, and security integrations are fully complete:

• Directory Orchestration: Established api/, mobile/, and infra/ root directories.
• Infrastructure as Code (IaC):
  • Defined the Cloudflare provider in providers.tf.
  • Mapped secure tokens/credentials in variables.tf.
  • Declared the Cloudflare D1 Database and Worker bindings in main.tf.
• Edge API Scaffolding:
  • Initialized Node.js project configuration.
  • Installed wrangler runtime dependencies.
  • Defined database bindings inside wrangler.toml mapping to D1.
  • Added database schemas for festivals, stages, bands, sets, walking travel times, and user preferences in schema.sql.
  • Scaffolded TypeScript entrypoint at src/index.ts queryable via env.DB with D1 types.
  • Configured type checking in tsconfig.json.
• Security Compliance:
  • Configured the root .gitignore to ignore environment configuration files and build outputs.

---

2. Implementation Roadmap & Backlog

The following is the structured checklist representing the roadmap of remaining implementation tasks.

Phase 1: Clashfinder Ingestion & Gemini ETL

• [ ] Task 1.1: Clashfinder Ingest Worker
  • Description: Develop a scheduled/cron-triggered ingestion process that downloads schedule data from Clashfinder or parses the uploaded schedule CSV.
• [ ] Task 1.2: Gemini Data Normalizer
  • Description: Integrate the Gemini API via fetch to convert raw text/HTML scheduling pages into structured sets JSON matching our database ingestion schema.
• [ ] Task 1.3: D1 Batch Ingestion
  • Description: Insert normalized records into the D1 relational database, establishing correct foreign key mapping for festivals, stages, bands, and sets.

Phase 2: Route Optimization & REST API

• [ ] Task 2.1: Route Optimization Engine
  • Description: Implement a pathfinding/scheduling optimization algorithm in the Worker. Using:
    • User preferred bands/priorities (stored in user_preferences).
    • Sets timetable (stored in sets).
    • Stage walking travel times (stored in stage_travel_times).
  • Objective: Maximize total band watching time while accounting for walking travel times, and output a feasible conflict-free itinerary.
• [ ] Task 2.2: REST Endpoints
  • Description: Develop API routes in the Worker:
    • GET /api/schedule — Returns the optimized itinerary and clash-warnings.
    • POST /api/preferences — Set/update user priority levels.
    • POST /api/travel-times — Seed/update travel distances between stages.

Phase 3: Mobile Client Scaffolding

• [ ] Task 3.1: Cross-Platform UI Blueprint
  • Description: Build a clean, responsive mobile frontend (located in mobile/) targeting the Edge API endpoints, showcasing the optimized timeline and generating push notifications/reminders for when to start walking from Stage A to Stage B (all times and walking durations rendered in human-readable minutes, e.g., "5 mins" or "10 mins", rather than raw seconds).