# Frontend Gaps vs Architecture Implementation Guide

This document lists **what is not yet implemented** in the Tower Paints frontend relative to the backend architecture described in `IMPLEMENTATION_SUMMARY.md`, and **where** to implement each item.

---

## 1. API path alignment

The architecture doc uses routes under **`/api/analytics/...`** with a specific structure (e.g. `performance/monthly/{partnerId}/{year}/{month}`). The frontend currently uses:

- **analyticsApi** baseUrl: `/analytics` → e.g. `GET /api/analytics/monthly-performance`, `GET /api/analytics/compliance-heatmap`, `GET /api/analytics/low-stock-alerts`, `POST /api/analytics/weekly-report`
- **adminApi** baseUrl: `/admin` → e.g. `GET /admin/compliance`, `GET /admin/inventory/low-stock`, `GET /admin/inventory/dead-stock`

**Action:** Confirm with backend whether routes match. If the backend implements the doc’s paths (e.g. `GET /api/analytics/performance/monthly/{partnerId}/{year}/{month}`), add corresponding endpoints in the frontend and point existing (or new) components to them.

**Where:** `src/store/api/analyticsApi.js`, `src/store/api/adminApi.js`, `src/services/analyticsService.js`, `src/services/adminService.js`

---

## 2. Performance scorecard (doc)

| Doc endpoint | Frontend status | Where to implement |
|--------------|-----------------|--------------------|
| `GET /api/analytics/performance/monthly/{partnerId}/{year}/{month}` | Frontend has `getMonthlyPerformance` with no path params | `analyticsApi.js`: add query that accepts `partnerId`, `year`, `month` and calls the doc path (or current backend path). Use in **PerformanceScorecard** and partner dashboard. |
| `GET /api/analytics/performance/yearly/{partnerId}/{year}` | Not implemented | `analyticsApi.js`: new endpoint. **PerformanceScorecard.jsx** or a new **YearlyPerformance** component (partner view). |
| `GET /api/analytics/performance/dashboard/{year}` | Not implemented | `analyticsApi.js`: new endpoint. **AdminDashboard.jsx**: replace mock “top/slowest” and performance KPIs with this dashboard. |

**Components:** `src/features/analytics/PerformanceScorecard.jsx` exists but is **not used** in any route; wire it into partner analytics or dashboard.

---

## 3. Target projection (doc)

| Doc endpoint | Frontend status | Where to implement |
|--------------|-----------------|--------------------|
| `GET /api/analytics/projection/{partnerId}/{year}` | Not implemented; ProjectionCard uses `getMonthlyPerformance` for a single `projection` field | `analyticsApi.js`: new endpoint. **ProjectionCard.jsx**: call this instead of (or in addition to) monthly performance. |
| `GET /api/analytics/projection/all/{year}` | Not implemented | `analyticsApi.js`: new endpoint. New admin view or section in **AdminDashboard.jsx** (e.g. “All partner projections”, risk count). |
| `GET /api/analytics/projection/categories/{partnerId}/{year}` | Not implemented | `analyticsApi.js`: new endpoint. **ProjectionCard.jsx** or partner analytics: show paint/plaster/polystyrene breakdown. |

**Components:** `src/features/analytics/ProjectionCard.jsx` exists but is **not used** in any route; wire it into partner dashboard or analytics.

---

## 4. Compliance tracking (doc)

