Yaltopia-Homes-TGClient/docs/SMART_STARTUP_SYSTEM.md

🚀 Smart Startup Notification System

🎯 Problem Solved

Previously, the bot sent startup notifications every time it restarted during development (with npm run dev or nodemon), which was annoying and not useful. Now it only sends startup notifications when it's actually needed.

✅ How It Works

🧠 Smart Detection

The bot now tracks its state and only sends startup notifications when:

1. First Run - Bot starts for the first time (no state file exists)
2. After Shutdown - Bot was properly shut down and is starting again
3. After Crash - Bot crashed and is recovering
4. After Long Downtime - Bot was down for more than 5 minutes (likely a real outage)

🚫 When It WON'T Send Notifications

• Development restarts (nodemon, npm run dev)
• Quick restarts within 5 minutes
• Code changes during development

🔧 New Commands

/bot_state (Admin Only)

Check the current bot state and startup history:

🤖 Bot State Information

📊 Current Status: running
🚀 Last Startup: 05/01/2026, 16:30:25
🛑 Last Shutdown: 05/01/2026, 16:25:10
📝 Shutdown Reason: SIGINT (Ctrl+C)
🔢 Process ID: 12345

💡 Note: Startup notifications are only sent after proper shutdowns or crashes.

📁 State Tracking

The bot creates a .bot-state.json file to track:

• Current status (running/shutdown/crashed)
• Last startup time
• Last shutdown time and reason
• Last crash time and reason
• Process ID

This file is automatically managed and added to .gitignore.

🎯 Scenarios

✅ Will Send Startup Notification

• You stop the bot with Ctrl+C → Start it again
• Bot crashes due to error → Restarts automatically
• Server restarts → Bot starts up
• Backend API goes down for a while → Comes back online

❌ Won't Send Startup Notification

• You save a file during development (nodemon restart)
• You run npm run dev multiple times quickly
• Quick code changes and restarts

🛠️ Technical Details

State File Location

.bot-state.json (in project root)

State Tracking Logic

1. On Startup: Check if state file exists and last startup time
2. On Shutdown: Mark state as "shutdown" with reason
3. On Crash: Mark state as "crashed" with error details
4. Time Check: If >5 minutes since last startup, assume it's a real restart

Graceful Shutdown Handling

• Ctrl+C (SIGINT)
• kill command (SIGTERM)
• Admin /shutdown_bot command
• Process exit events

💡 Benefits

1. Clean Development - No spam notifications during coding
2. Real Alerts - Only get notified when it matters
3. Better Monitoring - Track actual uptime and downtime
4. Debug Info - /bot_state command helps troubleshoot issues

🧪 Testing

To test the system:

1. Development Restart (should NOT notify):

   npm run dev
   # Make a code change (nodemon restarts)
   # No notification sent
   

2. Proper Shutdown/Startup (should notify):

   npm run dev
   # Press Ctrl+C to stop
   npm run dev
   # Startup notification sent!
   

3. Check State:

   /bot_state
   # Shows current state and history
   

🎉 Result

Your monitoring topic will now only receive startup notifications when the bot actually starts up after being down, not during every development restart. This makes the monitoring much cleaner and more useful!

The system is smart enough to distinguish between:

• 🔄 Development restarts (ignored)
• 🚀 Real startups (notified)
• 💥 Crash recovery (notified)
• 🛑 Planned shutdowns (tracked properly)