Tenant Manager Development Phases

Overview

Development broken into 6 phases, focusing on backend database and API first as requested. Frontend comes later after core logic is solid.

---

Phase 1: Core Backend & Database

Priority: HIGHEST Duration: 1-2 days Status: In Planning

Goals

Build the foundation: database models, core API endpoints, authentication.

Tasks

Database Layer

• Create SQLAlchemy models matching schema
• User model
• Tenant model
• TenantConfig model
• TenantTheme model
• Deployment model
• AIAnalysis model
• ThemeSuggestion model
• Log model
• PortAllocation model

• Settings model

• Create database initialization script

• Read schema.sql
• Create tables
• Insert default data (ports, settings)

• Create initial superuser

• Database utility functions

• Connection management
• Session handling
• Transaction helpers

API Foundation

• FastAPI application setup
• CORS configuration
• Error handlers
• Logging setup

• Response models

• Authentication system

• JWT token generation
• Login endpoint
• Token validation middleware
• Password hashing (bcrypt)

Tenant CRUD Endpoints

• POST /api/tenants - Create tenant
• Validate input
• Auto-allocate ports if not provided
• Create tenant record
• Create default config

• Return tenant data

• GET /api/tenants - List tenants

• Pagination
• Filtering (status, search)
• Sorting

• Include health status

• GET /api/tenants/{id} - Get tenant

• Include config
• Include theme
• Include health details

• Include latest deployment

• PUT /api/tenants/{id} - Update tenant

• Validate changes
• Update fields

• Log changes

• DELETE /api/tenants/{id} - Delete tenant

• Stop services
• Remove NGINX configs
• Release ports
• Optional: remove files
• Log deletion

Configuration Endpoints

• GET /api/tenants/{id}/config - Get config
• PUT /api/tenants/{id}/config - Update config
• Validate changes
• Regenerate .env if needed
• Log changes

Port Management

• GET /api/ports - List allocations
• GET /api/ports/next-available - Get next free ports
• Port allocation logic
• Find available range
• Mark as allocated
• Release on tenant delete

Settings Management

• GET /api/settings - List settings
• GET /api/settings/{key} - Get setting
• PUT /api/settings/{key} - Update setting
• Encrypt secrets
• Validate types
• Log changes

Deliverables

• ✅ Working database with all tables
• ✅ Full tenant CRUD API
• ✅ Authentication system
• ✅ Configuration management
• ✅ Port allocation system
• ✅ Settings management
• ✅ API documentation updated
• ✅ Postman/curl examples

Testing

• Create test tenant via API
• Update tenant config
• List all tenants
• Delete tenant
• Test authentication
• Test port allocation

---

Phase 2: AI Integration (Claude)

Priority: HIGH Duration: 1 day Status: Not Started

Goals

Implement Claude website analyzer agent for automatic theme generation.

Tasks

Website Analyzer Agent

• Create agents/website_analyzer.py
• Screenshot capture with Playwright
• HTML/CSS fetching
• Claude API integration
• Response parsing

• Theme extraction logic

• Prompt engineering

• Design effective analysis prompt
• Handle various website types
• Extract color palettes
• Generate Tailwind scales

• Include reasoning

• Error handling

• Handle failed screenshots
• Handle API errors
• Timeout handling
• Retry logic

Theme API Endpoints

• POST /api/tenants/{id}/theme/analyze
• Validate URL
• Create AIAnalysis record
• Queue analysis job

• Return analysis ID

• GET /api/tenants/{id}/theme/suggestions

• Check analysis status
• Return suggestions
• Include screenshots

• Format for frontend

• POST /api/tenants/{id}/theme/apply-suggestion

• Validate suggestion ID
• Update tenant theme
• Mark as selected

• Log application

• GET /api/tenants/{id}/theme - Get current theme

• PUT /api/tenants/{id}/theme - Manual theme update

Background Processing

• Async analysis execution
• Don't block API response
• Update status on completion

• Store results in database

• WebSocket notifications (optional)

• Notify on analysis complete
• Real-time progress

Deliverables

