Blueprint

Dental SaaS app architecture

Blueprint page for the frontend app structure, route map, layouts, pages, state model, and UI system.

Open workspace routes
Routes in map18Public, auth, workspace, and admin
Widget modules6Dashboard composition units
Onboarding steps6Launch path from register to billing
State slices5Server and client responsibilities

App structure

Folder structure

Recommended feature split for the current Next App Router codebase.

src/appRouting boundary for public, auth, workspace, and admin experiences.
(auth) · group(workspace) · group(admin) · grouppricing/page.tsx · pageapi/v1 · group
src/featuresShared feature packages kept outside app routing.
app-shell · featuredashboard · featureinbox · featureonboarding · featuredesign-system · feature
WorkspaceStateProviderClient-only UI state for theme, filters, and selected conversation context.

Route map

Pages and layouts

Concrete URL map and layout ownership.

PathLabelLayoutRole
/pricingPricingpublicmanager
/app-architectureApp architecturepublicmanager
/loginLoginauthmanager
/registerRegister clinicauthmanager
/dashboardDashboardworkspacemanager
/setupSetupworkspaceadmin
/queueWork queueworkspacemanager
/alertsAlertsworkspacemanager
/leadsLeadsworkspacemanager
/inboxInboxworkspacemanager
/inbox/[conversationId]Conversation detailworkspacemanager
/automationsAutomationsworkspaceadmin
/integrationsIntegrationsworkspaceadmin
/aiAI insightsworkspacemanager
/reportsReportsworkspaceowner
/billingBillingworkspaceowner
/complianceComplianceworkspaceadmin
/platformPlatformadminsuper_admin

State

State management

Client versus server responsibility split.

Session and tenant scopeServer bootstrap

Resolve active user, role, organization, and tenant-scoped state snapshot. Lifetime: Per request.

Workspace preferencesWorkspaceStateProvider

Track theme mode, dashboard range, and inbox density. Lifetime: Per browser tab.

Operational filtersWorkspaceStateProvider

Lead status filter, selected conversation, and current onboarding focus. Lifetime: Per route session.

Canonical business dataRoute handlers + server reads

Leads, conversations, integrations, contracts, billing, and audit records. Lifetime: Persistent in storage.

Mutation feedbackClient route actions

Notice banners, pending actions, and optimistic interaction affordances. Lifetime: Ephemeral UI state.

Data

Data fetching strategy

Preferred fetching model for Next 16 App Router.

Server layouts and pagesDirect server-side reads with request-scoped memoization.

Use async Server Components and cache(async) bootstrap helpers that read cookies() and readAppState(). Keeps secrets and tenant authorization on the server.

Shared route bootstrapSingle tenant-scoped snapshot per request.

Workspace layout resolves session, scopes AppState, and derives summary counts once. Avoids re-fetching the same state in each child component.

Client interactivityLocal UI state only.

Theme, filters, and selected conversation stay inside a client provider instead of duplicating server data. Minimizes client bundle pressure and hydration work.

MutationsPOST/PATCH through Route Handlers with follow-up refresh.

Client actions call /api/v1 endpoints; server remains the source of truth for changed state. Good fit for inbox replies, lead status changes, and integration setup.

StreamingRoute-group loading states and component-level suspense when needed.

Workspace routes use loading.tsx; long-running widgets should later move behind Suspense boundaries. Matches Next App Router recommendations for request-time data.

Design system

UI components and basics

Reusable primitives and token rules for the app shell.

Surfaces

All panels use the same surface, line, and shadow tokens for a consistent SaaS shell.

Hierarchy

Eyebrows, h1 titles, and compact labels separate navigation, decision-making, and dense data.

Status language

Accent for healthy, amber for attention, red for risk, with pill badges across modules.

Density

Cards, tables, rails, and inspectors share one spacing rhythm to keep the dashboard readable.

backgroundsurfacesurface-strongsurface-mutedinkmutedlineaccentred

Dashboard

Dashboard widgets

Widget inventory for the overview screen.

Recovery overviewRevenue operations

New, unanswered, at-risk, booked, and lost lead totals with conversion context.

Response SLAFront desk manager

Average reply time, no-response pressure, and alert thresholds.

Source performanceClinic owner

Conversion and volume by Telegram, web form, and future channels.

Manager loadOperations admin

Assigned queue pressure and booked outcomes by staff member.

Integration healthPlatform setup

Clinic DB, Stripe, and intake provider readiness.

Plan usageBilling

Messages, AI runs, integration count, and seat pressure.

Inbox

Inbox structure

Three-rail inbox information architecture.

Conversation railFast scanning of active threads and SLA pressure.
Lead identity and source badgeLatest inbound excerptWaiting time and risk badgeUnread and ownership signals
Thread canvasPrimary reply surface for manager work.
Chronological message bubblesSuggested replies and AI contextReply composer and send actionStatus transitions like booked or lost
Patient context drawerDecision support without leaving the inbox.
Lead status and estimated valueProvider metadata and timestampsAI summary and risk recommendationQuick actions for booking or escalation

Onboarding

Onboarding flow

Operational sequence from signup to first live sync.

Create clinic workspaceClinic owner

Route: /register. Success: Owner can sign in and sees a tenant-scoped dashboard shell.

Confirm user rolesClinic admin

Route: /setup. Success: Managers, admins, and owners match the intended operating model.

Connect intake channelsClinic admin

Route: /integrations. Success: Telegram and web form are active; Clinic DB config is saved.

Approve read-only data contractIT + clinic owner

Route: /compliance. Success: Clinic DB data access contract is approved and audit recorded.

Run first sync and validate queueOperations admin

Route: /queue. Success: Imported leads appear in queue and inbox with correct tenant scope.

Confirm billing planClinic owner

Route: /billing. Success: Billing method, payment reference, and plan limits are visible and usable.

Layouts

Layout map

Layout ownership and shell partitioning.

Root layout

Owns fonts, globals, and the shared document shell.

(auth)/layout.tsx

Owns access-entry presentation and keeps auth routes separate from workspace chrome.

(workspace)/layout.tsx

Owns tenant bootstrap, sidebar navigation, and the workspace state provider.

(admin)/layout.tsx

Owns super-admin navigation and platform-only context.

PageHeaderSurfaceCardMetricTileDetailList

Pages

Page set

High-level page inventory for the MVP app shell.

Access

/login, /register

Operate

/dashboard, /setup, /queue, /alerts, /leads, /inbox, /inbox/[conversationId]

Optimize

/automations, /integrations, /ai

Govern

/reports, /billing, /compliance, /platform

Modules

Business modules

Channel and billing touchpoints exposed as widgets or admin summaries.

AuthDashboardQueueInboxLeadsAutomationsIntegrationsAIBillingCompliancePlatform adminOnboarding
Channel setupTelegram, web form, Clinic DB adapters
Commercial layerStripe checkout, portal, usage guardrails
Tenant safetySession scope, RBAC, audit and contract visibility
Integration-driven