# 08 — Frontend Architecture

## 1. Technology stack

Next.js (App Router) · TypeScript · Tailwind CSS · shadcn/ui-style components · Lucide icons · TanStack Query · Zustand (where needed) · React Hook Form · Zod · Playwright · Vitest

## 2. Frontend source structure

```
src/app
src/features
src/components
src/lib
src/hooks
src/stores
src/providers
src/types
src/constants
src/theme
src/styles
```

Route groups:

```
(customer)
(support)
(admin)
(public)
```

Feature modules are self-contained:

```
features/tickets/
├── api
├── components
├── hooks
├── schemas
├── types
├── constants
└── index.ts
```

**Do not create giant global business components** — logic and UI for a feature live inside that feature's folder.

## 3. Customer frontend

Lives inside the SaaS/product context — the customer never leaves their product to get support.

**Support Center** is the main surface, with areas:
- AI Support
- My Cases / Tickets
- Support History
- Optional resources

Primary journey:

```
Problem → AI analysis → Knowledge found → Guided steps → Customer action
       → Verification → Resolved
                      (if unresolved) → Human Support
```

### Support Center home

Communicates: *"How can we help you?"* The customer can describe a problem, start AI support, view existing cases, or see an active case. A case/ticket card shows: case ID, problem, product, current stage, progress, AI status, and human-support status when applicable.

### AI Support UI — not a ChatGPT clone

The interface must visibly communicate each stage, using clear cards/progress indicators, not just a scrolling chat log:

1. Problem understanding
2. Product analysis
3. Knowledge search
4. Diagnosis
5. Recommended solution
6. Guided steps
7. Customer action
8. Verification
9. Resolve or escalate

Example card content:

```
AI analyzed:        PDF conversion failure
Problem detected:   LAYOUT_PARSE_042
Likely cause:       Layout parser failure
Recommended:        Enable fallback parser

Guided steps:
1. Open Conversion Settings
2. Open Advanced
3. Enable fallback parser
4. Retry conversion
5. Verify output

[ I completed this step ]  [ I need help ]  [ Problem solved ]  [ Not solved ]
```

### What the customer never sees

Internal support hierarchy, internal assignment algorithms, agent workload, internal escalation rules, internal notes, internal routing logic.

## 4. Support agent frontend (internal)

A distinct experience from the customer app. Main areas:

- Dashboard
- My Queue
- All Tickets
- Problems
- SLA Monitoring
- Escalations
- Knowledge
- Reports

**Agent ticket workspace** shows: customer, tenant, product, problem, AI summary, diagnosis, troubleshooting history, conversation, investigation, root cause, solution, verification, resolution, SLA, assignment, escalation history.

**Critical UX requirement:** the agent continues from the AI's context — they never restart diagnosis from zero. The AI hand-off summary (see [03](./03-ai-support-architecture.md#10-escalation-trigger-conditions-ai--human)) should be the first thing the agent reads.

## 5. Admin frontend

Configuration surface. Areas: Products, Categories, Problem Types, Priorities, Support Hierarchy, Teams, Agents, Skills, Routing Rules, Assignment Rules, SLA Policies, Escalation Policies, Knowledge, Runbooks, Reports, Audit, Settings.

**None of these configuration values may be hardcoded** in frontend or backend source — the admin UI is how the business actually changes behavior.

## 6. Real-time updates

Use WebSocket or SSE so the customer/agent sees updates without refreshing:

- AI analyzing
- AI found knowledge
- AI generated solution
- AI waiting for customer
- Ticket assigned
- Agent replied
- SLA warning / SLA breached
- Escalation
- Ticket resolved

## 7. UX principle recap by persona

| Persona | Principle |
|---|---|
| Customer | Simple, guided, trustworthy, product-aware |
| Agent | Information-dense, fast, operational, context-rich |
| Admin | Configurable, visual, rule-driven, auditable |