• ✅ Working website analyzer agent
• ✅ Theme suggestion generation
• ✅ Theme management API
• ✅ Sample analysis results
• ✅ Documentation with examples

Testing

• Analyze real campaign website
• Verify color extraction
• Test multiple website styles
• Apply suggestion to tenant
• Verify theme updates

---

Phase 3: Deployment Engine

Priority: HIGH Duration: 1-2 days Status: Not Started

Goals

Automate the deployment process from the existing deploy.sh script.

Tasks

Deployment Orchestrator

• Create api/deployment.py
• Port deployment script logic to Python
• Step-by-step execution
• Progress tracking

• Error recovery

• Deployment steps

• Copy core files
• Initialize database
• Create systemd services
• Configure NGINX
• Setup SSL certificates
• Start services

• Verify health

• Progress tracking

• Update deployment status
• Log each step
• Calculate duration
• Store logs

Deployment API Endpoints

• POST /api/tenants/{id}/deploy
• Validate tenant ready
• Create deployment record
• Execute deployment

• Return deployment ID

• GET /api/deployments/{id}

• Return status
• Return current step
• Return progress %

• Return logs

• GET /api/deployments/{id}/logs

• Return full logs
• Support streaming (SSE)
• Real-time updates

Service Control

• POST /api/tenants/{id}/start
• Start systemd services
• Verify started

• Update tenant status

• POST /api/tenants/{id}/stop

• Stop services gracefully

• Update status

• POST /api/tenants/{id}/restart

• Restart services
• Verify health

NGINX Management

• POST /api/nginx/reload - Reload NGINX
• POST /api/nginx/test - Test config
• GET /api/nginx/configs - List configs
• NGINX config generation from templates

Deliverables

• ✅ Automated deployment system
• ✅ Service control endpoints
• ✅ Real-time deployment logs
• ✅ NGINX management
• ✅ Error handling and rollback

Testing

• Deploy test tenant end-to-end
• Test deployment failure recovery
• Start/stop/restart services
• Verify NGINX configuration
• Test SSL setup

---

Phase 4: Frontend (FastHTML)

Priority: MEDIUM Duration: 2-3 days Status: Not Started

Goals

Build user-friendly web interface for all functionality.

Tasks

Application Setup

• FastHTML application structure
• Template system setup
• Static files (CSS, JS)
• Tailwind CSS configuration
• HTMX integration
• Navigation layout

Dashboard Page

• Tenant overview cards
• Status indicators
• Quick stats
• Health badges
• System metrics
• Total tenants
• Active/stopped counts
• Available ports
• Recent deployments list
• Quick action buttons

Tenants Pages

• Tenants List (/tenants)
• Table with all tenants
• Status badges
• Search box
• Filters (status)

• Quick actions (start/stop)

• Tenant Detail (/tenants/{id})

• Tab navigation
• Overview tab (status, URLs, stats)
• Configuration tab
  • Editable form
  • Save button
  • Validation
• Theme tab
  • Color picker
  • Logo upload
  • AI analysis button
  • Suggestion preview
• Logs tab
  • Deployment logs
  • Service logs
  • Error logs
• Remote tab
  • Tenant stats
  • Person count
  • Actions

Deploy Wizard

• Multi-step form
• Step 1: Basic info
  • Name, slug, domain
  • Port allocation
  • GitHub repo
• Step 2: Configuration
  • Email, admin settings
  • Custom env vars
• Step 3: Theme
  • Website analysis
  • AI suggestions
  • Logo upload
  • Color picker
• Step 4: Review
  • Summary of all settings
  • Edit links
• Step 5: Deploy
  • Progress bar
  • Real-time logs
  • Completion message

Theme Editor

• Color pickers for all colors
• Live preview
• Logo upload with preview
• AI analysis UI
• URL input
• Analyze button
• Loading state
• Suggestion cards
• Select button per suggestion
• Preview before applying

Settings Page

• Settings form
• API key input (masked)
• System paths
• Default values
• Save button

Logs Viewer

• Filterable log table
• Real-time updates
• Export button
• Search functionality