| Doc endpoint | Frontend status | Where to implement |
|--------------|-----------------|--------------------|
| `GET /api/analytics/compliance/{partnerId}/{year}` | Not implemented | `analyticsApi.js`: new endpoint. **ComplianceTracker.jsx** or partner compliance view: show monthly breakdown, overall %. |
| `GET /api/analytics/compliance/missing/{partnerId}/{year}` | Not implemented | `analyticsApi.js`: new endpoint. Same compliance view: list of weeks without reports. |
| `POST /api/analytics/compliance/submit/{partnerId}/{weekNumber}/{year}` | Frontend has `submitWeeklyReport` (path may differ) | Align payload/URL with doc; use in **ComplianceTracker** or weekly report form. |
| `GET /api/analytics/compliance/non-compliant/{year}?threshold=85` | Not implemented | `analyticsApi.js` or adminApi: new endpoint. **AdminDashboard.jsx**: replace hardcoded “Recent non-compliant partners” list with this. |
| `GET /api/analytics/compliance/dashboard/{year}` | Not implemented | `analyticsApi.js`: new endpoint. **AdminDashboard.jsx**: compliance overview (average %, fully compliant count, non-compliant list). |

**Components:** `src/features/analytics/ComplianceTracker.jsx` exists but is **not used** in any route; wire it into partner or admin analytics.

---

## 5. Product analytics (doc)

| Doc endpoint | Frontend status | Where to implement |
|--------------|-----------------|--------------------|
| `GET /api/analytics/products/top?limit=5&days_back=30` | ProductAnalytics uses `getMonthlyPerformance` for `topProducts` (shape may differ) | Align with doc (limit, days_back). **ProductAnalytics.jsx** already uses it; ensure API slice matches doc. |
| `GET /api/analytics/products/deadstock?days_without_sale=30` | Same; `deadStock` from monthly performance | Same as above. |
| `GET /api/analytics/products/categories/{year}` | Not implemented; ProductAnalytics uses salesApi `getSalesByCategoryQuery` | Add to analyticsApi or keep salesApi; use in **ProductAnalytics.jsx** for category breakdown by year. |
| `GET /api/analytics/products/trend/{productId}/{year}` | Not implemented | `analyticsApi.js`: new endpoint. New component or ProductAnalytics: product trend chart. |
| `GET /api/analytics/products/dashboard/{year}` | Not implemented | `analyticsApi.js`: new endpoint. **ProductAnalytics.jsx** or admin analytics: full product overview. |

**Where:** `src/store/api/analyticsApi.js` (or dedicated product analytics API), `src/features/analytics/ProductAnalytics.jsx`

---

## 6. Return simulation (doc)

| Doc endpoint | Frontend status | Where to implement |
|--------------|-----------------|--------------------|
| `POST /api/analytics/returns/simulate/{partnerId}/{year}` with `{ "additional_sales": 50000 }` | Not implemented; **ReturnSimulator.jsx** does a local calculation (sales summary × uplift %) | `analyticsApi.js`: new mutation. **ReturnSimulator.jsx**: call this API with partnerId, year, and additional_sales; display doc’s response (projected total, return calculation, improvement). |
| `GET /api/analytics/returns/actual/{partnerId}/{year}` | Not implemented | `analyticsApi.js`: new query. **ReturnSimulator.jsx** or partner returns view: show actual return. |
| `GET /api/analytics/returns/scenarios/{partnerId}/{year}` | Not implemented | `analyticsApi.js`: new query. **ReturnSimulator.jsx**: show +10%, +20%, +30% scenarios from API. |

**Where:** `src/store/api/analyticsApi.js`, `src/features/analytics/ReturnSimulator.jsx`

---

## 7. Inventory health (doc)

| Doc endpoint | Frontend status | Where to implement |
|--------------|-----------------|--------------------|
| `GET /api/analytics/inventory/health/{warehouseId}?days_back=30` | Not implemented | analyticsApi or adminApi: new endpoint. New **WarehouseHealth** component or inventory page. |
| `GET /api/analytics/inventory/health/all?days_back=30` | Not implemented | Same; use in admin inventory or **AdminDashboard.jsx**. |
| `GET /api/analytics/inventory/low-stock?days_threshold=7` | Frontend has `getLowStockAlerts` (/analytics) and admin `getLowStock` (/admin) | Align with doc (days_threshold). **TopNav.jsx**, **AdminDashboard.jsx** already use low-stock; ensure response shape matches. |
| `GET /api/analytics/inventory/product-health?days_back=30` | Not implemented | analyticsApi: new endpoint. New component or inventory view: product-level health by risk. |

