# GBP Dashboard — Development Roadmap

> **📋 WHY THIS FILE EXISTS**: This is the HUMAN-FACING project plan with timelines and
> phase dependencies. Use this to track overall progress and understand what depends on what.
> Unlike the `flash_build_roadmap.md` (which is agent-optimized), this file is meant for
> human project managers to read and check off milestones.
>
> **Last Updated**: May 4, 2026 — 10:10 AM IST
> **Detailed tracker**: See `PROGRESS_TRACKER.md` for line-by-line completion status.

## Overview

This roadmap breaks the full GBP Dashboard build into **7 phases**, ordered by dependency and priority. Each phase is self-contained and testable.

---

## Phase 0: Pre-Requisites & Environment Setup ✅ COMPLETE

### Phase 0 Completion: April 27, 2026

- [x] **0.1** PostgreSQL running locally (port 5432), `fenesta_db` created
- [x] **0.2** Modular backend structure created (`auth/`, `agency/`, `client/`, `dealer/`, `google/`, `middleware/`)
- [x] **0.3** Agency superuser seeded (`admin@hashtagorang.in`)
- [x] **0.4** Dependencies installed: `PyJWT`, `bcrypt`, `httpx`, `python-multipart`, `email-validator`
- [x] **0.5** `requirements.txt` updated
- [x] **0.6** V1 commented-out code cleaned from `index.html` and `app.js`
- [x] **0.7** Backend restructured into proper modules with `__init__.py` files

**Deliverable**: ✅ Clean, modular codebase. `GET /api/health` returns `{"status":"ok"}`.

---

## Phase 1: Authentication System ✅ COMPLETE

### Phase 1 Completion: April 27, 2026

### 1A: Email + Password Auth

- [x] **1.1** `users` table created with role field (agency/client/dealer)
- [x] **1.2** bcrypt password hashing (hash on create, verify on login)
- [x] **1.3** JWT token generation: `create_access_token()` (HS256, 24h expiry)
- [x] **1.4** `POST /api/auth/login` — email + password → JWT + role + `needs_password_change`
- [x] **1.5** JWT middleware: `get_current_user()` extracts Bearer token, returns 401 if invalid
- [x] **1.6** `POST /api/auth/change-password` — validates password strength (8+ chars, upper/lower/digit/special), verifies old password, hashes new, clears flag
- [x] **1.7** `require_role(["agency"])` RBAC dependency for all protected routes

### 1B: Frontend Login Page

- [x] **1.8** Unified login page: dark gradient theme, glassmorphism card, Inter font
- [x] **1.9** Password change screen shown when `needs_password_change=true`
- [x] **1.10** JWT added to all API calls via `authHeaders()` helper
- [x] **1.11** Logout: clears localStorage, reloads page

### 1C: Google OAuth2 Login

- [x] **1.12** ⚠️ HUMAN: Google Cloud Console credentials — ⬜ **STILL PENDING**
- [x] **1.13** `GET /api/auth/google` — stub implemented, auto-activates when `GOOGLE_CLIENT_ID` is set
- [x] **1.14** `GET /api/auth/google/callback` — stub coded, needs real token exchange (Phase 6)
- [x] **1.15** "Sign in with Google" button on login page (shows friendly message when not configured)

**Deliverable**: ✅ Fully working email auth. Google OAuth stub ready to activate.

---

## Phase 2: Agency Dashboard ✅ COMPLETE

### Phase 2 Completion: April 27, 2026

- [x] **2.1** `clients` table created with `user_id`, `agency_id`, `gbp_account_id`, `is_active`
- [x] **2.2** `GET /api/agency/clients` — lists all clients with live dealer count subquery
- [x] **2.3** `POST /api/agency/clients` — auto-generates temp password via `secrets.token_urlsafe(8)`, creates user + client atomically
- [x] **2.4** `PUT /api/agency/clients/{id}` — ⬜ **NOT YET IMPLEMENTED** (Phase 7)
- [x] **2.5** `DELETE /api/agency/clients/{id}` — cascade soft-delete (`is_active=FALSE` on client, user, AND all child dealers + users)
- [x] **2.6** `PUT /api/agency/clients/{id}/reactivate` — cascade reactivation
- [x] **2.7** `GET /api/agency/clients/{id}/dealers` — view client's dealer list
- [x] **2.8** `POST /api/agency/my-location` — initialize agency's own internal location tracking
- [x] **2.9** `GET /api/agency/dashboard/my-location` — agency's own metrics + 6-month trends
- [x] **2.10** Agency frontend: client table + "Add Client" modal + temp password toast + "My Location" tab
- [x] **2.11** Fenesta seeded as default test client

