FleetTax Documentation
Complete technical documentation for the FleetTax Vahan road tax tracker application.
📖 Project Overview
FleetTax is a fully offline Android application built with Flutter that enables bus and truck fleet owners to efficiently track Vahan road tax payment deadlines. The app eliminates manual tracking by automatically calculating tax expiry dates, sending daily push notifications, and providing direct integration with the Vahan portal.
Key Objectives
- Track Tax Deadlines: Manage multiple vehicles with zero cloud dependency
- Auto Calculation: Automatically calculate expiry dates based on tax payment periods
- Timely Notifications: Send push notifications to prevent missed payments
- Offline First: No internet required, all data stored locally
- Modern Architecture: Built with Flutter, Provider, and SQLite
✨ Core Features
Vehicle Management
- Add Vehicle: Register new vehicles with all details
- Edit Vehicle: Modify any vehicle information
- Delete Vehicle: Remove vehicles with confirmation
- Local Storage: All data stored via SQLite
Dashboard & Tracking
- Statistics Bar: View total, expired, due soon, and valid vehicles
- Search: Find vehicles by registration number
- Filter: Filter by status or vehicle type
- Sort: Organize by expiry date, registration, or type
Notification System
- Daily Alerts: Push notifications from T-10 days until payment
- Background Execution: WorkManager for reliable delivery
- Smart Scheduling: Works even when app is closed
Status Color Coding
| Status |
Color |
Meaning |
| Expired |
Red (#FF0044) |
Tax payment is overdue |
| Due Soon |
Orange (#FF6B35) |
Tax expires within 10 days |
| Valid |
Green (#00E676) |
Tax payment is current |
🛠️ Technology Stack
Frontend Framework
Flutter 3.x: Cross-platform mobile framework with native-like performance and hot reload
Programming Language
Dart 3.x: Modern, statically-typed language with async/await support
State Management
Provider: Lightweight, reactive state management with automatic UI rebuilds
Database
SQLite: Embedded relational database with zero configuration
Background Tasks
WorkManager: Reliable background job scheduling that survives app restart
Additional Libraries
- flutter_local_notifications: Cross-platform push notifications
- intl: Date/time formatting and localization
- url_launcher: Open URLs and external apps
🏗️ Architecture
Project Structure
lib/
├── main.dart # App entry point
├── models/
│ └── vehicle.dart # Vehicle data model
├── db/
│ └── database_helper.dart # SQLite operations
├── services/
│ ├── notification_service.dart # Push notifications
│ └── workmanager_service.dart # Background tasks
├── providers/
│ └── vehicle_provider.dart # State management
├── screens/
│ ├── dashboard_screen.dart # Main view
│ ├── add_edit_screen.dart # Form
│ └── mark_paid_screen.dart # Payment entry
└── widgets/
├── vehicle_card.dart # Vehicle tile
├── stats_bar.dart # Statistics
└── filter_chips.dart # Filters
Architectural Patterns
- MVVM: Model-View-ViewModel with Provider pattern
- Singleton: Single database connection throughout app
- Service Locator: Static methods for service access
🗄️ Database Schema
CREATE TABLE vehicles (
id INTEGER PRIMARY KEY AUTOINCREMENT,
reg TEXT NOT NULL,
type TEXT NOT NULL,
tax_period TEXT NOT NULL,
last_paid TEXT NOT NULL,
notes TEXT,
receipt_ref TEXT,
created_at TEXT NOT NULL
);
Column Descriptions
| Column |
Type |
Description |
| id |
INTEGER |
Primary key, auto-incrementing |
| reg |
TEXT |
Vehicle registration number |
| type |
TEXT |
'bus' or 'truck' |
| tax_period |
TEXT |
'monthly', 'quarterly', or 'yearly' |
| last_paid |
TEXT |
ISO 8601 date (YYYY-MM-DD) |
| notes |
TEXT |
Optional notes |
| receipt_ref |
TEXT |
Optional receipt reference |
| created_at |
TEXT |
Creation timestamp |
🚀 Installation Guide
Prerequisites
- Flutter SDK: Version 3.11.5 or later
- Android Studio: Latest version with Android SDK 33+
- Android Device/Emulator: API 33 (Android 13) or higher
- Git: For cloning the repository
Step 1: Clone Repository
git clone https://github.com/DevanshSrajput/FleetTax.git
cd FleetTax
Step 2: Install Dependencies
flutter pub get
Step 3: Verify Setup
flutter doctor
Step 4: Run Application
# List available devices
flutter devices
# Run on specific device
flutter run -d <device-id>
📦 Building for Production
Release APK Build
flutter build apk --release
Output: build/app/outputs/flutter-apk/app-release.apk
Android Permissions
Ensure android/app/src/main/AndroidManifest.xml includes:
<uses-permission android:name="android.permission.POST_NOTIFICATIONS"/>
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED"/>
<uses-permission android:name="android.permission.SCHEDULE_EXACT_ALARM"/>
<uses-permission android:name="android.permission.INTERNET"/>
🔔 Notification System
How It Works
- App initializes NotificationService on launch
- WorkManager registers a daily background task
- Every 24 hours, the system checks all vehicles
- If daysLeft ≤ 10, a notification is triggered
- Process continues until vehicle is marked as paid
Notification Permissions (Android 13+)
- Runtime permission requested on first launch
- Users must enable in Settings → Apps → FleetTax → Notifications
- On manufacturer phones, allow background activity in battery settings
🐛 Troubleshooting
Notifications Not Showing
Cause: Permission not granted at runtime
Solution: Go to Settings → Apps → FleetTax → Enable Notifications
WorkManager Not Firing
Cause: Android power management killing background tasks
Solution: Allow background activity in battery settings for FleetTax
SDK Not Found
Solution: Run flutter doctor and follow recommendations
MissingPluginException
flutter clean
flutter pub get
flutter run
App Crashes on Launch
Solution: Check flutter logs for full error trace
📚 API Reference
Vehicle Class
Key Methods
- expiryDate: DateTime getter for calculated tax expiry
- daysLeft: int getter for days remaining (negative if expired)
- status: String getter returning 'expired', 'soon', or 'valid'
VehicleProvider
Key Methods
- load(): Load all vehicles from database
- add(Vehicle v): Insert new vehicle
- update(Vehicle v): Update existing vehicle
- delete(int id): Delete vehicle by ID
- markPaid(): Log payment and reschedule notifications
DatabaseHelper
Key Methods
- insert(Vehicle v): Add vehicle, returns ID
- update(Vehicle v): Update vehicle, returns rows affected
- delete(int id): Delete vehicle, returns rows affected
- getAll(): Get all vehicles from database
🗺️ Roadmap
Version 1.0 (Current) ✅
- ✓ Vehicle CRUD - Add, edit, delete vehicles
- ✓ Tax Calculation - Monthly, quarterly, yearly periods
- ✓ Dashboard - Color-coded status cards
- ✓ Search & Filter - Find and organize vehicles
- ✓ Notifications - Daily push alerts
- ✓ Vahan Integration - Direct portal access
- ✓ Offline Mode - Complete offline operation
Version 2.0 (Planned)
- Insurance expiry tracking
- Fitness certificate (FC) tracking
- Google Drive backup and restore
- PDF receipt capture
- Multi-owner and driver assignment
- Play Store release