HamSafar - Ride-Sharing App for Central Asia

HamSafar

A mobile app that enables convenient and reliable intercity ride-sharing across Central Asia.

View Demo · Up-to-Date Deployed Version

Table of Contents

1. About The Project
   • Built With
   • Features
   • Goals and Description
   • Context Diagram
2. Roadmap
3. Usage
4. How to Run
5. Development
   • Kanban Board
   • Git workflow
   • Secrets management
   • Automated tests
   • Continuous Integration
6. Quality
7. Architecture
8. Authors
9. License

About The Project

Built With

• 
• 
• 
• 
• 
• 
• 
• 
• 

Features

• User-friendly ride matching - Quickly find available rides or passengers nearby.
• Multi-language support - Available in Tajik, English and Russian to serve Central Asian users.
• Cost-efficient travel - Share ride costs to save money.
• Real-time notifications - Receive alerts about trip status and updates.
• Cross-platform mobile app - Built with Flutter for smooth performance on Android and iOS.
• Fast and reliable backend - Powered by FastAPI for quick responses and scalability.

Goals and Description

The app makes intercity travel in Central Asia easier by connecting drivers with free seats to passengers looking for affordable and flexible rides.

One app — shared trips, lower costs, more freedom.

Context Diagram

Stakeholders:

• Passengers — individuals looking for intercity rides
• Drivers — individuals offering empty seats
• Admin — monitors system performance and user reports

External Systems:

• Yandex Maps API — used for geolocation and map display
• Telegram Gateway — used to send notifications and verification messages
• MongoDB Atlas — database to store user data and trips
• Timeweb VM (Ubuntu) — hosts the backend and database

(back to top)

Roadmap

✅ Completed Checkpoints

• Flutter project initialized and environment configured
• UI/UX wireframes and mobile app design created
• FastAPI backend set up with MongoDB
• Core API endpoints implemented (trip creation, search, auth)
• Database connected to backend logic
• Admin panel features defined and connected
• User and trip models implemented
• Edit ride and edit profile screens developed
• Phone number registration via Telegram implemented
• Localization added: Tajik (default), Russian, English
• Backend and frontend integrated
• Data validation and request structure organized
• Initial admin panel usage enabled
• Project structure customized
• Core debugging and testing completed
• Yandex.Maps API integrated

---

🚧 Upcoming Checkpoints

• Improve phone number registration security
• Refactor codebase and improve documentation
• Prepare production-ready deployment
• Add analytics and basic admin metrics
• Expand admin dashboard functionality
• Implement push notifications
• Add driver identity verification system

(back to top)

How to Run

1. Install Flutter for your development platform
2. Run flutter doctor in your terminal until requirements are satisfied
3. Clone the repository
4. Configure virtual python environment in /backend folder and install requirements.txt
5. Start api server from /backend with the command fastapi dev(or run) api/application.py
6. Execute flutter --no-color pub get from the /frontend directory
7. Run /lib/main.dart to start the application

(back to top)

Development

CONTRIBUTING.md

Kanban board

• Backlog - tasks not yet taken into work.
• To Do - tasks ready to be worked on.
• In Progress - tasks currently being worked on.
• Done - completed and tested tasks.

Git workflow

• main - production-ready branch, contains stable and reviewed code.
• feature/parse-pers-inf - used for implementing a personal info parser.
• destructive_backend_injection - task-specific branch, e.g., for backend experiments or testing.

Rules:

• Creating Issues: from predefined templates (see .gitlab/issue_templates).

• Labelling: used to define type and priority (e.g., feature, bug, P1).

• Assigning: issues are assigned to responsible developers.

• Branches: created from main with clear, task-specific names (e.g., destructive_backend_injection, feature/parse-pers-inf).

• Commit messages: written in imperative mood, e.g., Add ride search feature.

• Merge Requests: always linked to an issue, follow our MR template.

• Code Reviews: require approval from at least 1 teammate.

• Merging: done via squash merge after CI passes and review is complete.

• Closing Issues: issues are manually marked as closed by team members in GitLab once the related work is done.

Git workflow visualization

Secrets management

• All secrets (API keys, etc.) are stored in project_settings.yaml file and not committed to the repository.

Automated tests

• We have implemented unit tests and integration tests.
• Backend tests are located in /backend/test/integration_tests/.
• Frontend unit tests are located in /frontend/test/unit_tests/.
• Testing tools and frameworks are not yet finalized.

Continuous Integration

• CI workflow file: .gitlab-ci.yml
• In CI we use:
  • pycodestyle - for Python static code analysis.
  • pytest - to run backend tests.
  • flutter test - to run frontend tests.
• All CI runs can be viewed here.

(back to top)

Quality

Quality characteristics and quality attribute scenarios

Quality assurance

• Automated tests
• User acceptance tests

Build and deployment automation

• Continuous Integration

(back to top)

Architecture

Tech Stack

Static view

Currently, the system has the following modules:

• Flutter app (Dart) running on mobile devices (Android/iOS)
• Backend API, implemented in our chosen server technology
• MongoDB database

Link to the diagram

---

Dynamic view

Example flow: user creates & confirms a ride

1. Flutter app sends request to FastAPI backend.
2. Backend validates data and writes to MongoDB.
3. A confirmation message is sent via external service.
4. Upon confirmation, backend updates ride status in DB.
5. Optional notification sent to driver/passenger.

Link to the diagram

---

Deployment view

Current state:

• All components are containerized from the beginning.
• Flutter app is developed locally and has not yet been published to Google Play / App Store.

Link to the diagram

Improvement areas:

• Separate concerns in backend (routes, logic, DB)
• Automate deployment (CI)

(back to top)

Authors

Arsen Latipov | Danil Chegaev | Karina Krotova | Sofia Seliutina | Varvara Gubanova | Anna Morozova

(back to top)

License

This project is licensed under the MIT License.

(back to top)