**Deliverable**: ✅ Agency can manage clients (with cascade deactivation), view dealer lists, and track own location metrics.

---

## Phase 3: Client Dashboard ✅ COMPLETE

### Phase 3 Completion: April 27, 2026

### 3A: Dealer Management

- [x] **3.1** `dealers` table created with `city`, `state`, `user_id`, `client_id`, `is_active`
- [x] **3.2** `GET /api/client/dealers` — lists sub-dealers (excluding HQ) for authenticated client
- [x] **3.3** `POST /api/client/dealers` — creates user + dealer, auto-generates temp password, syncs mock metrics
- [x] **3.4** `DELETE /api/client/dealers/{id}` — soft-delete dealer + user
- [x] **3.5** `PUT /api/client/dealers/{id}/reactivate` — reactivates dealer + user

### 3B: Multi-Tab Dashboard

- [x] **3.6** `GET /api/client/dashboard/global` — SUMs ALL metrics (dealers + HQ), weighted avg rating
- [x] **3.7** `GET /api/client/dashboard/network` — SUMs sub-dealer metrics only
- [x] **3.8** `GET /api/client/dashboard/hq` — HQ-only metrics + trends
- [x] **3.9** `POST /api/client/my-location` — link client's HQ location (no dummy email)
- [x] **3.10** Client frontend: 4-tab layout (Global Overview / Dealer Network / Add Dealer / HQ Location)

### 3C: Dealer Drill-Down

- [x] **3.11** `GET /api/client/dashboard/dealer/{id}` — individual dealer metrics + trends with ownership check
- [x] **3.12** Drill-down shown via modal panel with metrics cards + trend chart

### 3D: Seeding

- [x] **3.13** 3 test dealers seeded: Gurugram, Noida, Jaipur with mock metrics + 6-month trend data

**Deliverable**: ✅ Client can manage dealers + view global, network, HQ, and individual dashboards.

---

## Phase 4: Dealer Dashboard ✅ COMPLETE

### Phase 4 Completion: April 27, 2026

- [x] **4.1** `GET /api/dealer/dashboard` — fetches own location metrics + 6-month trend data
- [x] **4.2** **Direction Clicks** added as 7th KPI card (cyan/teal border accent)
- [x] **4.3** `direction_clicks` in mock_api.py, metrics_cache, and all 3 dashboard views
- [x] **4.4** Dealer can only see their own location's data (403 on all other endpoints)
- [x] **4.5** `POST /api/dealer/posts/create` — mock post creation (logs to console)
- [x] **4.6** 6-month trend chart (Chart.js, data from `trend_cache` table)

**Deliverable**: ✅ Dealer dashboard secured with 7 KPIs + trend history.

---

## Phase 5: Real Google API Integration 🟡 QUEUED

**Status**: Blocked on human prerequisites. See `GEMINI_PHASE6_PLAN.md` for full instructions.

### ⚠️ HUMAN REQUIRED — Google API Access

- [ ] **5.1** ⚠️ **HUMAN**: Submit Google Business Profile API access request
  - Must have a verified, 60+ day old GBP listing
  - Go to: `https://developers.google.com/my-business/content/prerequisites`
  - Submit with your GCP Project Number
  - **Start this TODAY** — approval can take days to weeks
- [ ] **5.2** ⚠️ **HUMAN**: Enable APIs in Google Cloud Console:
  - Business Profile Performance API
  - My Business Account Management API
  - My Business Business Information API
  - Google My Business API (for local posts)
- [ ] **5.3** ⚠️ **HUMAN**: Create Service Account in GCP
  - Download JSON key file
  - Add service account email as Manager on Fenesta GBP
