Skip to content

INTEGRATION_PLAN.md

Latest commit

 

History

History
347 lines (280 loc) · 11 KB

INTEGRATION_PLAN.md

File metadata and controls

347 lines (280 loc) · 11 KB
Raw

🔄 Integration Plan: Design System + OpenRouter Cost Tracking

Date: 2025-11-13 Branches:

  • main - Current work with OpenRouter tracking
  • claude/frontend-design-enhancement-016NkeAGFfHoXw6bE9agVgMs - New theme system

📊 Current Situation

On Main Branch (Our Changes)

  • ✅ Complete OpenRouter API cost tracking system
  • ✅ Backend API endpoints (/api/v1/usage/*)
  • ✅ Database models (ApiUsage)
  • ✅ Frontend usage.html page (standalone, not using design system)
  • ✅ 70+ tests (all passing)
  • ✅ Configuration & pricing setup

On Design Branch (New System)

  • 🎨 Complete theme system (8 themes)
  • 🎨 Shared components (base.html, nav.html, footer.html, theme-switcher.html)
  • 🎨 Jinja2 template inheritance
  • 🎨 New pages (dashboard.html, samples-v2.html)
  • 🎨 JavaScript utilities (theme.js, components.js)
  • 🎨 CSS theme overrides

🎯 Integration Goals

  1. ✅ Merge design system into main
  2. ✅ Convert usage.html to use new template system
  3. ✅ Add "Usage & Costs" to navigation
  4. ✅ Ensure all OpenRouter functionality works with themes
  5. ✅ Keep all 70+ tests passing
  6. ✅ Maintain backward compatibility with existing pages

📝 Integration Steps

Phase 1: Merge Design System

# Checkout design branch changes without switching
git checkout claude/frontend-design-enhancement-016NkeAGFfHoXw6bE9agVgMs -- frontend/

# This will bring in:
# - frontend/components/ (base.html, nav.html, footer.html, theme-switcher.html)
# - frontend/static/css/themes.css
# - frontend/static/js/theme.js
# - frontend/static/js/components.js
# - frontend/THEME_SYSTEM_GUIDE.md
# - frontend/QUICK_START.md

Phase 2: Backend Template Support

The backend is already using Jinja2 templates, so we need to ensure it can find the new components:

File: backend/app/main.py

# Templates path should include frontend folder
templates = Jinja2Templates(directory="frontend")

Phase 3: Convert Usage Page

File: frontend/pages/usage.html

Current structure (standalone):

<!DOCTYPE html>
<html>
<head>
    <!-- All CDN imports -->
    <!-- All scripts -->
</head>
<body>
    <!-- Hardcoded navigation -->
    <!-- Content -->
</body>
</html>

New structure (template inheritance):

{% extends "components/base.html" %}

{% block title %}API Usage & Costs - SP404MK2{% endblock %}

{% block head %}
    <!-- Chart.js for usage charts -->
    <script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
{% endblock %}

{% block content %}
    <!-- All our usage dashboard content -->
{% endblock %}

{% block scripts %}
    <!-- Page-specific Alpine.js components -->
{% endblock %}

Phase 4: Update Navigation

File: frontend/components/nav.html

Add usage link after Batch:

<li>
    <a href="/pages/usage.html"
       hx-boost="true"
       class="{% if request.url.path == '/pages/usage.html' %}active{% endif %}">
        <svg class="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 7h6m0 10v-3m-3 3h.01M9 17h.01M9 14h.01M12 14h.01M15 11h.01M12 11h.01M9 11h.01M7 21h10a2 2 0 002-2V5a2 2 0 00-2-2H7a2 2 0 00-2 2v14a2 2 0 002 2z"/>
        </svg>
        Usage
    </a>
</li>

Phase 5: Update Other Pages

Convert existing pages to use design system:

  • frontend/pages/samples.html → Use new template
  • frontend/pages/kits.html → Use new template
  • frontend/pages/batch.html → Use new template

Phase 6: File Organization

sp404mk2-sample-agent/
├── backend/
│   ├── app/
│   │   ├── api/v1/endpoints/
│   │   │   └── usage.py                    ✅ Already created
│   │   ├── models/
│   │   │   └── api_usage.py                ✅ Already created
│   │   ├── services/
│   │   │   └── usage_tracking_service.py   ✅ Already created
│   │   └── main.py                         📝 Update template path
│   ├── tests/
│   │   ├── unit/
│   │   │   └── test_usage_tracking_service.py  ✅ Already created
│   │   └── integration/
│   │       └── test_usage_endpoints.py         ✅ Already created
│   └── alembic/versions/
│       └── xxx_add_api_usage.py            📝 Create migration
├── frontend/
│   ├── components/                         🆕 From design branch
│   │   ├── base.html
│   │   ├── nav.html                        📝 Add usage link
│   │   ├── footer.html
│   │   └── theme-switcher.html
│   ├── pages/
│   │   ├── usage.html                      📝 Convert to template
│   │   ├── samples.html                    📝 Optional: convert
│   │   ├── kits.html                       📝 Optional: convert
│   │   └── batch.html                      📝 Optional: convert
│   ├── static/
│   │   ├── css/
│   │   │   └── themes.css                  🆕 From design branch
│   │   └── js/
│   │       ├── theme.js                    🆕 From design branch
│   │       └── components.js               🆕 From design branch
│   ├── tests/e2e/
│   │   └── test-usage-page.spec.js         ✅ Already created
│   ├── THEME_SYSTEM_GUIDE.md               🆕 From design branch
│   └── QUICK_START.md                      🆕 From design branch
└── docs/
    ├── PHASE6_TESTING_COMPLETE.md          ✅ Already created
    └── INTEGRATION_PLAN.md                 📝 This file

🔄 Migration Checklist

Critical (Must Do Now)

  • Merge design system files from branch
  • Convert usage.html to use base template
  • Add usage link to nav.html
  • Test usage page loads with all themes
  • Verify all backend API endpoints still work
  • Run unit tests to ensure nothing broke

Important (Should Do Soon)

  • Create database migration for api_usage table
  • Convert samples.html to use new template
  • Convert kits.html to use new template
  • Convert batch.html to use new template
  • Update E2E tests for new navigation structure

Optional (Can Do Later)

  • Add theme preferences to user model
  • Add usage stats to dashboard.html
  • Create admin view for all users' usage
  • Add real-time cost updates via WebSocket

⚠️ Potential Issues & Solutions

Issue 1: Template Path

Problem: Backend may not find Jinja2 templates in frontend/components/ Solution: Update backend/app/main.py template directory path

Issue 2: Static Files

Problem: New CSS/JS files may not load Solution: Verify static file mounting in FastAPI app

Issue 3: Navigation Active State

Problem: {% if request.url.path == '/pages/usage.html' %}active{% endif %} may not work Solution: Ensure FastAPI passes request context to templates

Issue 4: Chart.js Conflicts

Problem: Multiple Chart.js instances on same page Solution: Add Chart.js to base.html head or only in usage page block

Issue 5: Test Failures

Problem: E2E tests expect old navigation structure Solution: Update test selectors to match new navigation

🧪 Testing Strategy

1. Visual Testing

  • Load each page in browser
  • Test all 8 themes on usage page
  • Check navigation highlighting works
  • Verify mobile responsive layout
  • Test theme switcher persists preference

2. Functional Testing

  • Upload sample → verify usage tracked
  • Check usage dashboard displays data
  • Test CSV export downloads
  • Verify budget alerts show correctly
  • Test all API endpoints with curl/Postman

3. Automated Testing

# Unit tests (should all pass)
pytest backend/tests/unit/test_usage_tracking_service.py -v

# Integration tests
pytest backend/tests/integration/test_usage_endpoints.py -v

# E2E tests (may need selector updates)
npx playwright test test-usage-page

📦 Commit Strategy

Commit 1: Merge Design System

git checkout claude/frontend-design-enhancement-016NkeAGFfHoXw6bE9agVgMs -- frontend/components frontend/static/css/themes.css frontend/static/js/theme.js frontend/static/js/components.js frontend/THEME_SYSTEM_GUIDE.md frontend/QUICK_START.md

git add frontend/components frontend/static frontend/THEME_SYSTEM_GUIDE.md frontend/QUICK_START.md
git commit -m "feat: Add theme system with 8 curated themes and shared components

- 8 DaisyUI themes (light, dark, synthwave, dracula, cyberpunk, business, lofi, forest)
- Jinja2 template inheritance (base.html, nav.html, footer.html)
- Theme persistence in localStorage
- Responsive navigation with mobile menu
- SP-404MK2 custom colors

Co-authored-by: Design System Branch"

Commit 2: Integrate Usage Page

git add frontend/pages/usage.html frontend/components/nav.html
git commit -m "feat: Integrate OpenRouter usage tracking with theme system

- Convert usage.html to extend base template
- Add 'Usage & Costs' to navigation
- Support all 8 themes
- Maintain Chart.js functionality
- Update navigation active states"

Commit 3: Add OpenRouter Backend

git add backend/app/api/v1/endpoints/usage.py backend/app/models/api_usage.py backend/app/services/usage_tracking_service.py backend/app/core/config.py
git commit -m "feat: Add OpenRouter API cost tracking backend

- Complete usage tracking service
- 6 API endpoints (summary, daily, budget, recent, export, public)
- Model pricing configuration
- Budget limit enforcement
- CSV export functionality"

Commit 4: Add Tests

git add backend/tests/unit/test_usage_tracking_service.py backend/tests/integration/test_usage_endpoints.py frontend/tests/e2e/test-usage-page.spec.js
git commit -m "test: Add comprehensive test suite for cost tracking

- 27 unit tests for UsageTrackingService
- 30+ integration tests for API endpoints
- 15+ E2E tests for usage dashboard
- All tests passing"

Commit 5: Documentation

git add PHASE6_TESTING_COMPLETE.md INTEGRATION_PLAN.md
git commit -m "docs: Add testing and integration documentation

- Complete Phase 6 testing summary
- Integration plan for design system merge
- Testing procedures and results
- File organization guide"

✅ Success Criteria

  1. ✅ All pages use new theme system
  2. ✅ Usage page accessible from navigation
  3. ✅ All 8 themes work on usage dashboard
  4. ✅ Charts render correctly in all themes
  5. ✅ All 70+ tests still passing
  6. ✅ No console errors in browser
  7. ✅ Mobile layout works correctly
  8. ✅ Theme preference persists across page loads
  9. ✅ All API endpoints returning correct data
  10. ✅ CSV export working with correct data

🚀 Deployment Notes

After successful integration:

  1. Update CLAUDE.md with new design system info
  2. Create PR for review
  3. Merge to main after tests pass
  4. Deploy to production
  5. Monitor for any issues
  6. Update user documentation

Integration ready to begin!