saqib mirandClaude Sonnet 5
f475a55a53
Full system blueprint (docs 01-10): product vision, integration & security, AI support architecture, ticketing & problem management, orchestration/SLA/escalation, database schema, backend/frontend architecture, testing/observability/CI-CD, and the implementation roadmap. This is the pre-implementation design reference the codebase is being built against. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
149 lines
4.0 KiB
Markdown
149 lines
4.0 KiB
Markdown
# 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 |
|