**Where:** `src/store/api/analyticsApi.js` or `adminApi.js`, `src/components/layout/TopNav.jsx`, `src/features/dashboard/admin/AdminDashboard.jsx`, new inventory health view.

---

## 8. Dashboards using mock data

- **AdminDashboard.jsx**  
  Uses **mock data** for: KPIs (revenue, partners, low stock, non-compliant), monthly sales card, sales trend, category mix, compliance heatmap, partner rank, projection funnel, low stock list, dead stock list, “Recent non-compliant partners”, target progress.  
  **Action:** Replace with real API calls (performance dashboard, compliance dashboard, projection/all, inventory health, product dashboard, etc.) as above.

- **PartnerDashboard.jsx**  
  Uses **mock data** for: KPIs, monthly sales, trend, category, target progress, low stock, best/slowest products, dead stock, projection warning, stock turnover.  
  **Action:** Replace with partner-scoped APIs (monthly/yearly performance, projection, compliance, returns, inventory) and wire **ProjectionCard**, **ReturnSimulator**, **ComplianceTracker**, **PerformanceScorecard** where appropriate.

**Where:**  
`src/features/dashboard/admin/AdminDashboard.jsx`  
`src/features/dashboard/partner/PartnerDashboard.jsx`

---

## 9. Unused analytics components

These components exist but are **not referenced** in the router or in the main dashboards:

| Component | Path | Suggested use |
|-----------|------|----------------|
| PerformanceScorecard | `src/features/analytics/PerformanceScorecard.jsx` | Partner analytics page or partner dashboard section; feed from performance/monthly and performance/yearly. |
| ComplianceTracker | `src/features/analytics/ComplianceTracker.jsx` | Partner or admin compliance view; feed from compliance and compliance/missing. |
| ProjectionCard | `src/features/analytics/ProjectionCard.jsx` | Partner dashboard or analytics; feed from projection/{partnerId}/{year}. |
| ReturnSimulator | `src/features/analytics/ReturnSimulator.jsx` | Partner dashboard or analytics; replace local math with returns/simulate, actual, scenarios. |

**Where:** Add to routes in `src/router/index.jsx` (e.g. under `/admin/analytics`, `/partner/analytics`) or embed in `AdminDashboard.jsx` / `PartnerDashboard.jsx`.

---

## 10. Summary checklist

| Area | Missing / to do | Primary files |
|------|------------------|---------------|
| Performance | Yearly performance, performance dashboard (admin), path params for monthly | analyticsApi.js, PerformanceScorecard.jsx, AdminDashboard.jsx |
| Projection | Partner projection, all projections (admin), category projections | analyticsApi.js, ProjectionCard.jsx, AdminDashboard.jsx |
| Compliance | Partner compliance, missing weeks, non-compliant list, compliance dashboard | analyticsApi.js, ComplianceTracker.jsx, AdminDashboard.jsx |
| Product | Categories by year, product trend, product dashboard | analyticsApi.js, ProductAnalytics.jsx |
| Returns | Simulate, actual, scenarios (replace local ReturnSimulator logic) | analyticsApi.js, ReturnSimulator.jsx |
| Inventory health | Warehouse health, health/all, product-health | analyticsApi.js or adminApi.js, TopNav, new view or AdminDashboard |
| Dashboards | Replace all mock data with real APIs | AdminDashboard.jsx, PartnerDashboard.jsx |
| Routing | Use PerformanceScorecard, ComplianceTracker, ProjectionCard, ReturnSimulator | router/index.jsx or dashboard layouts |

---

**Note:** Backend route paths in the doc (e.g. `/api/analytics/performance/monthly/...`) may differ from current frontend base paths (`/analytics`, `/admin`). Either the backend exposes both styles or the frontend must be updated to match the doc’s URLs (and vice versa). Align with your actual API base URL and route list before implementing.
