rail-game/TODO.md

Development TODO Plan

Phase 1 – Project Foundations

• Initialize Git hooks, linting, and formatting tooling (ESLint, Prettier, isort, black).
• Configure pyproject.toml or equivalent for backend dependency management.
• Scaffold FastAPI application entrypoint with health-check endpoint.
• Bootstrap React app with Vite/CRA, including routing skeleton and global state provider.
• Define shared TypeScript/Python models for core domain entities (tracks, stations, trains).
• Set up CI workflow for linting and test automation (GitHub Actions).

Phase 2 – Core Features

• Implement authentication flow (backend JWT, frontend login/register forms).
• Build map visualization integrating Leaflet with OSM tiles.
• Define geographic bounding boxes and filtering rules for importing real-world stations from OpenStreetMap.
• Implement an import script/CLI that pulls OSM station data and normalizes it to the PostGIS schema.
• Expose backend CRUD endpoints for stations (create, update, archive) with validation and geometry handling.
• Build React map tooling for selecting a station.
• Enhance map UI to support selecting two stations and previewing the rail corridor between them.
• Define track selection criteria and tagging rules for harvesting OSM rail segments within target regions.
• Extend the importer to load track geometries and associate them with existing stations.
• Implement backend track-management APIs with length/speed validation and topology checks.
• Implement track path mapping along existing OSM rail segments between chosen stations.
• Design train connection manager requirements (link trains to operating tracks, manage consist data).
• Implement backend services and APIs to attach trains to routes and update assignments.
• Add UI flows for managing train connections, including visual feedback on the map.
• Establish train scheduling service with validation rules, conflict detection, and persistence APIs.
• Provide frontend scheduling tools (timeline or table view) for creating and editing train timetables.
• Develop frontend dashboards for resources, schedules, and achievements.
• Add real-time simulation updates (WebSocket layer, frontend subscription hooks).

Phase 3 – Data & Persistence

• Design PostgreSQL/PostGIS schema and migrations (Alembic or similar).
• Implement data access layer with SQLAlchemy and repository abstractions.
• Decide on canonical fixture scope (demo geography, sample trains) and document expected dataset size.
• Author fixture generation scripts that export JSON/GeoJSON compatible with the repository layer.
• Create ingestion utilities to load fixtures into local and CI databases.
• Provision a Redis instance/container for local development.
• Add caching abstractions in backend services (e.g., network snapshot, map layers).
• Implement cache invalidation hooks tied to repository mutations.

Phase 4 – Testing & Quality

• Write unit tests for backend services and models.
• Configure Jest/RTL testing utilities and shared mocks for Leaflet and network APIs.
• Write component tests for map controls, station builder UI, and dashboards.
• Add integration tests for custom hooks (network snapshot, scheduling forms).
• Stand up Playwright/Cypress project structure with authentication helpers.
• Script login end-to-end flow (Playwright).
• Script station creation end-to-end flow.
• Script track placement end-to-end flow.
• Script scheduling end-to-end flow.
• Define load/performance targets (requests per second, simulation latency) and tooling.
• Implement performance test harness covering scheduling and real-time updates.

Phase 5 – Deployment & Ops

• Create Dockerfile for frontend.
• Create Dockerfile for backend.
• Create docker-compose for local development with Postgres/Redis dependencies.
• Add task runner commands to orchestrate container workflows.
• Set up CI/CD pipeline for automated builds, tests, and container publishing.
• Provision infrastructure scripts (Terraform/Ansible) targeting initial cloud environment.
• Define environment configuration strategy (secrets management, config maps).
• Configure observability stack (logging, metrics, tracing).
• Integrate tracing/logging exporters into backend services.
• Document deployment pipeline and release process.

Phase 6 – Polish & Expansion

• Add leaderboards and achievements logic with UI integration.
• Design data model changes required for achievements and ranking.
• Implement accessibility audit fixes (WCAG compliance).
• Conduct accessibility audit (contrast, keyboard navigation, screen reader paths).
• Optimize asset loading and introduce lazy loading strategies.
• Establish performance budgets for bundle size and render times.
• Evaluate multiplayer/coop roadmap and spike POCs where feasible.
• Prototype networking approach (WebRTC/WebSocket) for cooperative sessions.