This repository contains the LiveMapper project - a real-time GPS vehicle tracking application with interactive mapping.

codespaces-react/
├── livemapper/              # Main LiveMapper application
│   ├── src/                 # React/TypeScript source code
│   ├── tests/               # E2E and unit tests
│   └── README.md            # Detailed project documentation
├── specs/                   # Feature specifications
│   └── 001-modern-web-responsive/
│       ├── spec.md          # Feature specification
│       ├── plan.md          # Implementation plan
│       ├── tasks.md         # Task breakdown
│       └── contracts/       # API contracts
└── CONTRIBUTING.md          # Git workflow and contribution guidelines

Navigate to the LiveMapper application directory:

cd livemapper
pnpm install
pnpm run dev

Open http://localhost:3001 to view the application.

Primary Documentation: See livemapper/README.md for:

• Complete feature overview
• Installation and configuration
• Architecture documentation
• API integration details
• Testing and performance metrics
• Troubleshooting guide

Contributing: See CONTRIBUTING.md for:

• Git workflow (main/development/feature branches)
• Commit conventions
• Pull request process

Specifications: See specs/001-modern-web-responsive/ for:

• Feature specifications
• Implementation plans
• API contracts

LiveMapper is a production-ready React application that provides live vehicle tracking using the GPS Live API. It features:

• Real-time vehicle tracking with 5-second updates
• Interactive maps powered by Leaflet and OpenStreetMap
• Smart polling that pauses when browser tab is hidden
• Status indicators with color-coded markers (active/idle/offline)
• Marker clustering for large fleets (500+ vehicles)
• CORS proxy for seamless API integration
• Mock data mode for development and testing

This project uses a structured Git workflow:

• main - Production-ready code (protected)
• development - Active development branch
• feature/* - Feature branches

All development should target the development branch, not main.

See CONTRIBUTING.md for complete workflow details.

✅ Phase 1-3 Complete: MVP with real-time tracking, map UI, and GPS Live API integration

Next Phase: Filter & Search (vehicle filtering and search functionality)

This project uses SpecKit, a specification-driven development workflow for building features systematically.

SpecKit provides slash commands in Claude Code for structured feature development:

• /speckit.specify - Create feature specifications
• /speckit.plan - Generate implementation plans
• /speckit.tasks - Break down into actionable tasks
• /speckit.implement - Execute the implementation
• /speckit.analyze - Verify consistency and quality

Using SpecKit for LiveMapper provided:

✅ Clear Planning - Features specified before implementation ✅ Risk Mitigation - Technical challenges identified early ✅ Phased Development - 8 phases from MVP to full feature set ✅ Quality Documentation - Auto-generated architecture docs ✅ Easy Onboarding - New contributors understand features quickly

All specifications are in /specs/001-modern-web-responsive/:

• spec.md - Feature requirements and acceptance criteria
• plan.md - Technical design and architecture decisions
• tasks.md - Phase-based task breakdown
• constitution.md - Project principles and guidelines
• contracts/ - API contracts and interface definitions

See livemapper/README.md for detailed SpecKit workflow documentation.

This project is licensed under the MIT License - see the LICENSE file for details.

• Issues: GitHub Issues
• Documentation: livemapper/README.md

Built with ❤️ using React, TypeScript, and Leaflet