# BTS Apps Dashboard — Development Requirements ## 1. Project Overview Build an internal web-based application named **"BTS Apps Dashboard"**. The primary purpose of this dashboard is to centrally monitor the **Production Health API of 50+ applications** without manually opening and testing each application. Each application has one **GET Health API endpoint**. The system must automatically call each configured Health API once per day, determine whether the API is working, and display the latest health status in a centralized dashboard. The initial version must remain **simple, reliable, clean, and easy to maintain**, while keeping the architecture flexible enough to support more frequent monitoring and additional functionality in the future. --- # 2. Primary Objective Replace the manual process of checking 50+ applications individually. Current process: ```text Open App 1 → Check API Open App 2 → Check API Open App 3 → Check API ... Open App 50+ → Check API ``` Target process: ```text BTS Apps Dashboard ↓ Automatically check all enabled Health APIs ↓ Store health-check results ↓ Display current status ↓ Show when an API stopped working ``` The dashboard should provide a single source of truth for the production API health of all registered applications. --- # 3. Initial Scope The initial version must support: - Secure dashboard login - Application management - Add application - Edit application - Delete application - Enable/disable monitoring - Configure Production Health API URL - Daily automatic health check - HTTP status validation - Response-time measurement - Error recording - Last successful check - Last failed check - Current status - "Not Working Since" information - Health-check history - Basic dashboard statistics - Configurable monitoring schedule Do NOT implement notifications or alerts in this version. --- # 4. Technology Stack Use the following technology stack. ## Frontend - **Next.js** - **React** - **TypeScript** - **Tailwind CSS** - Use a clean modern component-based UI architecture. - Use a suitable component library such as **shadcn/ui** if helpful. ## Backend Use the backend capabilities of: - **Next.js API Routes / Route Handlers** - **Node.js** - **TypeScript** Keep the backend modular so it can be separated into a standalone service later if required. ## Database Use: - **PostgreSQL** - **Prisma ORM** The database structure must be designed for future scalability. ## Authentication Implement secure username/password authentication. Use: - Secure password hashing such as **bcrypt/argon2** - HTTP-only secure session/cookie or an established authentication solution - Protected dashboard routes - Protected backend APIs Do not store plain-text passwords. ## Scheduler Use a server-side scheduled job for health checks. The architecture should support: - Daily checks initially - Configurable check time - Future frequency options without major architectural changes If the deployment platform provides a native cron/scheduled-job mechanism, use that where appropriate. ## API Health Checking Use: - Native `fetch` or Axios - Configurable timeout - HTTP status validation - Response-time measurement - Network/error handling ## Deployment The application should be deployment-ready for: - AWS - Vercel or similar hosting - Docker-based deployment Prefer a simple deployment architecture for the initial version. --- # 5. Application Data Each application must contain the following information. ### Required fields ```text Project Code Project Name Production Health API URL Monitoring Status ``` ### Recommended fields ```text Description Expected HTTP Status Code Request Timeout Created At Updated At ``` ### Example ```text Project Code: 1118 Project Name: 2ndLine Production Health API URL: https://api.example.com/health Monitoring: Enabled Expected HTTP Status: 200 Timeout: 10 seconds ``` --- # 6. Project Code Project Code must be unique. Examples: ```text 1118 1120 1121 1125 ``` The dashboard should prevent duplicate Project Codes. Display an appropriate validation message when a duplicate code is entered. --- # 7. Application Management Create an **Apps Management** section. ## Add App Provide a form containing: ```text Project Code * Project Name * Production Health API URL * Monitoring Enabled Expected HTTP Status Timeout Description ``` Required fields must be clearly indicated. Validate: - Project Code is not empty - Project Code is unique - Project Name is not empty - Production URL is a valid URL - HTTP status is valid - Timeout is valid --- ## Edit App Allow authorized users to edit all configurable application information. Changes should be recorded through the `updated_at` field. --- ## Delete App Provide a confirmation dialog before deletion. Use **soft delete** rather than immediately permanently deleting the database record. Reason: Health-check history should not be lost accidentally. Deleted applications should no longer appear in the active dashboard. --- # 8. Monitoring Enable / Disable Each application must have: ```text Monitoring Enabled ``` Possible states: ```text Enabled Disabled ``` If monitoring is disabled: - Do not perform health checks - Do not mark the application as failed - Display the application as **Monitoring Disabled** - Preserve its historical health-check data Example: ```text Project: Example App Status: Monitoring Disabled ``` --- # 9. Health Check Process The monitoring engine must automatically run once per day initially. Process: ```text Scheduled Time ↓ Get all active applications ↓ Filter Monitoring Enabled = true ↓ For each application ↓ Send GET request to Production Health API ↓ Start response-time timer ↓ Wait for response ↓ Validate HTTP status ↓ Record result ↓ Update current application health status ``` --- # 10. Health Check Rules The initial health validation is simple. ## Working An API is considered **Working** when: ```text Request succeeds AND HTTP Status Code matches Expected HTTP Status ``` Default Expected HTTP Status: ```text 200 ``` --- ## Not Working An API is considered **Not Working** when any of the following occurs: ```text HTTP 4xx HTTP 5xx Connection refused Connection failure DNS failure SSL/TLS error Request timeout Unexpected HTTP status Other network errors ``` Store the actual error wherever available. --- # 11. Request Timeout Every health check must have a timeout. Default: ```text 10 seconds ``` The timeout should be configurable per application. If the API does not respond within the configured timeout: ```text Status = Not Working Error = Request Timeout ``` --- # 12. Response Time Measure the time taken for each health API request. Store the value in milliseconds. Example: ```text 182 ms 421 ms 1,240 ms ``` Display response time in the dashboard. --- # 13. Health Check Result Each health-check execution must store: ```text Project ID Checked At Status HTTP Status Code Response Time Error Message ``` Example successful result: ```text Project: 2ndLine Checked At: 17 September 2026, 09:00 AM Status: Working HTTP Status: 200 Response Time: 184 ms Error: — ``` Example failed result: ```text Project: Photo App Checked At: 17 September 2026, 09:01 AM Status: Not Working HTTP Status: 503 Response Time: 1,243 ms Error: Service Unavailable ``` --- # 14. Current Application Status Each application should have a current status. Use exactly three primary states: ### Working ```text API responded successfully ``` ### Not Working ```text API failed the latest health check ``` ### Monitoring Disabled ```text Monitoring is intentionally disabled ``` Use clear visual indicators: ```text 🟢 Working 🔴 Not Working ⚪ Monitoring Disabled ``` Do not rely only on colors. Always display the status text as well. --- # 15. Not Working Since This is a critical requirement. If an API changes from Working to Not Working, record the exact time when the failure started. Example: ```text 14 Sep → Working 15 Sep → Not Working 16 Sep → Not Working 17 Sep → Not Working ``` The dashboard should display: ```text Not Working Since: 15 September 2026, 09:02 AM ``` The UI can show the shorter format: ```text Not working since 15 September ``` but the database must store the exact timestamp. --- # 16. Failure Detection Logic Do not overwrite the original failure-start time every day. Example: ```text 15 Sep → Failed failure_started_at = 15 Sep 16 Sep → Failed failure_started_at remains 15 Sep 17 Sep → Failed failure_started_at remains 15 Sep ``` When the API recovers: ```text 18 Sep → Working ``` then: ```text failure_started_at = NULL last_recovered_at = 18 Sep ``` The historical health-check records must remain available. --- # 17. Recommended Additional Status Information Store and display: ```text Last Checked At Last Successful Check Last Failed Check Last Recovered At Not Working Since Current HTTP Status Current Response Time Current Error Message ``` These fields will make troubleshooting much easier. --- # 18. Main Dashboard The main page after login should be the **BTS Apps Dashboard**. At the top, show summary cards: ```text Total Apps Working Not Working Monitoring Disabled ``` Example: ```text ┌────────────────┐ ┌────────────────┐ │ Total Apps │ │ Working │ │ 52 │ │ 49 │ └────────────────┘ └────────────────┘ ┌────────────────┐ ┌────────────────┐ │ Not Working │ │ Disabled │ │ 2 │ │ 1 │ └────────────────┘ └────────────────┘ ``` --- # 19. Application Dashboard Table Display all active applications in a table. Columns: ```text Project Code Project Name Status Checked At HTTP Status Code Response Time Error Message Not Working Since ``` Example: | Project Code | Project Name | Status | Checked At | HTTP | Response | Error | Not Working Since | |---|---|---|---|---:|---:|---|---| | 1118 | 2ndLine | Working | 17 Sep 09:00 | 200 | 184 ms | — | — | | 1120 | TalkSafe | Working | 17 Sep 09:01 | 200 | 241 ms | — | — | | 1121 | Photo App | Not Working | 17 Sep 09:02 | 503 | 1243 ms | Service Unavailable | 15 Sep | | 1125 | Utility App | Monitoring Disabled | — | — | — | — | — | --- # 20. Dashboard Filters Provide basic filtering. Filters: ```text Status: All Working Not Working Monitoring Disabled ``` Search: ```text Search by Project Code or Project Name ``` Optional sorting: ```text Project Code Project Name Status Checked At Response Time ``` --- # 21. Application Details Clicking an application should open a detailed view. Example: ```text 2ndLine Project Code: 1118 Production Health API: https://api.example.com/health Current Status: 🔴 Not Working Not Working Since: 15 September 2026, 09:02 AM Last Checked: 17 September 2026, 09:00 AM HTTP Status: 503 Response Time: 1,243 ms Error: Service Unavailable ``` Below this, show health-check history. --- # 22. Health Check History Display recent health checks for each application. Example: | Checked At | Status | HTTP | Response Time | Error | |---|---|---:|---:|---| | 17 Sep 09:00 | Not Working | 503 | 1243 ms | Service Unavailable | | 16 Sep 09:00 | Not Working | 503 | 1102 ms | Service Unavailable | | 15 Sep 09:00 | Not Working | 503 | 980 ms | Service Unavailable | | 14 Sep 09:00 | Working | 200 | 210 ms | — | Provide pagination for history rather than loading unlimited records. --- # 23. Monitoring Settings Create a basic settings page. Initially support: ```text Check Frequency: Daily Check Time: 09:00 AM Timezone: Asia/Kolkata ``` The system must be designed so future options can be added: ```text Every 1 hour Every 6 hours Every 12 hours Daily Custom ``` Do not hard-code the scheduler in a way that prevents future frequency changes. --- # 24. Manual "Check Now" Feature Although the automatic schedule is daily, add a **Check Now** action. This is highly recommended. For example: ```text [ Check Now ] ``` When clicked: ```text GET Health API ↓ Perform health check ↓ Store result ↓ Refresh dashboard ``` This allows the administrator to immediately verify an API without waiting for the next scheduled check. The manual check should use exactly the same health-check logic as the scheduled check. --- # 25. Security Requirements The dashboard is an internal application and must require authentication. Implement: - Login - Logout - Secure password hashing - Protected dashboard routes - Protected API endpoints - Session expiration - HTTP-only cookies where applicable - CSRF protection where applicable - Input validation - Server-side authorization - Rate limiting on authentication endpoints - Do not expose database credentials or secrets to the frontend Production API URLs and credentials/secrets, if any are introduced later, must never be exposed unnecessarily in frontend code. --- # 26. Database Design Use Prisma with PostgreSQL. Recommended entities: ## User ```text id username password_hash created_at updated_at ``` ## Project ```text id project_code project_name production_url monitoring_enabled expected_http_status timeout_seconds description created_at updated_at deleted_at ``` ## HealthCheck ```text id project_id checked_at status http_status_code response_time_ms error_message ``` Recommended additional fields on Project: ```text last_checked_at last_successful_check_at last_failed_check_at failure_started_at last_recovered_at ``` These can either be stored directly for quick dashboard access or derived from health-check records. Choose the approach that provides good performance while avoiding inconsistent data. --- # 27. Soft Delete Projects should use: ```text deleted_at ``` instead of immediately removing the record. Normal dashboard queries should only show: ```text deleted_at IS NULL ``` Deleting a project must not delete historical health-check records. --- # 28. Error Handling The system must gracefully handle: ```text Timeout DNS error Connection refused SSL error HTTP 400 HTTP 401 HTTP 403 HTTP 404 HTTP 500 HTTP 502 HTTP 503 HTTP 504 Unexpected status Unknown network error ``` The monitoring engine must never crash because one application's API is unavailable. If one API fails: ```text App A → Failed App B → Continue checking App C → Continue checking App D → Continue checking ``` A failure in one project must not stop the remaining health checks. --- # 29. Scheduler Reliability The scheduled health-check process must: - Run automatically at the configured time - Check all enabled applications - Continue if an individual API fails - Record each result - Prevent duplicate execution where possible - Log scheduler execution - Log the number of applications checked - Log successful/failed checks Example internal execution log: ```text Daily Health Check Started Apps Found: 52 Apps Checked: 51 Working: 49 Failed: 2 Disabled: 1 Execution Completed ``` --- # 30. UI/UX Requirements Create a professional internal admin dashboard. Design goals: - Clean - Minimal - Modern - Professional - Easy to scan - Desktop-first - Responsive - Clear status visibility - No unnecessary animations - No excessive decoration - No large unnecessary page titles - Strong table readability - Clear spacing and hierarchy The most important information should be visible immediately: ```text Application Status Last Checked HTTP Status Response Time Error Not Working Since ``` --- # 31. Navigation Use a simple sidebar/navigation. Suggested structure: ```text BTS Apps Dashboard Dashboard Apps Monitoring Settings Logout ``` Optional: ```text Health History System Settings ``` Do not add unnecessary sections in the initial version. --- # 32. Dashboard Refresh The dashboard should show the latest stored health-check information. Provide a manual: ```text Refresh ``` button. After a scheduled or manual health check completes, the dashboard should display the updated information. Optional future enhancement: ```text Auto Refresh every 30/60 seconds ``` Do not make this mandatory for Phase 1. --- # 33. Empty States Handle empty states professionally. If no applications exist: ```text No applications configured yet. Add your first application to start monitoring. [ Add App ] ``` If no health checks have been performed: ```text No health-check data available yet. The first scheduled check will appear here. ``` --- # 34. Validation All validation must happen on both: ```text Frontend Backend ``` Never rely only on frontend validation. Validate: - Required fields - URL format - Project Code uniqueness - HTTP status range - Timeout range - Authentication - Authorization --- # 35. Logging Add application-level logging for: ```text Authentication events Application creation/update/deletion Scheduled health-check execution Manual health checks API failures Scheduler errors Unexpected server errors ``` Do not log passwords, tokens, or sensitive credentials. --- # 36. Performance Requirements The system is initially expected to monitor approximately: ```text 50–100 applications ``` but should be designed so it can grow to: ```text 500+ applications ``` without requiring a complete redesign. The dashboard should use pagination where appropriate. Health checks should be executed independently so one slow API does not block the entire monitoring process unnecessarily. --- # 37. No Notification System Explicitly do NOT implement: ```text Email alerts Slack notifications Microsoft Teams notifications WhatsApp notifications SMS Push notifications PagerDuty ``` The administrator will simply review the **BTS Apps Dashboard**. --- # 38. Future Extensibility Do not implement these features now, but keep the architecture extensible for: ```text Hourly monitoring Multiple Health APIs per project Staging environment monitoring API response-body validation Authentication-based health APIs API dependency monitoring Uptime percentage Charts Incident history Multiple users User roles Audit logs AWS infrastructure monitoring Notifications ``` Do not build these features unless explicitly requested. --- # 39. Initial Success Criteria The project will be considered successfully implemented when: 1. User can log in securely. 2. User can add an application. 3. User can edit an application. 4. User can delete an application. 5. User can enable/disable monitoring. 6. User can configure the Production Health API. 7. System automatically checks enabled applications once per day. 8. System validates the HTTP response. 9. System records HTTP status code. 10. System records response time. 11. System records error messages. 12. Dashboard displays current health status. 13. Dashboard displays last checked time. 14. Dashboard displays "Not Working Since". 15. Historical health-check results are retained. 16. One failed API does not stop other APIs from being checked. 17. User can manually trigger "Check Now". 18. Dashboard requires authentication. 19. No notification functionality is implemented. 20. The application is deployment-ready. --- # 40. Development Approach Build the project incrementally. ### Phase 1 — Foundation - Project setup - Next.js - TypeScript - Tailwind CSS - Prisma - PostgreSQL - Authentication - Basic dashboard layout ### Phase 2 — Application Management - Apps listing - Add App - Edit App - Delete App - Enable/disable monitoring - Validation - Soft delete ### Phase 3 — Health Monitoring - Health-check service - GET request - Timeout handling - HTTP status validation - Response-time measurement - Error handling - Database result storage ### Phase 4 — Dashboard & History - Dashboard statistics - Application status table - Search/filter - Application details - Health-check history - Not Working Since calculation ### Phase 5 — Scheduler & Settings - Daily scheduler - Configurable check time - Timezone - Monitoring settings - Manual "Check Now" ### Phase 6 — Testing & Production Readiness Test: - Healthy API - HTTP 4xx - HTTP 5xx - Timeout - DNS failure - Connection failure - SSL failure - API recovery - Multiple failed days - Monitoring disabled - Deleted application - Duplicate Project Code - Authentication - Unauthorized access - Scheduler failures - Multiple applications being checked independently --- # 41. Important Implementation Instruction Do not over-engineer the first version. The current requirement is intentionally simple: ```text 50+ Apps ↓ One GET Health API per App ↓ Daily Check ↓ Store Result ↓ Dashboard ``` Prioritize: ```text Reliability Accuracy Simplicity Security Maintainability Clean UI ``` over adding unnecessary infrastructure or features. The architecture should be modular enough that future functionality can be added without rewriting the core monitoring system. --- # 42. Final Product Name Use the following product name consistently throughout the UI: **BTS Apps Dashboard** Suggested browser title: ```text BTS Apps Dashboard ``` Suggested login title: ```text BTS Apps Dashboard ``` Suggested dashboard header: ```text BTS Apps Dashboard ``` Do not use generic names such as "API Monitor" in the user-facing UI. --- # 43. Final User Flow ```text Login ↓ BTS Apps Dashboard ↓ ┌───────────┴───────────┐ ↓ ↓ Manage Apps Health Status ↓ ↓ Add/Edit/Delete Current Status ↓ ↓ Configure API Last Checked ↓ HTTP Status ↓ Response Time ↓ Error Message ↓ Not Working Since ↓ Health History ``` The system should provide a simple, reliable and centralized way to determine the production health of all BTS applications without manually opening each application.