StarPunk/docs/design/hotfix-v1.1.1-rc2-route-conflict.md

Hotfix Design: v1.1.1-rc.2 Route Conflict Resolution

Problem Summary

Production deployment of v1.1.1-rc.1 causes 500 error at /admin/dashboard due to:

1. Route naming conflict between two dashboard functions
2. Missing starpunk.monitoring module causing ImportError

Root Cause Analysis

Primary Issue: Route Conflict

# Line 26: Original dashboard
@bp.route("/")  # Registered as "admin.dashboard"
def dashboard():  # Function name creates endpoint "admin.dashboard"
    # Shows notes list

# Line 218: Metrics dashboard
@bp.route("/dashboard")  # CONFLICT: Also accessible at /admin/dashboard
def metrics_dashboard():  # Function name creates endpoint "admin.metrics_dashboard"
    from starpunk.monitoring import get_metrics_stats  # FAILS: Module doesn't exist

Secondary Issue: Missing Module

The metrics dashboard attempts to import starpunk.monitoring which doesn't exist in production, causing immediate ImportError on route access.

Solution Design

Minimal Code Changes

1. Route Path Change (admin.py)

Line 218 - Change route decorator:

# FROM:
@bp.route("/dashboard")

# TO:
@bp.route("/metrics-dashboard")

This single character change resolves the route conflict while maintaining all other functionality.

2. Defensive Import Pattern (admin.py)

Lines 239-250 - Add graceful degradation:

def metrics_dashboard():
    """Metrics visualization dashboard (Phase 3)"""
    # Defensive imports with fallback
    try:
        from starpunk.database.pool import get_pool_stats
        from starpunk.monitoring import get_metrics_stats
        monitoring_available = True
    except ImportError:
        monitoring_available = False
        get_pool_stats = lambda: {"error": "Pool stats not available"}
        get_metrics_stats = lambda: {"error": "Monitoring not implemented"}

    # Continue with safe execution...

URL Structure After Fix

Path	Function	Purpose	Status
/admin/	dashboard()	Notes list	Working
/admin/metrics-dashboard	metrics_dashboard()	Metrics viz	Fixed
/admin/metrics	metrics()	JSON API	Working
/admin/health	health_diagnostics()	Health check	Working

Redirect Behavior

All existing redirects using url_for("admin.dashboard") will continue to work:

• They resolve to the dashboard() function
• Users land on the notes list at /admin/
• No code changes needed in 8+ redirect locations

Navigation Updates

The template at /templates/admin/base.html is already correct:

<a href="{{ url_for('admin.dashboard') }}">Dashboard</a>  <!-- Goes to /admin/ -->
<a href="{{ url_for('admin.metrics_dashboard') }}">Metrics</a>  <!-- Goes to /admin/metrics-dashboard -->

Implementation Steps

Step 1: Create Hotfix Branch

git checkout -b hotfix/v1.1.1-rc2-route-conflict

Step 2: Apply Code Changes

1. Edit /starpunk/routes/admin.py:
   • Change line 218 route decorator
   • Add try/except around monitoring imports (lines 239-250)
   • Add try/except around pool stats import (line 284)

Step 3: Local Testing

# Test without monitoring module (production scenario)
uv run python -m pytest tests/test_admin_routes.py
uv run flask run

# Verify:
# 1. /admin/ shows notes
# 2. /admin/metrics-dashboard doesn't 500
# 3. All CRUD operations work

Step 4: Update Version

Edit /starpunk/__init__.py:

__version__ = "1.1.1-rc.2"

Step 5: Document in CHANGELOG

Add to /CHANGELOG.md:

## [1.1.1-rc.2] - 2025-11-25

### Fixed
- Critical: Resolved route conflict causing 500 error on /admin/dashboard
- Added defensive imports for missing monitoring module
- Renamed metrics dashboard route to /admin/metrics-dashboard for clarity

Testing Checklist

Functional Tests

• /admin/ displays notes dashboard
• /admin/metrics-dashboard loads without 500 error
• Create note redirects to /admin/
• Edit note redirects to /admin/
• Delete note redirects to /admin/
• Navigation links work correctly
• /admin/metrics JSON endpoint works
• /admin/health diagnostic endpoint works

Error Handling Tests

• Metrics dashboard shows graceful message when monitoring unavailable
• No Python tracebacks exposed to users
• Flash messages display appropriately

Regression Tests

• IndieAuth login flow works
• Note CRUD operations unchanged
• RSS feed generation works
• Micropub endpoint functional

Rollback Plan

If issues discovered after deployment:

1. Revert to v1.1.1-rc.1
2. Users directed to /admin/ instead of /admin/dashboard
3. Metrics dashboard temporarily disabled

Success Criteria

1. No 500 Errors: All admin routes respond with 200/300 status codes
2. Backward Compatible: Existing functionality unchanged
3. Clear Navigation: Users can access both dashboards
4. Graceful Degradation: Missing modules handled elegantly

Long-term Recommendations

For v1.2.0

1. Implement starpunk.monitoring module properly
2. Add comprehensive metrics collection
3. Consider dashboard consolidation

For v2.0.0

1. Restructure admin area with sub-blueprints
2. Implement consistent URL patterns
3. Add dashboard customization options

Risk Assessment

Risk	Likelihood	Impact	Mitigation
Route still conflicts	Low	High	Tested locally first
Template breaks	Low	Medium	Template already correct
Monitoring import fails differently	Low	Low	Defensive imports added
Performance impact	Very Low	Low	Minimal code change

Approval Requirements

This hotfix requires:

1. Code review of changes
2. Local testing confirmation
3. Staging deployment (if available)
4. Production deployment authorization

Contact

• Architect: StarPunk Architect
• Issue: Production 500 error on /admin/dashboard
• Priority: CRITICAL
• Timeline: Immediate deployment required