MVP SaaS Support Dashboard (Next.js) — Inbox, SLA Warnings, AI Summaries, Notes, Admin Settings

This execution plan targets a hackathon MVP that demos clearly: an agent opens the Inbox, immediately sees SLA risk via warning indicators, clicks into a ticket, reads an AI-written summary, adds internal notes, and uses Admin Settings to tune SLA thresholds and AI behavior. We start by fixing scope and the minimal data model to avoid enterprise creep. We then establish the Next.js UI shell and a local-first persistence layer (SQLite + Prisma) to keep iteration fast and the demo reliable. Route handlers provide a clean API boundary so UI work can proceed independently. Core build focus is the Inbox workflow and Ticket Detail experience. SLA logic is implemented as shared utilities to ensure consistent indicators and to support future real-time updates. AI summaries are built with a provider abstraction and a deterministic fallback so the demo works even without external credentials. Admin Settings gives live control over the demo (SLA thresholds and AI toggles) without building full user management. Finally, we polish UX (loading states, toasts, optimistic updates), add minimal tests to de-risk key logic, and leave small, well-labeled extension points for real-time and RBAC without implementing them. The result is a practical, demo-ready support dashboard that’s architected to evolve while staying focused for the hackathon.

In-scope: Inbox (filters/search/SLA indicator/priority/assignee/last activity), Ticket Detail (messages, AI summary, internal notes CRUD, basic actions), Admin Settings (SLA thresholds per priority, warningRatio default 0.8, business hours stub, AI toggle/provider stub), local persistence (JSON or SQLite TBD) with seed data, CRUD route handlers (tickets/notes/settings/ai summary), responsive UI with component library TBD. Out-of-scope: realtime, real auth/RBAC (stub via header/query), multi-tenant/billing/SSO/audit, full-text search/analytics/integrations, complex SLA calendars. Demo (4 min): show Inbox urgency (OK/Warn/Breached), open WARNING ticket, generate/read AI summary, add internal note + assign + set Pending, adjust P2 SLA in Admin and see immediate SLA changes, toggle AI summaries off and confirm disabled UI.

Entities: Ticket(id, subject, requester{name,email}, status open|pending|resolved|closed, priority p1|p2|p3, createdAt, lastReplyAt, dueAt, assigneeId|null, tags[], channel email|web|chat; derived: slaState ok|warning|breached, slaProgress, lastActivityAt); Message(id,ticketId,createdAt,authorType customer|agent|system,authorName,body,attachments[]); Note(id,ticketId,createdAt,authorId,body); SLAConfig(id='default',updatedAt,warningRatio,thresholdMinutesByPriority{p1,p2,p3},businessHoursMode off|stub); AIConfig(id='default',updatedAt,enabled,provider mock|openai,model?); UserRole(userId,role admin|agent|viewer). SLA computation: elapsedMs=now-createdAt, totalMs=dueAt-createdAt, progress=elapsedMs/totalMs; ok if progress<warningRatio, warning if warningRatio<=progress<1, breached if progress>=1; defaults warningRatio=0.8, thresholds p1=60m p2=240m p3=1440m; edge cases: totalMs<=0 => breached and log warning.

Planned spec outputs to create next: docs/mvp-scope.json (MVP Scope + Demo Script) and docs/domain-model.json (Domain Model + SLA Rules).

Bootstrapped Next.js App Router + TypeScript with Tailwind and shadcn/ui (CSS variables theme). Added ESLint/Prettier conventions. Implemented AppShell (TopNav + SideNav) and stub pages for /inbox and /admin, plus UI primitives and EmptyState/Skeleton patterns.

app/layout.tsx app/globals.css app/page.tsx app/inbox/page.tsx app/admin/page.tsx components/shell/app-shell.tsx components/shell/top-nav.tsx components/shell/side-nav.tsx components/ui/button.tsx components/ui/badge.tsx components/ui/table.tsx components/ui/skeleton.tsx components/empty-state.tsx lib/nav.ts lib/utils.ts public/placeholder.svg tailwind.config.ts postcss.config.js next.config.ts tsconfig.json .eslintrc.json .prettierrc .prettierignore

Routes: - /: landing/redirect to Inbox; AppShell + CTA/link - /inbox: primary workflow; AppShell + placeholder table + empty/skeleton patterns - /admin: settings stub; AppShell + placeholder sections Layout conventions: - AppShell: CSS grid; desktop fixed sidebar; mobile collapsible/drawer; sticky top nav; scrollable content - Design tokens: Tailwind + CSS variables (background/foreground, primary, muted, border, ring), shadcn radius - Component usage: EmptyState for no results; Skeleton 5–8 rows while loading; Badge variants for SLA/tags; Table for inbox list; Button for primary actions

1) Initialized Next.js app with App Router + TypeScript 2) Configured Tailwind CSS and shadcn/ui with CSS variables theme 3) Added ESLint + Prettier + prettier-plugin-tailwindcss 4) Created AppShell (TopNav + SideNav) and wired into app/layout.tsx 5) Added stub pages for /inbox and /admin using shared shell 6) Added UI primitives (Button, Badge, Table, Skeleton) and EmptyState component 7) Added nav model (lib/nav.ts) for consistent sidebar items and future role filtering

package.json: added @prisma/client dependency and prisma devDependency; added scripts prisma:generate, prisma:migrate:dev, prisma:studio, db:seed.

.env.example: set DATABASE_URL=file:./dev.db.

prisma/schema.prisma: enums TicketStatus, TicketPriority, SlaState, MessageDirection, UserRole. Models: User (stub), Ticket (SLA timestamps, aiSummary fields, optional assignee), Message (direction + body + metadataJson), Note (internal notes), Settings (single-row id=1 with SLA + AI config). Includes indexes on status/lastMessageAt/priority and ticketId/createdAt where relevant.

prisma/seed.ts: upserts Settings id=1; creates Admin + Agent; seeds 8 tickets spanning OK/WARNING/BREACHED SLA scenarios, statuses and priorities; creates 2–6 messages per ticket with realistic inbound/outbound threads; adds ~5 internal notes; precomputes aiSummary on a subset.

src/server/db.ts: exports singleton PrismaClient (cached on globalThis in dev) and optional withPrisma helper for testability.

