# Section 4: ACCOUNT Modules - Audit & Action Plan

**Date:** December 27, 2025  
**Status:** Finalized for Implementation  
**Scope:** Account Settings, Plans & Billing, Usage (AI Models excluded - admin only)

---

## 4.1 Account Settings

**Route:** `/account/settings`  
**File:** `pages/account/AccountSettingsPage.tsx`  
**Tabs:** Account, Profile, Team

### Current Functionality
- **Account Tab:** Organization name, billing email, full billing address, tax ID/VAT
- **Profile Tab:** First/last name, email, phone, timezone, language, notifications, security
- **Team Tab:** List team members, invite via email, remove members, role display

---

### Issues to Address

| # | Issue | Priority | Action |
|---|-------|----------|--------|
| 1 | Profile NOT connected to API | 🔴 Critical | Study existing backend - if profile API exists and is consistent with system, connect it. If not present, create consistent with existing API structure |
| 2 | Change Password does nothing | 🔴 Critical | Implement password change functionality |
| 3 | No role assignment on invite | High | Add role dropdown (Admin/Member) to invitation form |
| 4 | No role editing for members | High | Add ability to change member role after invitation |
| 5 | No email verification | High | Implement email verification flow when email is changed |
| 6 | Orphaned TeamManagement.tsx | High | Delete `pages/account/TeamManagement.tsx` - functionality exists in AccountSettingsPage |
| 7 | No 2FA option | Medium | Add two-factor authentication option in security section |
| 8 | No account deletion | Medium | Add account closure/deletion capability |
| 9 | No session management | Medium | Add view/revoke active sessions capability |
| 10 | No pending invitation management | Medium | Add ability to resend or cancel pending invitations |
| 11 | No team member limit display | Medium | Show "X of Y team members" based on plan limit |
| 12 | Inconsistent role system | Medium | Backend returns `is_admin` boolean but UI shows Admin/Member - align these |

---

### Implementation Notes

**For Issue #1 (Profile API):**
- First: Audit backend to check if profile endpoint exists
- If exists: Study implementation, verify consistency with other APIs, then connect frontend
- If not exists: Create new endpoint following existing API patterns in the codebase
- Fields to persist: first_name, last_name, email, phone, timezone, language, notification preferences

**For Issue #2 (Password change):**
- Implement secure password change requiring current password
- Validate new password meets requirements
- Consider session invalidation after password change

**For Issue #12 (Role consistency):**
- Decide on role system: boolean `is_admin` or role enum (admin/member/viewer)
- Align frontend display with backend data structure

---

## 4.2 Plans & Billing

**Route:** `/account/plans`  
**Files:** `pages/account/PlansAndBillingPage.tsx`, `pages/Billing/CreditPurchase.tsx`  
**Tabs:** Current Plan, Upgrade Plan, History

### Current Functionality
- **Current Plan:** Plan name, status, credits, balance, renewal date, features
- **Upgrade:** Pricing table, plan comparison, change policy
- **History:** Invoices with PDF download, payments, payment methods

### Payment Context
Currently using manual payment methods only (bank transfer, wallet). No automatic payment processing.

---

### Issues to Address

| # | Issue | Priority | Action |
|---|-------|----------|--------|
| 1 | No proration preview | High | Show prorated amount before plan upgrade/downgrade |
| 2 | Credit purchase not linked | Medium | Link to credit purchase from Plans & Billing page |
| 3 | Cancellation is immediate | High | Add confirmation dialog before plan cancellation |
| 4 | No downgrade proration display | Medium | Show calculation when downgrading plan |
| 5 | Throttling errors surface to users | Medium | Replace raw throttling messages with user-friendly spinner/message |
| 6 | No billing cycle visualization | Medium | Make renewal date prominent, show billing cycle clearly |
| 7 | No cancellation reason collection | Low | Add optional reason selection when cancelling |

---

### Issues NOT Being Addressed (Per Discussion)

| Issue | Reason |
|-------|--------|
| No payment failure retry | Manual payment only - no auto-retry needed |
| Payment method UI incomplete | Manual payment only - limited methods by design |

---

### Implementation Notes

**For Issue #1 (Proration preview):**
- Before confirming plan change, show:
  - Current plan remaining value
  - New plan cost
  - Prorated amount due/credited
- Calculate based on days remaining in billing cycle

**For Issue #3 (Cancellation confirmation):**
- Modal dialog: "Are you sure you want to cancel?"
- Show what they'll lose (features, remaining credits)
- Require explicit confirmation

**For Issue #5 (Throttling messages):**
- Intercept throttling errors
- Show spinner with "Processing your request..." instead of technical error
- Implement proper retry logic behind the scenes

---

## 4.3 Usage

**Route:** `/account/usage`  
**Files:** `pages/account/UsageAnalyticsPage.tsx`, `pages/account/UsageLimits.tsx`, `pages/account/CreditActivity.tsx`  
**Tabs:** Your Limits & Usage, Credit History, API Activity

