# CRM UI Specification

**Product:** Torbat CRM (Enterprise Sales CRM)  
**Version:** Phase 6.3 frontend integration  
**Date:** 2026-07-26

## Product identity

| Aspect | Choice |
|--------|--------|
| Accent | `--crm-accent` indigo (`#6366f1` light / `#818cf8` dark) |
| Tone | Professional, minimal, low noise, desktop-first |
| Language | RTL-first (Persian labels) |
| Shell | Collapsible sidebar groups, mobile drawer, dark mode toggle |

Distinct from Accounting (sky/operational), Beauty (rose/warm), Healthcare (teal/clinical).

## Architecture

```
app/crm/                    # Thin routes only (page, layout, loading, error)
modules/crm/                # All business UI
  services/crm-api.ts       # Typed client → /api/crm BFF → :8003
  components/               # Shell, CRUD factory, breadcrumbs
  design-system/            # CrmTablePage, CrmStatGrid, CrmStatusChip
  features/sales/           # Page implementations
  constants/portals.ts      # Navigation
```

## Page inventory (41 routes)

All pages under `/crm/sales/*` unless noted.

| Area | Pages | Backend |
|------|-------|---------|
| Hub | `/crm/hub` | `/health` |
| Dashboards | overview, sales, pipeline, leads, activities, calendar | List aggregates |
| Entities | customers, companies, contacts, leads | Real CRUD APIs |
| Sales | deals, kanban, pipelines, quotes | opportunities, pipelines, quotes |
| Collaboration | activities, tasks, meetings, calls, emails, notes, timeline, documents | Phase 6.3 APIs |
| Marketing | tags | tags API; campaigns/segments scoped notice |
| Data | custom-fields, import, export | custom-fields; import N/A; export client CSV |
| Insights | reports, analytics, automation | computed / scoped |
| Admin | notifications, roles, permissions, integrations, api-keys, audit-logs, settings, health, capabilities | partial + static |

## Standard page contract

Every list page includes:

- `CrmPageLoader` / skeleton via `CrmTablePage`
- `CrmPageError` with 403 permission state
- `EmptyState` with create action
- Search (client-side filter)
- Sort dropdown (client-side)
- Pagination (client-side slice; server uses page/page_size fetch)
- Bulk selection + bulk delete where API supports
- Dialog create + Drawer edit + ConfirmDialog delete
- Toast via Sonner
- Breadcrumb via `CrmBreadcrumbs`

## Keyboard shortcuts

| Chord | Target |
|-------|--------|
| `g` then `o` | Overview dashboard |
| `g` then `l` | Leads |
| `g` then `c` | Contacts |
| `g` then `d` | Deals |
| `g` then `k` | Kanban |

## Out of scope (honest UI)

Pages show `CrmScopeNotice` instead of fake data:

- Campaigns, Segments, Import, Automation, Integrations, API Keys
- Global audit (per-entity audit only)
- `/capabilities` (health version only)

## API conventions

- Header: `Authorization: Bearer`, `X-Tenant-ID`
- Soft delete: `POST /{id}/delete` (leads, contacts, organizations)
- List: `page`, `page_size` — no server search/sort/filter
- Deals = `opportunities`; Customers = contacts + organizations

## Related

- [crm-component-map.md](./crm-component-map.md)
- [crm-routing-map.md](./crm-routing-map.md)
- [crm-validation-report.md](./crm-validation-report.md)
- [crm-responsive-report.md](./crm-responsive-report.md)