Agent Skills: Frontend-Backend Integration Map

Purpose

Analyzes and maps frontend API calls to backend endpoints to detect gaps, unused routes, and type mismatches.

When to Use

• When validating API integration coverage.
• When identifying missing or unused backend endpoints.
• When tracing complete data flows from frontend to database/Genkit.

Process

1. Scan frontend API services:

   • Read all files in frontend/src/api/*.ts
   • Extract API call patterns:
     • Function names (e.g., generateKscResponses)
     • HTTP methods (GET, POST, PUT, DELETE)
     • URL paths (e.g., /api/v1/ksc/generate)
     • Request/response TypeScript interfaces
   • Build frontend API inventory

2. Scan backend endpoints:

   • Read all files in backend/app/api/endpoints/*.py
   • Extract route definitions:
     • Route decorators (@router.post, @router.get)
     • URL paths
     • Request/response Pydantic models
     • Function names
   • Build backend endpoint inventory

3. Perform integration analysis:

   • Match frontend calls to backend endpoints
   • Identify ✅ MAPPED integrations (frontend ↔ backend)
   • Identify ❌ MISSING BACKEND endpoints (frontend calls with no backend)
   • Identify ❌ UNUSED BACKEND endpoints (backend routes with no frontend)
   • Identify ⚠️ TYPE MISMATCHES (field name inconsistencies, type differences)

4. Analyze Genkit flow integration:

   • Read backend/app/genkit_flows/*.py
   • Map backend endpoints to Genkit flows
   • Track complete data flow: Component → Service → Endpoint → Flow

5. [OPTIONAL] Trace database operations:

   • Read backend/app/core/firestore_cache.py and Firestore collection usage
   • Map backend endpoints to Firestore collections they read/write
   • Document data persistence flow: Endpoint → Collection → Cache strategy
   • Identify missing database operations (endpoints without data persistence)
   • Only included when --include-database flag is used

6. [OPTIONAL] Map design token usage:

   • Read frontend/src/theme/tokens.json and CSS token definitions
   • Scan components in frontend/src/components/**/*.tsx
   • Identify which components use design tokens vs hardcoded values
   • Document token application flow: Token → CSS Variable → Component
   • Flag components not using the M3 token system
   • Only included when --include-design-tokens flag is used

7. Generate mapping report:

   • Create docs/INTEGRATION_MAP.md with:
     • Complete integration matrix
     • Missing endpoint list with priority
     • Unused endpoint list for cleanup
     • Type mismatch warnings
     • Integration health score
     • Recommendations for fixes
     • [OPTIONAL] Database persistence flow (with --include-database)
     • [OPTIONAL] Design token coverage report (with --include-design-tokens)

8. Generate visual diagrams:

   • Create Mermaid diagram showing:
     • Frontend components → API services
     • API services → Backend endpoints
     • Backend endpoints → Genkit flows
     • Missing connections highlighted
     • [OPTIONAL] Add Firestore collection connections (with --include-database)
     • [OPTIONAL] Add design token flow (with --include-design-tokens)

9. Report findings:

   • Display summary statistics
   • Show critical issues (missing required endpoints)
   • List improvement opportunities
   • Provide action items

Analysis Output Structure

Integration Map Report

# Frontend-Backend Integration Map

Generated: 2025-01-06T12:00:00Z

## Summary Statistics

- Total Frontend API Functions: 45
- Total Backend Endpoints: 38
- Mapped Integrations: 35 (✅ 77.8%)
- Missing Backend Endpoints: 10 (❌ 22.2%)
- Unused Backend Endpoints: 3 (⚠️ 6.7%)
- Type Mismatches: 5 (⚠️ 11.1%)

## Integration Health Score: 78/100

### ✅ MAPPED INTEGRATIONS (35)

| Frontend Function        | HTTP Method | Backend Endpoint             | Genkit Flow           |
| ------------------------ | ----------- | ---------------------------- | --------------------- |
| `generateKscResponses()` | POST        | `/api/v1/ksc/generate`       | `generateKscResponse` |
| `getAtsScore()`          | POST        | `/api/v1/analysis/ats-score` | `atsScoring`          |
| ...                      |

### ❌ MISSING BACKEND ENDPOINTS (10)

| Frontend Function    | Expected Endpoint            | Priority | Impact         |
| -------------------- | ---------------------------- | -------- | -------------- |
| `sendWelcomeEmail()` | POST `/api/v1/email/welcome` | HIGH     | Broken feature |
| `getUserAnalytics()` | GET `/api/v1/analytics/user` | MEDIUM   | Missing data   |
| ...                  |

### ❌ UNUSED BACKEND ENDPOINTS (3)

| Endpoint                           | Last Used | Recommendation       |
| ---------------------------------- | --------- | -------------------- |
| GET `/api/v1/admin/legacy-reports` | Never     | Consider deprecating |
| ...                                |

### ⚠️ TYPE MISMATCHES (5)

| Integration                     | Issue                                                                              | Fix                |
| ------------------------------- | ---------------------------------------------------------------------------------- | ------------------ |
| `analysisService.getAtsScore()` | Frontend uses `resumeText` (camelCase), backend expects `resume_text` (snake_case) | Standardize casing |
| ...                             |

Visual Diagram

The skill generates a Mermaid flowchart:

graph LR
    A[KscGeneratorPage] -->|calls| B[aiServices.generateKscResponses]
    B -->|POST /api/v1/ksc/generate| C[ksc/generate endpoint]
    C -->|invokes| D[generateKscResponse flow]
    D -->|caches via| E[Firestore Cache]

    F[AnalysisPage] -->|calls| G[analysisService.getAtsScore]
    G -.->|MISSING| H[/api/v1/analysis/ats-score]

    style H fill:#ff6b6b,stroke:#ff0000

Template Variables

• {{FRONTEND_SERVICES}}: List of frontend API service files
• {{BACKEND_ENDPOINTS}}: List of backend endpoint files
• {{MAPPED_COUNT}}: Number of mapped integrations
• {{MISSING_COUNT}}: Number of missing backend endpoints
• {{UNUSED_COUNT}}: Number of unused backend endpoints
• {{MISMATCH_COUNT}}: Number of type mismatches
• {{HEALTH_SCORE}}: Overall integration health percentage
• {{DIAGRAM}}: Mermaid diagram code

Usage Tips

• Run this skill after significant frontend or backend changes
• Use before major releases to catch integration issues
• Generate integration map for new team members
• Track integration health over time
• Prioritize missing endpoints by usage frequency
• Use --include-database to trace complete data flows to Firestore
• Use --include-design-tokens to audit component token compliance
• Use both flags for comprehensive fullstack documentation