Deliverables

• ✅ Complete web interface
• ✅ Responsive design
• ✅ HTMX interactions
• ✅ Form validation
• ✅ Real-time updates

Testing

• Test all forms
• Test deploy wizard flow
• Test AI analysis UI
• Test theme editor
• Mobile responsiveness

---

Phase 5: Advanced Features

Priority: MEDIUM Duration: 1-2 days Status: Not Started

Goals

Add health monitoring, remote APIs, and advanced features.

Tasks

Health Monitoring

• Health check system
• Frontend HTTP check
• Backend HTTP check
• Database size check
• Service status check
• Scheduled health checks
• Background task
• Store results
• Update tenant status
• Health API endpoints
• GET /api/tenants/{id}/health
• POST /api/tenants/{id}/health-check
• Health dashboard widget

Remote Tenant API Integration

• Connect to tenant APIs
• Authentication
• Stats retrieval
• Action execution
• Remote endpoints
• GET /api/tenants/{id}/remote/stats
• GET /api/tenants/{id}/remote/persons/count
• POST /api/tenants/{id}/remote/backup
• Remote stats on tenant detail page

Backup System

• Automated backups
• Schedule configuration
• Database backup
• File backup
• Retention policy
• Manual backup trigger
• Restore functionality

Audit & Logging

• Comprehensive logging
• API requests
• Deployments
• Configuration changes
• User actions
• Log viewing UI
• Log export

Deliverables

• ✅ Health monitoring system
• ✅ Remote API integration
• ✅ Backup automation
• ✅ Complete audit trail

---

Phase 6: Production Ready

Priority: HIGH Duration: 1 day Status: Not Started

Goals

Prepare for production deployment and ongoing use.

Tasks

Error Handling

• Comprehensive error handling
• User-friendly error messages
• Error logging
• Error recovery

Testing

• Unit tests (key functions)
• Integration tests (API endpoints)
• End-to-end tests (deployment flow)
• Load testing

Documentation

• Complete README
• API documentation
• User guide
• Troubleshooting guide
• Architecture documentation

Deployment

• systemd services
• tenantmgr-api.service
• tenantmgr-frontend.service
• NGINX configuration
• manager.nominate.ai
• SSL setup
• Port allocation (32200/32201)
• Environment configuration
• Startup scripts

Security

• Security audit
• Input validation
• SQL injection prevention
• XSS prevention
• CSRF protection
• Secret encryption
• Rate limiting

Monitoring

• Log aggregation
• Error alerting
• Performance monitoring
• Uptime monitoring

Deliverables

• ✅ Production-ready application
• ✅ Complete documentation
• ✅ Deployed and running
• ✅ Monitoring in place

---

Future Phases

Phase 7: List Loader Agent (Future)

• AI-powered contact list parsing
• Intelligent field mapping
• Import preview and validation
• Automated transformations

Phase 8: Advanced NGINX (Future)

• Centralized NGINX configuration
• Wildcard SSL certificates
• Automatic DNS management
• Zero-downtime deployments

Phase 9: Scaling (Future)

• Multi-server support
• Load balancing
• Database clustering
• Tenant migration tools

Phase 10: White-Label (Future)

• Reseller support
• Billing integration
• Custom domain management
• Partner API

---

Development Workflow

For Each Phase:

1. Planning
2. Review tasks
3. Estimate time

4. Identify dependencies

5. Development

6. Implement tasks sequentially
7. Test as you go

8. Update documentation

9. Testing

10. Unit tests
11. Integration tests

12. Manual testing

13. Documentation

14. Update API docs
15. Update README

16. Add examples

17. Review

18. Code review
19. Test coverage check

20. Documentation review

21. Deploy

22. Merge to main
23. Tag release
24. Deploy to production

---

Current Status

Phase: Planning/Design Started: 2025-11-21 Current Focus: Database schema and API design Next Steps: Begin Phase 1 implementation

Progress: - [x] Architecture design - [x] Database schema - [x] API specification - [ ] Implementation start

Ready to build! 🚀