igny8/to-do-s/part1/SECTION_4_FINAL_MODS.md

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

---