### Current Functionality
- **Quick Stats:** Credits left, used this month, monthly limit, usage %
- **Limits:** Hard limits (sites, users, keywords, clusters) + Monthly limits
- **Credit History:** Transaction log with type, amount, description
- **API Activity:** Call statistics, endpoint breakdown

---

### Issues to Address

| # | Issue | Priority | Action |
|---|-------|----------|--------|
| 1 | API Activity is HARDCODED | 🔴 Critical | Implement real API activity tracking - replace fake values (1,234, 567, 342) |
| 2 | Success rate is fake | 🔴 Critical | Calculate and display real success rate from actual data |
| 3 | No usage alerts | High | Implement default alerts at usage thresholds (80%, 90%, 100%) - sent to all users automatically |
| 4 | No per-site usage | High | Add breakdown showing which site consumed what |
| 5 | No usage forecasting | Medium | Add "At current rate, you'll reach limit in X days" |
| 6 | No actionable insights | Medium | Suggest upgrade when approaching limits |
| 7 | Credit history lacks context | Medium | Add links from credit transactions to related content/operations |

---

### Issues NOT Being Addressed (Per Discussion)

| Issue | Reason |
|-------|--------|
| No per-user usage | Not needed for current phase |
| No usage export | Not needed for current phase |

---

### Implementation Notes

**For Issue #1 & #2 (Real API Activity):**
- Backend needs to log API calls (may already exist)
- Track: endpoint, timestamp, status (success/fail), response time
- Aggregate for display: total calls, success rate, calls by endpoint
- Replace hardcoded values with real calculated data

**For Issue #3 (Usage alerts):**
- Default behavior: all users receive alerts
- Trigger points: 80%, 90%, 100% of limits
- Delivery: in-app notification + email
- No user preferences needed - alerts go to everyone

**For Issue #4 (Per-site usage):**
- Break down credit usage by site
- Show: "Site A: 450 credits, Site B: 230 credits"
- Pie chart or table visualization

---

## 4.4 AI Models (Admin Only)

**Status:** ❌ SKIP ENTIRELY

Not part of user-facing modules. Admin only - no changes needed.

---

## 4.5 ACCOUNT Cross-Module Issues (MAJOR)

These are architectural issues requiring proper analysis and solutions.

### Issues to Address

| # | Issue | Priority | Action |
|---|-------|----------|--------|
| 1 | Multiple credit balance sources | 🔴 Critical | Establish ONE source of truth for credit balance. Analyze: Plans page, Usage page, billingStore - determine which is authoritative, remove others, refactor all references |
| 2 | Fragmented billing pages | High | **AI Agent Task:** Audit system to identify all billing-related pages/functions, find duplicates/redundancies, propose consolidation solution |
| 3 | Legacy routes still exist | High | Remove legacy routes (`/billing/overview`, `/team`, `/profile`), remove redirect code, refactor any references throughout codebase |
| 4 | No notification preferences | Low | Not needed - default alerts go to all users |

---

### Implementation Notes

**For Issue #1 (Single source of truth for balance):**

*Phase 1: Analysis*
- Identify all places that fetch/display credit balance:
  - `billingStore.ts` (Zustand store)
  - Plans & Billing page
  - Usage page
  - Dashboard (if applicable)
  - Header component (if showing balance)
- Document how each fetches data (API endpoint, frequency)

*Phase 2: Decision*
- Determine which should be THE source:
  - Likely `billingStore` as central state management
  - Single API endpoint for balance data
- All components should read from this one source

*Phase 3: Implementation*
- Refactor all components to use single source
- Remove duplicate API calls
- Remove duplicate state management
- Ensure consistency across all views

**For Issue #2 (Fragmented billing pages):**

*AI Agent Audit Task:*
```
TASK: Billing Pages Consolidation Audit

1. DISCOVER all billing-related files:
   - pages/account/PlansAndBillingPage.tsx
   - pages/Billing/CreditPurchase.tsx
   - pages/Billing/Credits.tsx (if exists)
   - pages/Settings/CreditsAndBilling.tsx (if exists)
   - Any other billing-related pages

2. ANALYZE each page:
   - What functionality does it provide?
   - What routes point to it?
   - Is it actively used or orphaned?
   - Does it duplicate functionality from another page?

3. IDENTIFY redundancies:
   - Same functionality in multiple places
   - Overlapping features
   - Dead/orphaned pages

4. PROPOSE solution:
   - Which pages to keep
   - Which pages to merge
   - Which pages to delete
   - Final consolidated structure

5. DOCUMENT migration path:
   - What routes need updating
   - What references need changing
   - What imports need refactoring
```

**For Issue #3 (Legacy routes removal):**

*Routes to remove:*
- `/billing/overview`
- `/team`
- `/profile`

*Process:*
1. Find route definitions in router/App.tsx
2. Remove route entries
3. Find and remove redirect logic
4. Search codebase for any links to these routes
5. Update or remove those links
6. Delete any orphaned components only used by these routes

---

## Summary

### Total Issues by Section

| Section | Critical | High | Medium | Low | Total |
|---------|----------|------|--------|-----|-------|
| 4.1 Account Settings | 2 | 4 | 6 | 0 | 12 |
| 4.2 Plans & Billing | 0 | 2 | 4 | 1 | 7 |
| 4.3 Usage | 2 | 2 | 3 | 0 | 7 |
| 4.4 AI Models | - | - | - | - | Skipped |
| 4.5 Cross-Module | 1 | 2 | 0 | 1 | 4 |
| **TOTAL** | **5** | **10** | **13** | **2** | **30** |

---

### Critical Items (Must Fix)

1. **Account Settings** - Profile tab not connected to API
2. **Account Settings** - Password change does nothing
3. **Usage** - API Activity tab shows hardcoded fake data
4. **Usage** - Success rate is fake (98.5%)
5. **Cross-Module** - Multiple credit balance sources causing inconsistency

---

### High Priority Items

1. Account Settings - Role assignment on invite
2. Account Settings - Role editing for members
3. Account Settings - Email verification
4. Account Settings - Delete orphaned TeamManagement.tsx
5. Plans & Billing - Proration preview
6. Plans & Billing - Cancellation confirmation dialog
7. Usage - Usage alerts at thresholds
8. Usage - Per-site usage breakdown
9. Cross-Module - Billing pages consolidation audit
10. Cross-Module - Legacy routes removal

---

### Files to Delete

| File | Reason |
|------|--------|
| `pages/account/TeamManagement.tsx` | Orphaned - functionality in AccountSettingsPage |
| Legacy route redirect handlers | After removing `/billing/overview`, `/team`, `/profile` |
| Duplicate billing pages | After consolidation audit determines which to remove |

---

### Files to Modify

| File | Changes |
|------|---------|
| `pages/account/AccountSettingsPage.tsx` | Connect profile API, implement password change, add role management, add invitation management |
| `pages/account/PlansAndBillingPage.tsx` | Add proration preview, cancellation confirmation, link credit purchase |
| `pages/account/UsageAnalyticsPage.tsx` | Implement real API activity, add per-site breakdown, add forecasting |
| `store/billingStore.ts` | Establish as single source of truth for balance |
| Router/App.tsx | Remove legacy routes |
| All components using credit balance | Refactor to use single source |

---

### Backend Work Required

| Area | Work |
|------|------|
| Profile API | Audit existing endpoint OR create new one consistent with API structure |
| Password change API | Implement secure password change endpoint |
| API Activity tracking | Ensure backend logs API calls, create endpoint to retrieve activity data |
| Usage alerts | Backend service to check thresholds and trigger notifications |
| Per-site usage | Endpoint to return credit usage broken down by site |

---

### AI Agent Specific Tasks

| Task | Description |
|------|-------------|
| Billing Pages Audit | Discover all billing pages, analyze functionality, identify redundancies, propose consolidation |
| Credit Balance Refactor | Identify all balance sources, determine single source, refactor all references |
| Legacy Routes Cleanup | Remove routes, remove redirects, update all references |
| Profile API Study | Check if endpoint exists, verify consistency, connect or create |

---


## ✅ Section 4 Implementation Complete

### CRITICAL Items Completed:

1. **Profile API Connection** (AccountSettingsPage.tsx)
   - Profile tab now loads user data from `useAuthStore`
   - Added `getUserProfile()` and `updateUserProfile()` functions to billing.api.ts

2. **Password Change Implementation** (AccountSettingsPage.tsx)
   - Added password change modal with old/new password fields
   - Connected to `/auth/change-password/` backend endpoint
   - Added validation (min 8 chars, confirmation match)

3. **Fixed Fake API Activity Data** (UsageAnalyticsPage.tsx)
   - Removed hardcoded values (98.5%, 1,234, 567, 342)
   - API tab now shows real data from `analytics?.usage_by_type`
   - Displays "Operations by Type" with actual credits/counts

### HIGH Priority Items Completed:

4. **Deleted TeamManagementPage.tsx**
   - Removed orphaned file (functionality already exists as tab in AccountSettingsPage)

5. **Added Cancellation Confirmation Dialog** (PlansAndBillingPage.tsx)
   - Cancel button now shows confirmation modal
   - Modal explains consequences (loss of features, credit preservation)
   - User must confirm before cancellation proceeds

6. **Legacy Routes Verified**
   - `/billing/overview` → Points to CreditsAndBilling page
   - `/account/team` → Redirects to `/account/settings`
   - `/settings/profile` → Redirects to `/account/settings`