# UI Pages and Navigation

**Status:** v1.0 feature-complete — internal testing (Tasks 002–018).

## Implemented pages

### Market Database (`/market`) — Task 006

| Aspect | Detail |
|--------|--------|
| Layout | `src/app/market/layout.tsx` — AppShell wrapper for all `/market/*` |
| Auth | Protected (middleware) |
| Hub | `/market` — stats cards, quick links |
| Sub-nav | `MarketSubNav` on all market pages |

| Route | File | Features |
|-------|------|----------|
| `/market` | `page.tsx` | Totals: companies, people, emails, mobiles; quick links |
| `/market/companies` | `companies/page.tsx`, `companies-browser.tsx` | Search, filters, table, pagination, link to detail |
| `/market/companies/[id]` | `companies/[id]/page.tsx` | Full profile: basic info, people, contacts, service matches, campaigns, inbox replies, leads, opps, activities; quick actions |
| `/market/people` | `people/page.tsx`, `people-browser.tsx` | Search, filters, clickable names, company links, bulk add to static segment |
| `/market/people/[id]` | `people/[id]/page.tsx` | Person profile + quick actions (segment, lead, task) |
| `/market/contact-points` | `contact-points/page.tsx`, `contact-points-browser.tsx` | Linked company/person, counts, bulk add to segment |

**Removed from UI (v1.1+):** `/market/data-quality`, `/market/duplicate-reviews` — cleaning/duplicates handled in GPT preprocessing before import. MongoDB models retained for legacy data.

### Segments (`/segments`) — Task 007

| Aspect | Detail |
|--------|--------|
| Layout | `src/app/segments/layout.tsx` — AppShell wrapper |
| Auth | Protected (middleware) |
| Routes | `/segments`, `/segments/new`, `/segments/[id]`, `/segments/[id]/edit` |
| Features | Dynamic (filter dropdowns from API) or static (member picker); preview (dynamic); members list; static member manager on detail; bulk add from market lists; edit/deactivate |
| Components | `segment-form.tsx`, `static-segment-manager.tsx`, `add-to-segment-modal.tsx`, `bulk-segment-toolbar.tsx` |

### Email Templates (`/email-templates`) — Task 008

| Aspect | Detail |
|--------|--------|
| Layout | `src/app/email-templates/layout.tsx` — AppShell wrapper |
| Auth | Protected (middleware) |
| Routes | `/email-templates`, `/email-templates/new`, `/email-templates/[id]`, `/email-templates/[id]/edit` |
| Features | Create/edit/archive templates, variable extraction/validation, preview with sample data |

### Campaigns (`/campaigns`) — Task 009

| Aspect | Detail |
|--------|--------|
| Layout | `src/app/campaigns/layout.tsx` — AppShell wrapper |
| Auth | Protected (middleware) |
| Routes | `/campaigns`, `/campaigns/new`, `/campaigns/[id]`, `/campaigns/[id]/edit` |
| Features | Create draft campaign, preview recipients, generate recipients, stats and recipient table |

### Email test (`/email-test`) — Task 010

| Aspect | Detail |
|--------|--------|
| Layout | Uses `AppShell` |
| Auth | Protected (middleware) |
| Route | `/email-test` |
| Features | SMTP verify button + test email form (`to`, `subject`, `htmlContent`, `textContent`) |

### Inbox (`/inbox`) — Task 011 + Task 020

| Aspect | Detail |
|--------|--------|
| Layout | Uses `AppShell` — three-column conversation center |
| Auth | Protected (middleware) |
| Routes | `/inbox`, `/inbox?thread=:id`, `/inbox/[id]` (redirects to thread) |
| Features | Thread list with filters (unread, campaign, sequence, lead-worthy, archived), search, pagination 25/50/100, 45s auto-refresh, conversation bubbles (inbound/outbound), collapsed quoted history, reply composer, CRM side panel, AI classify, lead convert, sequence stop, archive/read, IMAP sync |
| Docs | [25-professional-inbox.md](./25-professional-inbox.md) |

### AI Status (`/ai/status`) — Task 012

| Item | Detail |
|------|--------|
| Route | `/ai/status` |
| Features | Provider availability, model, fallback flag; preview classify form (no DB write) |
| Sidebar | "حالة الذكاء" / AI Status |

### Leads (`/leads`) — Task 013

| Item | Detail |
|------|--------|
| Routes | `/leads`, `/leads/new`, `/leads/[id]` |
| Features | Search/filter list, manual create, detail with AI/reply links, status actions, create opportunity |

### Pipeline (`/pipeline`) — Task 013

| Item | Detail |
|------|--------|
| Route | `/pipeline` |
| Features | Kanban columns by opportunity stage; dropdown to move stage |

