Skip to content

Plan: Transform Telegram Bot to Web App (Hybrid Architecture)#1

Open
lpsmurf wants to merge 1 commit into
mainfrom
feature/telegram-webapp-plan
Open

Plan: Transform Telegram Bot to Web App (Hybrid Architecture)#1
lpsmurf wants to merge 1 commit into
mainfrom
feature/telegram-webapp-plan

Conversation

@lpsmurf

@lpsmurf lpsmurf commented Mar 31, 2026

Copy link
Copy Markdown
Owner

📱 Telegram Web App Implementation Plan

Summary

Transform @hfsp_agent_bot from a button-based 13-step wizard into a modern hybrid architecture:

  • Bot: Notifications + quick commands + agent pairing
  • Web App: Multi-field setup forms + agent dashboard + real-time status

🎯 Key Improvements

✅ Better forms (single multi-field form instead of step-by-step)
✅ Visual feedback (progress bars, real-time status updates)
✅ Mobile-first responsive design
✅ Professional dark mode UI (matches Telegram theme)
✅ Agent management dashboard (search, filter, sort)

📋 Plan Details

6 Implementation Phases:

  • Phase 1: Web app framework setup (2-3h)
  • Phase 2: Setup form component (4-5h)
  • Phase 3: Dashboard component (3-4h)
  • Phase 4: Real-time updates via WebSocket (3-4h)
  • Phase 5: Bot integration (2-3h)
  • Phase 6: Deployment (1-2h)

Total Estimated Time: 20-30 hours (2-4 days focused development)

🔧 Technology Stack

  • Frontend: React 18 + TypeScript + TailwindCSS
  • Backend: Express + WebSocket (existing + 3 new routes)
  • Database: SQLite (shared with bot, no migrations needed)
  • Telegram Integration: Web App SDK + HMAC validation

🔐 Security

  • Server-side HMAC validation (Telegram initData)
  • JWT tokens for API authentication
  • User can only access their own agents
  • No sensitive data exposed to client

📊 Success Criteria

  • ✅ App loads in <2 seconds on Telegram
  • ✅ Real-time provisioning status (no manual refresh)
  • ✅ Mobile-optimized + dark mode support
  • ✅ Agent dashboard fully functional
  • ✅ Bot notifications working
  • ✅ Backward compatible (bot still works as fallback)

📚 Documentation

Full implementation guide included in WEBAPP_PLAN.md with:

  • Detailed architecture overview
  • Phase-by-phase breakdown
  • Code examples for critical components
  • Integration with existing services
  • Testing strategy
  • Risk mitigation approach
  • Rollout strategy

✋ This is a Planning Document

This PR does not include code - it's the implementation plan for team review. Once approved, implementation will begin following the phases outlined.

See: WEBAPP_PLAN.md for complete details


Generated by Claude | Ready for review and approval

- Build complete React 18 + TypeScript + Vite webapp
- Implement 4-step agent setup wizard (bot creds → provider → deploy → pairing)
- Add 2-minute countdown timer for bot startup feedback
- Create agent management dashboard with list, restart, and delete
- Backend integration: HMAC-SHA256 initData validation, JWT auth, agent CRUD
- WebSocket real-time provisioning status streaming
- Move bot token validation to backend for security
- Fix Docker restart/start logic with proper error handling
- Configure tenant VPS SSH access (TENANT_VPS_USER=tenant, SSH key path)
- Mobile-first responsive design with bottom tab navigation
- Tab-based SPA: Deploy (wizard) / My Agents (dashboard) / Help

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant