# Frontend Pages & Routes

**Last Verified:** December 27, 2025  
**Version:** 1.2.0  
**Framework:** React 19 + TypeScript + React Router 6 + Vite

---

## Route Configuration

Routes defined in `/frontend/src/App.tsx`:
- `PrivateRoute` - Requires authentication
- `AdminRoute` - Requires admin/staff role
- Nested layouts with `AppLayout` (sidebar + header)

---

## Public Routes (No Auth Required)

| Route | File | Description |
|-------|------|-------------|
| `/login` | `AuthPages/SignIn.tsx` | User login |
| `/register` | `AuthPages/SignUp.tsx` | New account registration |
| `/forgot-password` | `AuthPages/ForgotPassword.tsx` | Request password reset |
| `/reset-password/:token` | `AuthPages/ResetPassword.tsx` | Set new password |
| `/verify-email/:token` | `AuthPages/VerifyEmail.tsx` | Email verification |

---

## Dashboard

| Route | File | Description |
|-------|------|-------------|
| `/` | `Dashboard/Home.tsx` | Main dashboard with workflow pipeline, metrics, quick actions |

**v1.2.0 Dashboard Widgets:**
- `WorkflowPipelineWidget` - Visual flow: Sites → Keywords → Clusters → Ideas → Tasks → Drafts → Published
- `AIOperationsWidget` - Operation stats (clustering, ideas, content, images) with time filter (7d/30d/90d)
- `RecentActivityWidget` - Activity feed with type-specific icons
- `ContentVelocityWidget` - Week/Month/Total metrics table
- `AutomationStatusWidget` - Status, schedule, last/next run, run controls
- `NeedsAttentionBar` - Alert bar for pending actions requiring attention
- `QuickActionsWidget` - Quick action buttons for common tasks

**Data Sources:**
- Pipeline counts from actual API calls (keywords, clusters, ideas, tasks, content)
- AI operations derived from content creation totals
- Activity generated from real data with capped display values

---

## SETUP Routes

### Add Keywords

| Route | File | Description |
|-------|------|-------------|
| `/setup/add-keywords` | `Setup/IndustriesSectorsKeywords.tsx` | Browse/add seed keywords from global database |

**Features:**
- Industry → Sector → Keywords browse hierarchy
- "Show not-added only" filter toggle
- Real-time keyword count summary (added/total)
- "Next: Plan Your Content" CTA button
- "Keyword Research" coming soon teaser

### Content Settings

| Route | File | Description |
|-------|------|-------------|
| `/account/content-settings` | `account/ContentSettingsPage.tsx` | 3 tabs: Content Generation, Publishing, Image Settings |

**API Endpoints:** Settings persisted via `/api/v1/system/settings/content/{key}/`

### Sites

| Route | File | Description |
|-------|------|-------------|
| `/sites` | `Sites/List.tsx` | Site listing with setup checklist per site |
| `/sites/:id/dashboard` | `Sites/Dashboard.tsx` | Site overview with setup checklist |
| `/sites/:id/settings` | `Sites/Settings.tsx` | Site settings (General, Integrations, Content Types) |

**Components:**
- `SiteSetupChecklist` - Shows setup progress (site created, industry/sectors, WordPress, keywords)

### Thinker (Admin Only)

| Route | File | Description |
|-------|------|-------------|
| `/thinker/prompts` | `Thinker/Prompts.tsx` | AI prompt template management |
| `/thinker/author-profiles` | `Thinker/AuthorProfiles.tsx` | Author profile CRUD |
| `/thinker/strategies` | `Thinker/Strategies.tsx` | Coming Soon placeholder |
| `/thinker/image-testing` | `Thinker/ImageTesting.tsx` | Coming Soon placeholder |

---

## WORKFLOW Routes

### Planner

| Route | File | Description | Tab |
|-------|------|-------------|-----|
| `/planner` | → `/planner/keywords` | Redirect | - |
| `/planner/keywords` | `Planner/Keywords.tsx` | Keyword management, bulk actions | Keywords |
| `/planner/clusters` | `Planner/Clusters.tsx` | Cluster listing, AI clustering | Clusters |
| `/planner/clusters/:id` | `Planner/ClusterView.tsx` | Individual cluster view | - |
| `/planner/ideas` | `Planner/Ideas.tsx` | Content ideas, queue to writer | Ideas |

### Writer

| Route | File | Description | Tab |
|-------|------|-------------|-----|
| `/writer` | → `/writer/tasks` | Redirect | - |
| `/writer/tasks` | `Writer/Tasks.tsx` | Task queue, content generation | Queue |
| `/writer/drafts` | `Writer/Drafts.tsx` | Draft content listing | Drafts |
| `/writer/content/:id` | `Writer/ContentView.tsx` | Content detail view (read-only) | - |
| `/writer/images` | `Writer/Images.tsx` | Image management by content | Images |
| `/writer/review` | `Writer/Review.tsx` | Review queue (status=review) | Review |
| `/writer/approved` | `Writer/Approved.tsx` | Approved content (status=approved/published) | Approved |

