Skip to main content

Dashboard 2.0 POC - Deployment Guide

Status: Production Ready
Version: 4.0.0
Last Updated: 2025-11-28

Quick Start (5 Minutes)​

Follow these 4 simple steps to deploy the Dashboard 2.0 POC:

Step 1: Install Git Hooks ✅​

Enable automatic commit-task linking with our installation script:

./install-hooks.sh

What it does:

  • Installs a post-commit git hook
  • Automatically detects task IDs in commit messages (e.g., TASK-DASH-1001)
  • Links commits to tasks in the dashboard
  • Calls AI analysis API if backend is running

Expected output:

🔧 Installing Dashboard 2.0 Git Hooks...
📁 Git repository: /path/to/repo
📁 Hooks directory: /path/to/repo/.git/hooks
📝 Creating post-commit hook...
✅ Post-commit hook installed successfully
✅ Hook is executable
🎉 Git hooks installation complete!

Step 2: Start the Backend API 🚀​

Launch the Flask backend server with hybrid AI + TF-IDF linking:

cd backend
source venv/bin/activate
python3 api_v2.py

Expected output:

 * Running on http://127.0.0.1:5001
 * Debug mode: on

What's running:

  • RESTful API (11 endpoints)
  • Hybrid linking system (Claude Sonnet 4.5 + TF-IDF)
  • SQLite database with enhanced task metadata
  • Health check endpoint: http://localhost:5001/health

API Endpoints:

  • GET /api/v2/tasks - List all tasks
  • POST /api/v2/tasks - Create new task
  • GET /api/v2/commits - List all commits
  • POST /api/v2/commits - Ingest git commit
  • POST /api/v2/commits/analyze - AI-powered commit analysis
  • GET /api/v2/links - Get task-commit links
  • POST /api/v2/links/suggest - Get AI link suggestions
  • ...and 4 more endpoints

Step 3: Start the Frontend Dashboard 🎨​

Launch the GPS navigation dashboard UI:

# In a new terminal window
cd frontend
python3 -m http.server 8082

Expected output:

Serving HTTP on 0.0.0.0 port 8082 (http://0.0.0.0:8082/) ...

Access dashboard: Open your browser to: http://localhost:8082

What you'll see:

  • 🧭 Where Am I? - Current project status
  • 🚧 What's Blocking Me? - Blockers and dependencies
  • 📊 What's Happening? - Recent commits and activity
  • ✅ What Should I Do Next? - Upcoming tasks and priorities

Step 4: Test End-to-End Linking 🧪​

Verify the hybrid AI + TF-IDF linking system works:

4a. Make a test commit with task ID​

# Make a small change (e.g., update README)
echo "# Test" >> README.md
git add README.md
git commit -m "docs: Update README for testing TASK-DASH-1001"

Expected git hook output:

🔗 Dashboard 2.0: Analyzing commit for task links...
✅ Found task references in commit message:
   → TASK-DASH-1001

💡 Tip: Visit dashboard to see linked commits
   http://localhost:8082

🤖 Requesting AI analysis...
✅ AI analysis complete
   → Found 1 suggested task link(s)
   View details at: http://localhost:8082

4b. Check dashboard for linked commit​

  1. Visit http://localhost:8082
  2. Look for "TASK-DASH-1001: Database Schema & Migration System"
  3. Verify the commit appears in the "Recent Activity" section
  4. Click on the task to see commit details

4c. Test AI semantic linking (no explicit task ID)​

# Commit without mentioning task ID directly
echo "# Enhancement" >> README.md
git add README.md
git commit -m "feat: Improve database migration performance with indexes"

Expected behavior:

  • Git hook shows: "ℹ️ No task IDs found in commit message"
  • AI analysis should suggest linking to TASK-DASH-1001 (database-related)
  • Dashboard shows suggested link with confidence score

Verification Checklist ✅​

After completing Steps 1-4, verify everything works:

  • Git hooks installed: Run ./install-hooks.sh successfully
  • Backend running: Visit http://localhost:5001/health returns {"status": "healthy"}
  • Frontend accessible: http://localhost:8082 loads the dashboard
  • Database populated: Dashboard shows 8 tasks (DASH-1001 through DASH-1008)
  • Explicit linking works: Commits with TASK-DASH-XXXX link correctly
  • AI suggestions work: Commits without task IDs get AI-suggested links
  • Dashboard updates: Recent commits appear in "What's Happening?" quadrant
  • Filters work: Project filter modal shows/hides tasks correctly

Troubleshooting 🔧​

Issue: Git hooks not executing​

Symptom: No output after git commit

Solution:

# Check hook exists and is executable
ls -la .git/hooks/post-commit

# If not executable:
chmod +x .git/hooks/post-commit

# If missing, reinstall:
./install-hooks.sh

Issue: Backend API not starting​

Symptom: ModuleNotFoundError or connection refused

Solution:

# Ensure virtual environment is activated
cd backend
source venv/bin/activate

# Verify dependencies installed
pip list | grep -E "(flask|anthropic|scikit)"

# If missing:
pip install -r requirements.txt

# Check correct API file:
python3 api_v2.py  # NOT api.py (that's v1)

Issue: Frontend shows "Failed to fetch"​

Symptom: Dashboard loads but shows error messages

Solution:

# 1. Verify backend is running
curl http://localhost:5001/health

# 2. Check CORS headers (should allow localhost:8082)
curl -H "Origin: http://localhost:8082" \
     -H "Access-Control-Request-Method: GET" \
     -X OPTIONS \
     http://localhost:5001/api/v2/tasks -v

# 3. Check backend logs for errors
# (should be visible in terminal running api_v2.py)

Issue: AI linking not working​

Symptom: "Using TF-IDF fallback" message every time

Solution:

# 1. Check Anthropic API key is set
echo $ANTHROPIC_API_KEY

# If empty:
export ANTHROPIC_API_KEY="your-api-key-here"

# Or create .env file:
echo "ANTHROPIC_API_KEY=your-key" > backend/.env

# 2. Verify API key has access to Claude Sonnet 4.5
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4-5-20250929","max_tokens":10,"messages":[{"role":"user","content":"Hi"}]}'

# 3. Check rate limits (429 errors in backend logs)
# Wait a few minutes if rate limited

Issue: Database errors​

Symptom: no such column: task_id or similar

Solution:

# Re-apply migration
cd backend
sqlite3 ../data/dashboard.db < migrations/001_add_enhanced_task_fields.sql

# Verify columns exist:
sqlite3 ../data/dashboard.db "PRAGMA table_info(tasks);"

# Should show: task_id, complexity_hours, time_estimate, etc.

Advanced Configuration ⚙️​

Configure AI Model​

Edit backend/services/ai_linker.py:

# Change model version
self.model = "claude-sonnet-4-5-20250929"  # Latest

# Adjust confidence threshold
self.min_confidence = 0.3  # Default (0.0-1.0)

# Modify hybrid weighting
ai_weight = 0.7   # 70% AI
tfidf_weight = 0.3  # 30% TF-IDF

Configure Dashboard Refresh Rate​

Edit frontend/index.html:

// Auto-refresh every 30 seconds
setInterval(() => {
    loadTasks();
    loadRecentCommits();
}, 30000);  // Change to desired milliseconds

Add More Projects​

Edit .coditect/project.yml or create new tasklist.md files for additional projects.

Production Deployment Checklist 🚀​

Ready for production? Complete these steps:

  • Security: Set DEBUG=False in backend/api_v2.py
  • Database: Migrate to PostgreSQL/MySQL for production scale
  • API Keys: Use secrets management (not .env files)
  • CORS: Restrict CORS to production domain (not *)
  • HTTPS: Enable SSL/TLS certificates
  • Monitoring: Setup logging, error tracking (Sentry, etc.)
  • Backup: Automated database backups
  • Load Testing: Verify performance under load
  • Documentation: Update URLs in project-plan.md

Support & Maintenance 📞​

Logs​

  • Backend: Terminal output from api_v2.py
  • Frontend: Browser console (F12 → Console)
  • Git Hooks: Terminal output after git commit

Performance​

  • API Response Time: < 50ms (target: < 200ms) ✅
  • AI Analysis Time: ~1-2 seconds per commit
  • TF-IDF Analysis Time: ~100-200ms per commit
  • Database Query Time: < 50ms (target: < 100ms) ✅

Database Maintenance​

# Vacuum database (reclaim space)
sqlite3 data/dashboard.db "VACUUM;"

# Analyze for query optimization
sqlite3 data/dashboard.db "ANALYZE;"

# Backup database
cp data/dashboard.db data/dashboard_backup_$(date +%Y%m%d).db

What's Next? 🎯​

Completed in Phase 1 ✅​

  • ✅ Database schema with CODITECT standards
  • ✅ Backend API v2.0 (11/11 tests passing)
  • ✅ Hybrid AI + TF-IDF linking
  • ✅ GPS navigation dashboard
  • ✅ Git hooks automation
  • ✅ Complete documentation

Future Enhancements (Optional)​

  • Multi-repository support
  • Real-time WebSocket updates
  • User authentication & authorization
  • Team collaboration features
  • Export to CSV/JSON/PDF
  • Mobile-optimized view
  • GitHub/GitLab API integration
  • Automated sprint planning
  • Predictive analytics

Last Updated: 2025-11-28
Version: 4.0.0
Status: Production Ready
Support: Hal Casteel (Project Lead)