Citabot is a Flutter app for Android that automates the search for available appointments in services, including ITV (vehicle inspection). The app connects to a robust Python FastAPI backend that performs real-time scraping, delivers accurate appointment data, and sends automatic push notifications when new appointments become available.
- Real-time monitoring: Backend checks for new free appointments every 1 hour
- Firebase Cloud Messaging (FCM): Notifications work even when app is closed
- Smart detection: Only notifies when genuinely new appointments appear
- Works 24/7: No need to keep the app open or check manually
- Clean, intuitive, and responsive Material Design interface
- Custom loading indicators with animations and informative messages
- Enhanced error handling with user-friendly feedback
- Smooth navigation and interactive elements
- Search for real ITV appointments by province, station, and service type
- Favorites system: Save preferred stations for quick access
- Bulk search: Find earliest available appointment across all favorite stations
- Date filtering: Automatically excludes past dates from results
- Real-time availability with accurate dates, times, and prices
- Restricted CORS policy: Backend only accepts requests from known domains
- Rate limiting: Respectful scraping to avoid service disruption
- Intelligent caching: 30-minute cache with background refresh
- Environment-based configuration: Separate settings for development and production
- Flutter 3.x
- Android Studio or Android emulator API 33/34+
- Python 3.9+
- FastAPI and Uvicorn for the backend
- Clone the repository:
git clone https://github.com/Fralopala2/Citabot.git - Install Flutter dependencies:
cd citabot_app flutter pub get - Install backend dependencies:
cd citabot-backend pip install -r requirements.txt
- Download and install the APK on your Android device
- Open the app - it will automatically register for notifications
- Add favorite stations you want to monitor
- Receive automatic notifications when new appointments become available
- Configure environment:
cd citabot-backend cp .env.example .env cp firebase-service-account.json.example firebase-service-account.json # Edit both files with your Firebase credentials
- Start the backend:
Backend available at
uvicorn main:app --reload
http://127.0.0.1:8000
- Configure Firebase:
cd citabot_app/android/app cp google-services.json.example google-services.json # Edit with your Firebase Android configuration
- Run the app:
cd citabot_app flutter run
citabot_app/— Flutter source code (Android only)citabot-backend/— Python FastAPI backend
GET /itv/estaciones— Returns all real ITV stations and provincesGET /itv/servicios— Returns available services for a specific stationGET /itv/fechas— Returns next available dates and times for ITV appointmentsGET /cita-nia— Returns simulated NIA appointments
POST /register-token— Registers FCM device token for notificationsPOST /notifications/test— Test endpoint to send notification to specific tokenGET /notifications/stats— Returns notification system statistics
GET /cache/status— Returns cache status and refresh intervalsPOST /cache/clear— Manually clears all cached dataGET /debug/fechas— Debug endpoint for raw scraper dataGET /— Health check endpoint
Before running the project, you must configure the sensitive files:
cd citabot-backend
cp .env.example .env
cp firebase-service-account.json.example firebase-service-account.jsonThen edit both files with your real Firebase credentials.
cd citabot_app/android/app
cp google-services.json.example google-services.jsonEdit the file with your Firebase configuration for Android.
The .env file in citabot-backend/ should contain:
# Firebase Configuration (for push notifications)
FIREBASE_CONFIG={"type":"service_account","project_id":"your-project",...}
# Cache Configuration (optional)
CACHE_TTL=1800 # 30 minutes cache duration
BACKGROUND_REFRESH_INTERVAL=1800 # 30 minutes between automatic checks
MAX_CONCURRENT_REQUESTS=2 # Limit concurrent scraping requests
REQUEST_DELAY=5.0 # Seconds between requests to be respectful
# Environment
ENVIRONMENT=production # or "development"- Create Firebase project at Firebase Console
- Enable Cloud Messaging in your project
- Generate service account key:
- Go to Project Settings → Service Accounts
- Click "Generate new private key"
- Download the JSON file
- Configure environment:
- For local development: Save as
firebase-service-account.json - For production (Render): Set
FIREBASE_CONFIGenvironment variable with the JSON content
- For local development: Save as
- Robust scraping engine: Extracts real appointment data from official SITVAL system
- Automatic instanceCode extraction: Handles session management reliably
- Intelligent caching: 30-minute TTL with background refresh every 30 minutes
- Rate limiting: Maximum 2 concurrent requests, 5-second delays to prevent bans
- CORS security: Restricted to specific domains, limited HTTP methods
- Environment-aware: Different configurations for development vs production
- Firebase Cloud Messaging (FCM): Industry-standard push notification service
- Automatic token registration: Devices register themselves when app starts
- Background monitoring: Server continuously monitors for new appointments
- Smart detection: Compares current vs cached data to identify new appointments
- Token cleanup: Automatically removes invalid/expired tokens
- Works offline: Notifications delivered even when app is closed
- Custom UI components: Loading indicators with animations and overlays
- Date filtering: Automatically excludes past dates from search results
- Favorites management: Local storage for preferred stations
- Error handling: Comprehensive error messages and recovery options
- Material Design: Modern Android UI following Google's design guidelines
- Backend: Deployed on Render with automatic GitHub integration
- Database: In-memory caching with periodic refresh (no external DB required)
- Security: Environment variables for sensitive data, .gitignore for credentials
- Monitoring: Built-in endpoints for system health and cache status
The backend is deployed at https://citabot.onrender.com with:
- Automatic deployment from GitHub main branch
- Environment variables configured in Render dashboard
- Firebase credentials stored securely as environment variables
- CORS configured for production domains
- Build release APK:
cd citabot_app flutter build apk --release - APK location:
citabot_app/build/app/outputs/flutter-apk/app-release.apk - Installation: Transfer APK to Android device and install
- Health check:
GET https://citabot.onrender.com/ - Notification stats:
GET https://citabot.onrender.com/notifications/stats - Cache status:
GET https://citabot.onrender.com/cache/status
- Save preferred stations: Quick access to your most-used ITV locations
- Bulk search capability: Find earliest appointment across all favorite stations in one search
- Smart comparison: Automatically shows the first available slot among all favorites
- Local storage: Favorites persist on your device for fast access
- Dedicated management: Clean interface for adding/removing favorite stations
- Set and forget: Add stations to favorites and receive automatic notifications
- Real-time monitoring: Backend checks your favorite stations every 30 minutes
- New appointment alerts: Get notified immediately when new slots become available
- No manual checking: System works 24/7 without user intervention
- Multiple stations: Monitor several locations simultaneously
- Loading animations: Custom indicators with rotating icons and overlays
- Informative messages: Clear feedback during data fetching and cache refresh
- Error recovery: Helpful messages and retry options when searches fail
- Date validation: Automatic filtering of past dates from results
- Responsive design: Optimized for different screen sizes and orientations
This project is licensed under the Creative Commons Attribution-NonCommercial 4.0 International License.
Commercial use is strictly prohibited without prior written permission from the author.
Created by Paco (@Fralopala2) Feel free to open issues or suggest improvements via GitHub.