**v1.2.0 Changes:**
- Renamed "Published" to "Approved" page
- Legacy route `/writer/published` redirects to `/writer/approved`
- ThreeWidgetFooter added to Tasks, Content pages

### Automation

| Route | File | Description |
|-------|------|-------------|
| `/automation` | `Automation/Dashboard.tsx` | 7-stage pipeline, schedule config, run controls |

### Linker (Optional Module)

| Route | File | Description |
|-------|------|-------------|
| `/linker` | → `/linker/content` | Redirect |
| `/linker/content` | `Linker/Content.tsx` | Content list for internal linking |
| `/linker/dashboard` | `Linker/Dashboard.tsx` | Not exposed in navigation |

### Optimizer (Optional Module)

| Route | File | Description |
|-------|------|-------------|
| `/optimizer` | → `/optimizer/content` | Redirect |
| `/optimizer/content` | `Optimizer/Content.tsx` | Content list with optimization scores |
| `/optimizer/preview/:id` | `Optimizer/AnalysisPreview.tsx` | Not linked from UI |
| `/optimizer/dashboard` | `Optimizer/Dashboard.tsx` | Not exposed in navigation |

---

## ACCOUNT Routes

### Notifications

| Route | File | Description |
|-------|------|-------------|
| `/account/notifications` | `account/NotificationsPage.tsx` | Full notifications history with filters and bulk actions |

**Features:**
- Filter by severity (info/success/warning/error)
- Filter by notification type (AI operations, WordPress sync, credits, etc.)
- Filter by read status (all/unread/read)
- Filter by site
- Filter by date range (from/to)
- Mark individual notifications as read
- Mark all as read (bulk action)
- Delete individual notifications
- Click notification to navigate to related page
- Real-time unread count badge

**v1.2.2 Changes:**
- NEW page created with full filtering capabilities
- Linked from NotificationDropdown "View All Notifications" button
- Added to sidebar under ACCOUNT section with unread badge

### Account Settings

| Route | File | Description |
|-------|------|-------------|
| `/account/settings` | `account/AccountSettingsPage.tsx` | 3 tabs: Account, Profile, Team |

**Tab Structure:**
- **Account**: Organization name, billing address, tax ID
- **Profile**: Name, email, phone, timezone, language, notifications, security (password change modal)
- **Team**: Team member list, invite, remove

**v1.1.6 Changes:**
- Profile tab loads from auth store user data
- Added Change Password modal with validation
- Uses `/v1/auth/change-password/` endpoint

### Plans & Billing

| Route | File | Description |
|-------|------|-------------|
| `/account/plans` | `account/PlansAndBillingPage.tsx` | 3 tabs: Plan, Upgrade, History |

**Tab Structure:**
- **Current Plan**: Plan details, features, credits, renewal date
- **Upgrade Plan**: Pricing table, plan comparison
- **History**: Invoices, payments, payment methods

**v1.1.6 Changes:**
- Added cancellation confirmation modal (prevents accidental cancellations)

### Usage

| Route | File | Description |
|-------|------|-------------|
| `/account/usage` | `account/UsageAnalyticsPage.tsx` | 3 tabs: Limits, Credit History, API Activity |

**Tab Structure:**
- **Your Limits & Usage**: Hard + monthly limits with usage bars
- **Credit History**: Transaction log
- **API Activity**: Operations by type (using real analytics data)

**v1.1.6 Changes:**
- Fixed fake API Activity data - now shows real `usage_by_type` data
- Removed hardcoded placeholder values

### AI Models (Admin Only)

| Route | File | Description |
|-------|------|-------------|
| `/settings/integration` | `Settings/IntegrationPage.tsx` | OpenAI, Runware config, image testing, site integrations |

---

## HELP Routes

| Route | File | Description |
|-------|------|-------------|
| `/help` | `Help/Help.tsx` | Documentation, FAQ, support CTAs |

**v1.1.7 Changes:**
- Fixed support buttons (now mailto: links)
- Added Dashboard, Setup, Account & Billing documentation sections
- Expanded FAQ with credits, billing, WordPress, automation topics
- Deleted placeholder pages: Documentation.tsx, SystemTesting.tsx, FunctionTesting.tsx

