support_backend/docs/08-frontend-architecture.md

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) 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