CargoFlow is a complete Minimum Viable Product (MVP) logistics platform designed for cargo transportation. The system consists of two Android applications (for Clients and Drivers) and a unified FastAPI backend, providing a seamless experience for managing freight orders, tracking, and communication.
- Dual Android Applications: Native Android apps built with Kotlin and Jetpack Compose for both Clients (cargo owners) and Drivers (carriers).
- FastAPI Backend: A robust Python backend handling authentication, order management, status tracking, and real-time messaging.
- Order Lifecycle Management: Complete status machine for shipments (Confirmed → Driver to Pickup → At Pickup → Cargo Loaded → In Transit → At Destination → Delivered).
- Driver Offers System: Drivers can view available orders and submit competitive price/ETA offers.
- Real-time Chat: Integrated messaging system between clients and drivers for specific orders.
- Incident Reporting: Mechanism for drivers to report incidents or issues during transit.
- Sandbox Provider Architecture: Modular adapter pattern for SMS, Payments, Maps, Push Notifications, Storage, KYC, and Insurance, allowing easy switching between local sandbox and production providers.
- Modern UI/UX: Material 3 design system with glass-morphism effects and holographic backgrounds.
The project is structured as a multi-module Android project sharing a core module, connected to a Python backend.
| Component | Technology Stack | Description |
|---|---|---|
| Client App | Kotlin, Jetpack Compose | Android application for cargo owners to create orders, review offers, and track shipments. |
| Driver App | Kotlin, Jetpack Compose | Android application for carriers to view orders, submit offers, update statuses, and communicate with clients. |
| Core Module | Kotlin | Shared module containing UI components, API client, themes, and animations used by both apps. |
| Backend | Python, FastAPI, SQLite | RESTful API handling business logic, database operations, and notifications. |
- Android Studio (latest version recommended)
- JDK 17
- Android SDK 35 and Build Tools 35.0.0
- Python 3.x (for the backend)
- A physical Android device or emulator for testing
The project includes batch scripts to automate the setup process. Ensure your Android device is connected via USB with USB debugging enabled.
- Extract the repository to your local machine.
- Open the root folder in your preferred IDE (e.g., VS Code or Android Studio).
- Run the main launcher script:
This script will check dependencies, start the FastAPI backend, configure ADB reverse port forwarding, build both APKs, install them on the connected device, and launch the Client application.
.\START_ALL.bat
-
Start the Backend:
.\START_BACKEND.bat
The backend will be accessible at
http://127.0.0.1:8000(Swagger UI at/docs). -
Build the Applications:
.\BUILD_BOTH.bat
APKs will be generated in the respective
build/outputs/apk/debug/directories. -
Install & Run: Use ADB to install the generated APKs on your device or emulator.
The system operates in a local sandbox mode by default (configured via .env).
- Payment: Use the sandbox card
4242 4242 4242 4242. - SMS/Maps/Push: Handled by deterministic local mock implementations.
- Android: Kotlin 2.0.21, Jetpack Compose, Material 3, Coroutines
- Backend: Python, FastAPI, SQLite, Pydantic
- Build System: Gradle (Kotlin DSL), AGP 8.7.3
Before public launch, the following security measures must be implemented:
- Replace demo authentication with OTP and refresh tokens.
- Hash and rotate tokens; move secrets to secure storage.
- Implement PostgreSQL migrations and transaction boundaries.
- Configure HTTPS, reverse proxy, CORS allowlist, and rate limits.
- Add payment webhooks with signature verification.
- Implement audit logs, RBAC, and an admin console.
This project is licensed under the MIT License.