**Documentation Sections:**
- Getting Started (Quick Start, Workflow Overview)
- Dashboard (Metrics, Pipeline, Setup Checklist)
- Setup Module (Add Keywords, Content Settings, Sites)
- Planner Module (Keywords, Clusters, Ideas)
- Writer Module (Tasks, Content, Images)
- Automation Setup
- Account & Billing (Account Settings, Plans, Usage)
- FAQ (~28 questions)

---

## Legacy Redirects

These routes redirect to their new locations:

| Old Route | Redirects To |
|-----------|--------------|
| `/team` | `/account/settings` |
| `/profile` | `/account/settings` |
| `/import-export` | `/account/settings` |
| `/billing/overview` | `/account/plans` |
| `/billing/credits` | `/account/plans` (separate page exists at `Billing/CreditPurchase.tsx`) |
| `/billing/history` | `/account/plans` |
| `/publishing` | `/account/content-settings` |

---

## Page File Locations

```
frontend/src/pages/
├── account/
│   ├── AccountSettingsPage.tsx     # Account, Profile, Team tabs
│   ├── ContentSettingsPage.tsx     # Content Gen, Publishing, Images tabs
│   ├── PlansAndBillingPage.tsx     # Plan, Upgrade, History tabs
│   ├── UsageAnalyticsPage.tsx      # Limits, Credit History, API tabs
│   ├── UsageLimits.tsx             # Limits tab component
│   └── CreditActivity.tsx          # Credit History tab component
├── AuthPages/
│   ├── SignIn.tsx
│   ├── SignUp.tsx
│   ├── ForgotPassword.tsx
│   ├── ResetPassword.tsx
│   └── VerifyEmail.tsx
├── Automation/
│   └── Dashboard.tsx
├── Billing/
│   └── CreditPurchase.tsx
├── Dashboard/
│   └── Home.tsx
├── Help/
│   └── Help.tsx                    # Main help page with docs, FAQ
├── Linker/
│   ├── Content.tsx
│   └── Dashboard.tsx               # Not exposed
├── Optimizer/
│   ├── Content.tsx
│   ├── AnalysisPreview.tsx         # Not linked
│   └── Dashboard.tsx               # Not exposed
├── Planner/
│   ├── Keywords.tsx
│   ├── Clusters.tsx
│   ├── ClusterView.tsx
│   └── Ideas.tsx
├── Settings/
│   └── IntegrationPage.tsx         # AI Models (admin)
├── Setup/
│   └── IndustriesSectorsKeywords.tsx  # Add Keywords page
├── Sites/
│   ├── List.tsx                    # Site listing
│   ├── Dashboard.tsx               # Site overview + checklist
│   └── Settings.tsx                # Site configuration
├── Thinker/
│   ├── Prompts.tsx
│   ├── AuthorProfiles.tsx
│   ├── Strategies.tsx              # Coming Soon
│   └── ImageTesting.tsx            # Coming Soon
└── Writer/
    ├── Tasks.tsx
    ├── Drafts.tsx
    ├── ContentView.tsx
    ├── Images.tsx
    ├── Review.tsx
    └── Approved.tsx           # Renamed from Published.tsx (v1.2.0)
```

---

## Route Guards

### PrivateRoute
- Checks `authStore.isAuthenticated`
- Redirects to `/login` if not authenticated
- Stores intended destination for post-login redirect

### AdminRoute
- Requires `user.role === 'admin'` or `user.is_staff === true`
- Used for: Thinker module, AI Models page

### Module-Based Visibility
- Sidebar items hidden via `moduleStore.isModuleEnabled()`
- Routes still accessible via direct URL (no server-side blocking)

---

## Navigation Structure (Sidebar)

```
Dashboard
├── SETUP
│   ├── Add Keywords
│   ├── Content Settings
│   ├── Sites [if site_builder enabled]
│   └── Thinker [admin only, if thinker enabled]
├── WORKFLOW
│   ├── Planner [if planner enabled]
│   │   └── In-page: Keywords → Clusters → Ideas
│   ├── Writer [if writer enabled]
│   │   └── In-page: Queue → Drafts → Images → Review → Approved
│   ├── Automation [if automation enabled]
│   ├── Linker [if linker enabled]
│   └── Optimizer [if optimizer enabled]
├── ACCOUNT
│   ├── Account Settings (Account → Profile → Team)
│   ├── Plans & Billing (Plan → Upgrade → History)
│   ├── Usage (Limits → Credit History → API Activity)
│   └── AI Models [admin only]
└── HELP
    └── Help & Docs
```

---

## Known Issues (from Audit)

1. **Linker/Optimizer Dashboards** exist but not exposed in navigation
2. **Help sub-pages** are placeholders
3. **ContentView** is read-only (no editing capability)
4. Legacy redirects may cause confusion

See `/PRE-LAUNCH-AUDIT.md` for complete issue list.