markdown
Feremata is a modern web application designed to solve a critical urban mobility challenge in Addis Ababa, Ethiopia. It helps commuters find the nearest taxi pickup points (hubs) for shared routes with transparent pricing, walking directions, and interactive maps.
In cities with shared taxi systems, finding the right pickup point can be confusing and time-consuming. Feremata bridges this gap by providing:
- 🗺️ Instant Location Discovery - Find taxi hubs in seconds
- 💰 Transparent Pricing - Know your fare before you travel
- 🧭 Walking Directions - Step-by-step guidance to pickup points
- 🎤 Voice Input - Hands-free route searching
- 📱 Offline Support - Access hub information without internet
- 🌍 Interactive Maps - Visualize routes and locations
- Search by starting location and destination
- Intelligent matching algorithm for route suggestions
- Voice-enabled search for hands-free operation
- Real-time results with pricing information
- Powered by Mapbox GL for smooth, responsive maps
- Visual markers for all taxi hubs in Addis Ababa
- GPS integration for user location tracking
- Route highlighting and walking path visualization
- Fixed fares displayed upfront (10-20 Ethiopian Birr)
- No hidden fees or surge pricing
- Price comparison across multiple routes
- Popular route recommendations
- Turn-by-turn navigation to pickup points
- Estimated walking time and distance
- Landmark-based guidance
- Integration with Google Maps
- Browser-based speech recognition
- Support for Amharic and English
- Real-time transcription
- Accessibility-focused design
- 16+ routes covering major areas
- Popular route highlighting
- Price statistics and averages
- Estimated travel durations
- Node.js (v18 or higher) - Download
- npm or bun package manager
- Modern web browser (Chrome, Firefox, Safari, Edge)
- Clone the repository
git clone https://github.com/yourusername/feremata.git cd feremata
Install dependencies
bash npm install Start the development server
bash npm run dev Open your browser Navigate to http://localhost:8080
Build for Production bash
npm run build
npm run preview
🛠️ Technology Stack Frontend Framework React 18.3.1 - Modern UI library with hooks
TypeScript 5.5.3 - Type-safe JavaScript
Vite 5.4.1 - Lightning-fast build tool
UI & Styling Tailwind CSS 3.4.11 - Utility-first CSS framework
shadcn/ui - High-quality React components
Radix UI - Accessible component primitives
Lucide React - Beautiful icon library
Mapping & Location Mapbox GL 3.13.0 - Interactive maps
Geolocation API - User location tracking
State Management TanStack Query 5.56.2 - Server state management
React Router DOM 6.26.2 - Client-side routing
React Hook Form 7.53.0 - Form handling
Additional Features Web Speech API - Voice recognition
date-fns 3.6.0 - Date utilities
Zod 3.23.8 - Schema validation
Sonner - Toast notifications
🗺️ Available Routes Route Price Walking Time Popular Lafto → Mexico 10 Birr 2 min ⭐ Ledata → Mexico 12 Birr 3 min Bole → Piassa 15 Birr 3 min Piassa → Merkato 12 Birr 2 min Bole → Merkato 20 Birr 3 min Ledata → Bole 18 Birr 3 min Coverage Areas:
Lafto
Ledata
Bole
Mexico Square
Piassa
Merkato
💡 Usage Examples Basic Route Search Enter "Lafto" in the "From" field
Enter "Mexico" in the "To" field
Click "Find Pickup Point"
View results with pricing and walking directions
Voice Search Click the microphone icon next to input field
Speak your location (e.g., "Lafto")
The app will transcribe and populate the field
Repeat for destination
Walking Directions Search for your route
Click "Walking Directions" on result card
Follow turn-by-turn instructions
Open in Google Maps for GPS navigation
🎨 Design System Color Palette css /* Primary Colors / --fermata-teal: 166 100% 37% / #00B894 / --fermata-teal-light: 166 100% 47% / #00D9A5 / --fermata-yellow: 44 100% 71% / #FDCB6E / --fermata-yellow-light: 44 100% 81% / #FEE5B0 */ Typography Font Family: System fonts (Inter, SF Pro, Segoe UI)
Headings: Bold, 2xl-6xl sizes
Body: Regular, sm-lg sizes
Code: Monospace for technical content
Components Built with shadcn/ui for consistency
Fully accessible (ARIA compliant)
Responsive design (mobile-first)
Dark mode ready
🔧 Configuration Environment Variables Create a .env file in the root directory:
env
VITE_MAPBOX_TOKEN=your_mapbox_token_here
VITE_API_URL=https://api.feremata.com Mapbox Setup Sign up at Mapbox
Create a new access token
Add token to src/components/MapComponent.tsx
📱 Browser Support Browser Version Support Chrome 90+ ✅ Full Firefox 88+ ✅ Full Safari 14+ ✅ Full Edge 90+ ✅ Full Opera 76+ ✅ Full Note: Voice input requires browser support for Web Speech API (Chrome, Edge recommended)
🤝 Contributing We welcome contributions from the community! Here's how you can help:
Ways to Contribute 🐛 Report bugs and issues
💡 Suggest new features
📝 Improve documentation
🔧 Submit pull requests
🌍 Add new routes and locations
Development Workflow Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request
Code Style Follow TypeScript best practices
Use ESLint and Prettier for formatting
Write meaningful commit messages
Add comments for complex logic
Test your changes thoroughly
📄 License This project is licensed under the MIT License - see the LICENSE file for details.
👥 Team Feremata is built with ❤️ by developers passionate about improving urban mobility in Ethiopia.
Project Lead: Your Name
Contributors: See all contributors
🙏 Acknowledgments Lovable.dev - Initial project scaffolding
shadcn/ui - Beautiful component library
Mapbox - Mapping infrastructure
Addis Ababa Taxi Drivers - Route data and insights
Open Source Community - Amazing tools and libraries
📞 Contact & Support Website: feremata.com
Email: support@feremata.com
Twitter: @feremata
GitHub Issues: Report a bug
🗺️ Roadmap Version 1.0 (Current) ✅ Route search functionality
✅ Interactive maps
✅ Transparent pricing
✅ Voice input
✅ Walking directions
Version 2.0 (Planned) 🔄 Real-time taxi availability
🔄 User accounts and favorites
🔄 Offline map caching
🔄 Multi-language support (Amharic, Oromo)
🔄 Mobile app (iOS & Android)
Version 3.0 (Future) 🔮 AI-powered route recommendations
🔮 Integration with ride-hailing services
🔮 Community-driven route updates
🔮 Payment integration
🔮 Expansion to other Ethiopian cities
📊 Project Stats Routes: 16 active routes
Coverage: 6 major areas in Addis Ababa
Price Range: 10-20 Ethiopian Birr
Average Walking Time: 2-3 minutes
Components: 50+ React components
Lines of Code: ~5,000+
Made with ❤️ in Addis Ababa, Ethiopia