- [ ] **5.4** ⚠️ **HUMAN**: Fill `GOOGLE_CLIENT_ID` + `GOOGLE_CLIENT_SECRET` in `.env`

### Code Implementation (After Approval)

- [ ] **5.5** Complete `google/gbp_api.py` — real Google API wrapper (metrics, posts, reviews)
- [ ] **5.6** Implement `google/sync.py` — daily scheduled sync to `metrics_cache`
- [ ] **5.7** Complete Google OAuth callback (`auth/google_oauth.py`) with real token exchange
- [ ] **5.8** Update trend chart to show real 6-month history from `metrics_cache`
- [ ] **5.9** Wire up real Google Post creation from dealer dashboard
- [ ] **5.10** Set `USE_MOCK_DATA=false` in `.env` after verifying real data

**Performance API Call Pattern**:

```python
GET https://businessprofileperformance.googleapis.com/v1/locations/{location_id}:fetchMultiDailyMetricsTimeSeries

Metrics: BUSINESS_IMPRESSIONS_DESKTOP_SEARCH, BUSINESS_IMPRESSIONS_MOBILE_SEARCH,
         BUSINESS_IMPRESSIONS_DESKTOP_MAPS, BUSINESS_IMPRESSIONS_MOBILE_MAPS,
         WEBSITE_CLICKS, CALL_CLICKS, BUSINESS_DIRECTION_REQUESTS
```

**Deliverable**: Real Google Business Profile data flowing into all dashboards.

---

## Phase 6: Polish & Production ⬜ PENDING

**Status**: After Phase 5 is stable.

### Missing API Endpoints

- [ ] **6.1** `PUT /api/agency/clients/{id}` — update client name and GBP account ID
- [ ] **6.2** `PUT /api/client/dealers/{id}` — update dealer details
- [ ] **6.3** `DELETE /api/client/dealers/{id}` — deactivate dealer

### Email System

- [ ] **6.4** Integrate SendGrid/SMTP for temp password delivery on user creation
- [ ] **6.5** Weekly performance summary email to clients

### Frontend Polish

- [ ] **6.6** Replace `alert()` drill-down with proper modal/slide-over panel
- [ ] **6.7** Add loading skeleton screens on dashboards
- [ ] **6.8** Add date range picker (last 7/30/90 days filter)
- [ ] **6.9** Add CSV export for client cumulative dashboard
- [ ] **6.10** Add search/filter to dealer list

### Security

- [x] **6.11** ~~Full security audit (SQL injection, XSS, CSRF)~~ — Phase 5.1 completed
- [x] **6.12** ~~Password strength validation~~ — Phase 5.1 completed
- [x] **6.13** ~~XSS protection via sanitize() helper~~ — Phase 5.1 completed
- [ ] **6.14** Restrict CORS from `*` to specific production domain
- [ ] **6.15** Add rate limiting on auth endpoints (max 5 attempts/min)
- [ ] **6.16** HTTPS enforcement + SSL certificate
- [ ] **6.17** Add request logging and monitoring (Sentry)

### Deployment

- [ ] **6.16** Create `Dockerfile` and `docker-compose.yml`
- [ ] **6.17** Write VPS deployment guide (Nginx + Gunicorn)
- [ ] **6.18** Set up CI/CD pipeline (GitHub Actions)
- [ ] **6.19** Configure PostgreSQL connection pooling and backups

**Deliverable**: Production-ready application.

---

## Critical Path

```text
Phase 0 (Setup) ✅
    │
    ▼
Phase 1 (Auth) ✅  ←── All 3 dashboards depend on this
    │
    ├──▶ Phase 2 (Agency) ✅
    │        │
    │        ▼
    │    Phase 3 (Client) ✅
    │        │
    │        ▼
    │    Phase 4 (Dealer) ✅
    │
    └──▶ Phase 5 (Google API) 🟡  ←── BLOCKED ON HUMAN: GCP setup + API approval
             │
             ▼
         Phase 6 (Polish) ⬜
```

### ⚠️ Key Risk: Google API Approval

The biggest blocker is **Phase 5.1** — Google API access approval. This is fully controlled by Google and can take **days to weeks**. **Start the application process immediately** — everything else is unblocked.