Repos in src/server/repos/* keep Prisma queries out of handlers (tickets/messages/notes/settings). Services: sla.service.ts computes OK/WARNING/BREACHED using Settings.slaWarningRatio and dueAt timestamps; inbox.service.ts returns normalized inbox rows with SLA states so UI doesn’t need Prisma shapes.

Ticket timestamps enable deterministic SLA computations without background jobs. Settings uses a fixed id=1 to keep MVP simple. User is a stub for future RBAC/assignee/notes attribution. Seed data includes obvious SLA-state rows and some prefilled aiSummary to demonstrate the summary panel before AI wiring.

Routes: GET /api/tickets (filter/sort/paginate + SLA indicators), GET /api/tickets/:id (detail + messages + notes + SLA + AI fields), POST /api/tickets/:id/notes (create internal note), GET/PUT /api/settings (singleton settings read/update), POST /api/tickets/:id/summary (generate/refresh AI summary; mock-first for demo). Cross-cutting: zod validation, JSON envelope {success,data,error,meta}, explicit status codes, ISO dates, requestId logging.

app/api/tickets/route.ts (GET) app/api/tickets/[id]/route.ts (GET) app/api/tickets/[id]/notes/route.ts (POST) app/api/settings/route.ts (GET, PUT) app/api/tickets/[id]/summary/route.ts (POST) lib/api/response.ts (envelope + error mapping) lib/api/validators.ts (shared zod schemas) lib/api/log.ts (request-scoped logging helper)

Envelope: { success: boolean, data: any|null, error: {code,message,details?}, meta? }. Endpoints cover tickets list/detail, note creation, settings get/update, summary generate. Error codes: BAD_REQUEST, NOT_FOUND, METHOD_NOT_ALLOWED, INTERNAL_ERROR. Validation: zod, numeric coercion (limit/settings), 400 w/ flattened fieldErrors. Logging: crypto.randomUUID requestId; log {requestId, route, method, outcome, ms}; errors log {requestId, route, errorCode, message}.

Tickets list: Prisma query with optional filters, assignee join, _count for messages/notes; SLA computed via SLA service using Settings.slaPolicyMinutes + slaWarningRatio; keep limit <=200. Ticket detail: fetch ticket + messages + notes (+ authors), compute SLA, include aiSummary fields. Notes create: validate ticket exists, create note, return note + author. Settings: singleton GET/PUT; PUT partial update with zod bounds; upsert defaults if missing. Summary: demo/mock generates deterministic summary from recent messages and persists aiSummary + aiSummaryUpdatedAt.

Client-driven data grid that reads query params (status/assigneeId/sort), calls GET /api/tickets, and renders a table/list with SLA indicator badges, filters, sorting, and loading/empty/error states.

InboxFilters (components/inbox/InboxFilters.tsx): status/assignee/sort selects; updates URL search params. SlaIndicatorBadge (components/inbox/SlaIndicatorBadge.tsx): color-coded OK/Warn/Breach badge with tooltip. InboxTable (components/inbox/InboxTable.tsx): clickable rows, strong subject column, SLA column right-aligned. InboxLoadingSkeleton (components/inbox/InboxLoadingSkeleton.tsx): skeleton rows while loading.

InboxRow (lib/types/inbox.ts): includes ticket fields and sla {state, dueAt, minutesRemaining}. inboxQuerySchema (lib/validation/inboxQuery.ts): validates/normalizes status, assigneeId, sort (newest|oldest|sla_risk). useInboxSearchParams (components/inbox/useInboxSearchParams.ts): reads/writes URL params for shareable demo links.

Uses GET /api/tickets with query params: status, assigneeId, sort. Expects { ok: true, data: { items: InboxRow[], meta: { total } } }. Assignee filter options may be derived from returned items for MVP.

Columns: Customer, Subject (bold + muted id), Status badge, Assignee (or Unassigned), Last activity (relative + exact tooltip), SLA badge (+ minutes remaining when available). Filters: status (default all), assigneeId (default all; derived from results). Sorting: newest, oldest, sla_risk (breach>warn>ok). States: loading skeleton + disabled filters; empty state with clear-filters CTA; inline error banner with retry.

Ticket detail page with conversation timeline + metadata (server-rendered) and sidebar panels for AI summary + internal notes (client, interactive).

Server components: TicketDetailPage (fetch + layout + skeleton stability), MessageTimeline (chronological messages with role styling + timestamps), TicketMetaCard (subject/status/priority/requester + SLA state + back link w/ preserved query). Client components: AiSummaryCard (shows summary + regenerate via POST /api/tickets/:id/ai-summary with loading/error; keep old summary until new arrives), InternalNotesPanel (notes list + add form; optimistic insert with temp id; reconcile/rollback on success/failure).

Ticket detail: GET /api/tickets/:ticketId (or direct repo in RSC), includes ticket fields + messages + optional notes; cache=no-store for MVP. AI refresh: POST /api/tickets/:ticketId/ai-summary returns updated aiSummary + timestamp; local component state. Note create: POST /api/tickets/:ticketId/notes { body } returns created note.

Inbox->detail uses <Link prefetch>; preserve search/sort/filter via querystring pass-through; back link returns to /inbox with same params. Perceived speed via loading.tsx skeletons; AI summary and notes hydrate independently. A11y: readable message bubbles, wrapping text, labeled textarea, aria-busy on submit; empty states for missing summary/notes.

Suggested files: app/inbox/[ticketId]/page.tsx, loading.tsx, components/{MessageTimeline,TicketMetaCard,AiSummaryCard,InternalNotesPanel}. Helper: lib/url/preserveInboxQuery.ts. Optimistic notes: insert temp note (temp_<id>) immediately, clear textarea, POST; replace temp on success; rollback + restore text on failure. AI regen: disable button while pending, show spinner text, keep old summary visible, update on success, show error on failure.

Status: conceptually_completed. Built AIProvider interface with OpenAI-compatible implementation selected via env vars and a deterministic fallback summarizer when no API key is present. Summaries persist on Ticket (aiSummary, aiSummaryUpdatedAt, aiSummarySource, aiSummaryModel) enabling consistent demos without external AI.

File: src/services/ai/types.ts Defines SummarySource ('ai'|'fallback'), TicketSummaryInput/Result, and AIProvider interface.

File: src/services/ai/providers/openaiCompatibleProvider.ts Calls {baseUrl}/chat/completions with model/temperature/messages; timeout via AbortController; parses choices[0].message.content; returns {summary, source:'ai', model, tokensUsed, generatedAt}.

File: src/services/ai/providers/fallbackSummarizer.ts Deterministic heuristic: sorts messages, uses first/last customer + last agent message; picks first sentence + truncates; emits multiline summary with recommended next action; returns source:'fallback'.

File: src/services/ai/index.ts getAIProvider() uses AI_API_KEY/OPENAI_API_KEY to choose OpenAICompatibleProvider; otherwise returns FallbackSummarizer. Supports overrides: AI_BASE_URL, AI_MODEL, AI_TIMEOUT_MS.

File: src/services/tickets/summaryService.ts Loads ticket+messages; calls provider.summarizeTicket; updates prisma Ticket fields: aiSummary, aiSummarySource, aiSummaryModel, aiSummaryUpdatedAt; returns updated ticket, provider name, and result.

File: prisma/schema.prisma Adds aiSummary, aiSummaryUpdatedAt, aiSummarySource, aiSummaryModel to Ticket model.

File: src/app/api/tickets/[ticketId]/summary/route.ts POST validates ticketId; runs generateAndPersistTicketSummary; responds with persisted fields plus provider and tokensUsed; returns 500 with error message on failure.

File: .env.example Documents AI_API_KEY (fallback if unset), AI_BASE_URL, AI_MODEL, AI_TIMEOUT_MS.

1) No AI_API_KEY: Regenerate summary quickly updates Ticket summary with source=fallback and stable output. 2) With AI_API_KEY: Uses OpenAI-compatible endpoint and sets source=ai and model=<AI_MODEL>. 3) Inbox/ticket detail show summary + timestamp; provider errors return 500 so UI can show an error toast.

Inputs: createdAt (Date|ISO string), priority (LOW|NORMAL|HIGH|URGENT), settings { slaMinutesLow/Normal/High/Urgent, warningRatio default 0.8 }, now optional (injectable). Outputs: dueAt (Date), msTotal, msElapsed, msRemaining (negative if breached), state (OK|WARNING|BREACHED), progress (elapsed/total, not upper-clamped). Rules: dueAt = createdAt + priority threshold; BREACHED if now >= dueAt; WARNING if progress >= warningRatio; else OK. Fail-soft defaults if settings invalid: use NORMAL threshold and warningRatio=0.8.

New: src/lib/sla.ts (computeDueAt, computeSlaStatus, formatTimeRemaining, getSlaVisual, types); src/lib/sla.visual.ts (SLA_VISUAL mapping, getSlaVisual). Updated: src/server/services/slaService.ts (consume/re-export shared utilities); src/app/inbox/components/SlaBadge.tsx (use shared visuals + show remaining); src/app/api/tickets/route.ts and src/app/api/tickets/[ticketId]/route.ts (include dueAt/state/msRemaining computed via shared utilities).

OK: badgeVariant=secondary, class='bg-emerald-50 text-emerald-700 border-emerald-200', icon=CheckCircle2. WARNING: badgeVariant=secondary, class='bg-amber-50 text-amber-800 border-amber-200', icon=AlertTriangle. BREACHED: badgeVariant=destructive, class='bg-red-50 text-red-700 border-red-200', icon=AlertOctagon.

src/lib/__tests__/sla.test.ts covers: dueAt by priority threshold; OK when below warningRatio; WARNING at warningRatio boundary; BREACHED when now==dueAt; breached yields negative msRemaining; all tests inject now for determinism.