Overview
The bot runs two background services for automated journey notifications:- Journey checker: Continuous loop checking for users who need notifications
- APScheduler jobs: Cron-based tasks for daily maintenance
app/__main__.py:92:
Journey checker service
The journey checker runs continuously, monitoring users for scheduled notifications.Implementation
Defined inapp/vbb/service/checker.py:18:
How it works
- Infinite loop: Runs continuously while bot is active
- Fetch registered users: Gets all users with home and destination addresses configured
- Check notification status: Skip users who already received today’s notification
- Time matching: Check if current time matches user’s
check_time - Launch dialog: Start journey dialog with user’s saved preferences
- Mark notified: Set
is_notified = Trueto prevent duplicate notifications - Sleep: Wait 15 seconds before next check
Time matching logic
- Compares current hour and minute with user’s
check_time - Granularity: 1 minute
- Timezone: Uses system timezone (should be Europe/Berlin)
Background dialog launching
Notifications are sent by programmatically starting a dialog:- Fake user and chat objects: Required by aiogram-dialog
- Background manager: Special dialog manager for non-interactive launches
- Dialog start: Launches
JourneysSG.MAINdialog withnow=Falseparameter
Journey notification flow
Notification message
The journey dialog getter inapp/dialogs/journeys.py:17 fetches journeys:
now=Falsemeans journeys are calculated to arrive at user’sarrival_time- User can paginate through multiple journey options
- Formatted message includes departure/arrival times, lines, transfers
APScheduler jobs
APScheduler handles periodic maintenance tasks.Initialization
Defined inapp/utils/scheduler_jobs.py:1:
Scheduler instance
Created inapp/__init__.py:23:
- Type: AsyncIOScheduler (integrates with asyncio event loop)
- Timezone: Uses system timezone
- Persistence: Jobs lost on restart (in-memory only)
Daily notification reset job
Resets theis_notified flag for all users at midnight.
Implementation
Defined inapp/vbb/service/checker.py:51:
Schedule
- Frequency: Daily
- Time: 00:00 (midnight)
- Timezone: System timezone (should be Europe/Berlin)
Purpose
Ensures users receive exactly one notification per day:Error handling and recovery
Database connection errors
- Automatic rollback on errors
- Connection cleanup after each iteration
- No zombie connections from crashes
VBB API errors
If the VBB API is unavailable:- No retry limit: Will keep attempting until API recovers
- User experience: May receive delayed notification
- No data loss: notification flag only set after successful send
Bot restart behavior
Journey checker:- Restarts immediately with bot
- Catches up on any missed notifications within 15 seconds
- No persistent state needed
- Jobs recreated on startup
- Missed jobs are not executed retroactively
- If bot restarted during midnight reset,
is_notifiedflags remain until next midnight
Performance considerations
Database queries
Each check cycle (15 seconds):- 1 query: Fetch all registered users
- N queries: Update each notified user (worst case: all users)
- 1001 queries in one cycle
- ~15ms per query = ~15 seconds total
- May slow down notification delivery
Optimization strategies
Batch updates:VBB API rate limits
Limit: 100 requests per minute If 100+ users have the samecheck_time:
- All requests sent in one 15-second cycle
- May exceed rate limit
- Some users receive HTTP 429 errors
Monitoring and observability
Logging
The journey checker logs every user check:- Notification count per cycle: Track how many users notified
- API error rate: Watch for VBB API failures
- Database query time: Detect performance degradation
Health checks
Add a health check endpoint:Testing background services
Manual testing
-
Set check_time to current time:
-
Watch logs:
-
Verify no duplicate:
Automated testing
Future enhancements
Journey change detection
Monitor journeys for changes (delays, cancellations):Multiple daily notifications
Support multiple notification times per user:Notification preferences
Allow users to customize notification content:Next steps
Architecture overview
Review the complete system architecture
Database schema
Understand the data model for users and journeys