### Tasks (`/tasks`) — Task 013

| Item | Detail |
|------|--------|
| Route | `/tasks` |
| Features | Open tasks list, complete action |

### Activity feed (`/activities`) — Task 022

| Item | Detail |
|------|--------|
| Route | `/activities` |
| Files | `src/app/activities/page.tsx`, `activities-feed.tsx` |
| Features | Global CRM activity center; search; category + date filters; pagination |

### CRM profile timelines — Task 022

Company, Person, and Lead profiles include unified **Activity / Timeline** tab with summary counters, manual notes (إضافة ملاحظة), search, and category filters via `ActivityTimeline`.

### Opportunity detail (`/opportunities/[id]`) — Task 013

| Item | Detail |
|------|--------|
| Route | `/opportunities/[id]` |
| Features | Stage, probability, move stage, close won/lost, activities |

### Inbox convert — Task 013

Inbox detail AI panel: **تحويل إلى Lead** → `/api/leads/from-email-reply` (optional force).

### Imports (`/imports`) — Task 005

| Aspect | Detail |
|--------|--------|
| Files | `src/app/imports/page.tsx`, `imports-client.tsx` |
| Auth | Protected (middleware) |
| Shell | `AppShell` |
| Features | File upload; import type (auto/simple/processed); detect with auto column mapping; mapping review table + editable JSON; preview/execute without manual mapping; import history |

### Login (`/login`) — Task 003

| Aspect | Detail |
|--------|--------|
| Files | `src/app/login/page.tsx`, `src/app/login/login-form.tsx` |
| Auth | Public; authenticated users redirected to `/dashboard` (middleware) |
| Layout | Root RTL layout |
| Behavior | Credentials sign-in via `next-auth/react` `signIn`; Arabic error messages; `callbackUrl` query support |

### Notifications (`/notifications`) — Task 015

| Aspect | Detail |
|--------|--------|
| Topbar | Bell icon with unread badge and dropdown |
| Page | `/notifications` — filter, mark read, delete, open action URL |
| Dashboard | Recent notifications widget |

### Dashboard (`/dashboard`) — Task 003 / 014

| Aspect | Detail |
|--------|--------|
| Files | `src/app/dashboard/page.tsx`, `src/components/dashboard/*` |
| API | `GET /api/dashboard` |
| Auth | Protected (middleware + layout redirect) |
| Sections | KPI row; market (sectors, cities, quality, duplicates); campaign sent/open/click/reply rates; leads & pipeline value; inbox & AI intents; tasks; recent activities |
| Shell | `AppShell` with sidebar (future module links) and topbar (sign out) |
| Content | Arabic heading, session info, placeholder for upcoming CRM modules |

### Home (`/`) — Task 002

| Aspect | Detail |
|--------|--------|
| File | `src/app/page.tsx` |
| Layout | Root `src/app/layout.tsx` — `lang="ar"`, `dir="rtl"` |
| Purpose | Foundation landing until auth and app shell (Task 003+) |
| Content | App name (AR/EN), description, capability chips, current phase label, pointer to `/docs` and `/tasks` in repo |
| Navigation | No sidebar yet; not linked to runtime docs routes |

## Layout structure

- **Auth layout:** `/login` — no sidebar (implemented)
- **App shell:** `AppShell` on `/dashboard`, `/imports`, `/market/*` — sidebar + topbar
- **Root layout:** `lang="ar"`, `dir="rtl"`, `SessionProvider` (Task 003)
- **Locale:** Arabic/English toggle in settings or header (Phase 2+)

## Primary navigation

| Nav item | Route | Phase |
|----------|-------|-------|
| Dashboard | `/dashboard` | 9 |
| Market Database | `/market` | 2 (done) |
| — Companies | `/market/companies` | 2 |
| — People | `/market/people` | 2 |
| — Contact Points | `/market/contact-points` | 2 |
| Leads | `/leads` | 4 |
| Pipeline | `/pipeline` | 4 |
| Segments | `/segments` | 4 |
| Campaigns | `/campaigns` | 5 (implemented prep) |
| Email Templates | `/email-templates` | 5 |
| Inbox | `/inbox` | 6 |
| Import | `/imports` | 5 (done) |
| Analytics | `/analytics` | 9 |
| Settings | `/settings` | 2 / 22 |

## Page specifications

### Dashboard (`/dashboard`) — implemented (Task 014)

- KPI cards: companies, leads, open opportunities, campaign replies, open tasks, pipeline value
- Market: top sectors/cities, high-priority companies, import count
- Campaigns: sent/opened/clicked/replied + rate bars
- Leads: temperature/status counts; opportunities by stage; estimated & weighted pipeline value
- Inbox & AI: reply status counts, hot/warm classifications, top intents
- Tasks: open, overdue, due today, completed
- Recent activities timeline (latest 15)
- Refresh button calls `/api/dashboard`

### Companies (planned — manual CRUD)

- **List** `/companies` — legacy route; prefer `/market/companies` for imported data browse
- **Detail** `/companies/[id]` — tabs: Overview, People, Contact points, Activities, Opportunities

### People (browse — implemented under Market Database)

- **List** `/market/people` — filter by company, job title, decision maker
- **Detail** `/people/[id]` — planned manual CRUD profile (deferred)

### Leads

- **List** `/leads` — kanban or table by status
- **Detail** `/leads/[id]` — qualification notes, convert action

### Pipeline (`/pipeline`)

- Kanban by opportunity stage
- Drag-and-drop stage change (Phase 4)
- Stage totals and weighted value

### Segments (`/segments`)

- List segments with member counts
- Builder UI for filters (company sector, tags, city, etc.)
- Preview count before save

### Sequences (`/sequences`) — Task 019

| Aspect | Detail |
|--------|--------|
| Layout | `src/app/sequences/layout.tsx` — AppShell wrapper (same as Campaigns) |
| Auth | Protected in middleware; sidebar item «السلاسل» |
| Routes | `/sequences`, `/sequences/new`, `/sequences/[id]`, `/sequences/[id]/edit` |
| Components | `sequences-list.tsx`, `sequence-form.tsx`, `sequence-detail-shell.tsx`, `sequence-actions.tsx` |

### Campaigns

- **List** `/campaigns` — search/filter, stats columns, actions
- **Create** `/campaigns/new` — segment + template + sender + recipient preview
- **Detail** `/campaigns/[id]` — metadata, stats cards, generated recipients, generate action, SMTP verify, send batch, send one
- **Edit** `/campaigns/[id]/edit` — editable while draft/scheduled (service guards terminal statuses)

### Templates (`/campaigns/templates`)

- List and editor with HTML preview
- Variable placeholders: `{{company.name}}`, `{{person.firstName}}`, etc.

### Inbox (`/inbox`)

- Inbox list with sync + verify buttons
- Email detail with linked campaign/company/person/message context
- Manual status actions (`new`, `ignored`, `spam`)
- AI classification panel (`AiClassificationPanel`): intent, sentiment, temperature, stage, action, summary, confidence; button "تصنيف الرد بالذكاء"

### Import (`/import`)

- Upload Excel, column mapping preview
- Validation report and batch history

### Settings (`/settings`) — Task 016

| Aspect | Detail |
|--------|--------|
| Layout | `src/app/settings/layout.tsx` — AppShell, admin guard, `SettingsNav` |
| Auth | Protected; **admin role required** (others redirect to dashboard) |
| Sidebar | Settings link admin-only |

| Route | File | Features |
|-------|------|----------|
| `/settings` | `page.tsx`, `settings-dashboard.tsx` | Hub cards |
| `/settings/users` | `users/page.tsx`, `users-settings-client.tsx` | List, create, edit, activate/deactivate, reset password |
| `/settings/mailboxes` | `mailboxes/page.tsx`, `mailboxes-settings-client.tsx` | CRUD, verify SMTP/IMAP, set default |
| `/settings/ai` | `ai/page.tsx`, `ai-settings-client.tsx`, `ai-brand-voice-settings.tsx` | Provider/model, brand voice, env key status, test classify |
| `/settings/branding` | `branding/page.tsx`, `branding-settings-client.tsx` | White-label: logos, colors, platform name, preview (sidebar/login/email) |
| `/settings/system` | `system/page.tsx`, `system-settings-client.tsx` | Language, timezone, sender defaults |
| `/settings/imports` | `imports/page.tsx`, `imports-settings-client.tsx` | Dedup threshold, match fields, auto flags |
| `/settings/data-cleanup` | `data-cleanup/page.tsx`, `data-cleanup-client.tsx` | Scope select, preview counts, confirmation phrase, execute delete |
| `/settings/cron` | `cron/page.tsx`, `cron-settings-client.tsx` | Cron & Workers: last runs, logs table, manual sync/sequence triggers |

## UI stack

- Tailwind CSS for layout and spacing
- shadcn/ui for tables, forms, dialogs, dropdowns (post Task 002)
- Responsive: desktop-first; usable on tablet

## Accessibility and i18n

- Semantic headings and form labels
- RTL: `dir="rtl"` when locale is Arabic
- Date/number formatting per locale (Saudi conventions)

## Related

- [07-leads-pipeline.md](./07-leads-pipeline.md)
- [06-campaign-system.md](./06-campaign-system.md)
- [05-email-system.md](./05-email-system.md)