graph TB
subgraph Browser["Browser (Client)"]
direction TB
subgraph Pages["Next.js Pages (App Router)"]
P_Dashboard["/dashboard"]
P_Policies["/policies"]
P_PoliciesNew["/policies/new"]
P_PoliciesId["/policies/[id]"]
P_Incidents["/incidents"]
P_Assets["/assets/[type]"]
P_Risk["/assessment"]
P_Register["/register"]
subgraph PlatformAdminPages["Platform Admin Module"]
P_PALogin["/platform-admin/login\nShared login for all admin portals"]
P_PAHub["/platform-admin\nAdmin hub dashboard"]
P_PADocs["/platform-admin/docs\nAdmin guide - renders PLATFORM_ADMIN.md"]
P_PATemplates["/platform-admin/policy-templates\nList and manage master templates"]
P_PATmplEdit["/platform-admin/policy-templates/[id]\nEditor - sections, publish, changelog"]
P_PATmplNew["/platform-admin/policy-templates/new\nCreate new draft template"]
P_PARulesPage["/platform-admin/template-rules\nCreate and manage recommendation rules"]
end
subgraph HipaaAdminPages["HIPAA Admin Module"]
P_HipaaHub["/hipaa-admin\nDashboard"]
P_HipaaCompanies["/hipaa-admin/companies"]
P_HipaaParticipants["/hipaa-admin/participants"]
P_HipaaReports["/hipaa-admin/reports"]
end
end
subgraph LayoutGuards["Client-side Layout Auth Guards"]
LG_PA[platform-admin/layout.tsx\nchecks platform_admin OR hipaa_admin\nvia onAuthStateChanged + getIdTokenResult]
LG_Hipaa[hipaa-admin/layout.tsx\nchecks hipaa_admin claim\nvia onAuthStateChanged + getIdTokenResult]
end
subgraph UIComponents["Shared UI Components (src/components/ui/)"]
UI_Button[Button]
UI_Card[Card]
UI_Dialog[Dialog]
UI_Badge[Badge]
UI_Toast[Toast / useToast]
UI_Skeleton[Skeleton]
UI_Select[Select]
UI_Textarea[Textarea]
end
subgraph FeatureComponents["Feature Components"]
subgraph PolicyComps["src/components/policies/"]
C_PolicyForm[PolicyForm]
C_PolicyEditor[PolicyEditor]
C_PolicyStatusBadge[PolicyStatusBadge]
C_TemplatePicker[TemplatePicker]
C_TemplateDiffView[TemplateDiffView]
C_TemplateUpdateBanner[TemplateUpdateBanner]
C_ApprovalCommentThread[ApprovalCommentThread]
end
subgraph AdminComps["src/components/admin/"]
C_AdminShell[AdminShell\nShared sidebar nav\nClaim-gated link sections\nSign-out clears Firebase + cookie]
end
subgraph PlatformAdminComps["src/app/platform-admin/ components"]
C_TemplateEditorForm[TemplateEditorForm\nTipTap rich-text section editor]
C_RuleBuilderForm[RuleBuilderForm\nNAICS x jurisdiction x flags form]
end
subgraph IncidentComps["src/components/incidents/"]
C_IncidentForm[IncidentForm]
C_IncidentStatusBadge[IncidentStatusBadge]
end
subgraph AssetComps["src/components/assets/"]
C_AssetTable[AssetTable]
C_AssetForm[AssetForm]
end
subgraph OnboardingComps["src/components/onboarding/"]
C_RegistrationForm[RegistrationForm\njurisdiction + businessFlags fields]
C_CompleteProfileModal[CompleteProfileModal\nskipped for admin claim holders]
end
end
subgraph Hooks["React Hooks (src/hooks/)"]
H_UseAuth[useAuth]
H_UsePermission[usePermission]
H_UseToast[useToast]
H_UseOnboarding[useOnboardingStatus\nshort-circuits if platform_admin claim]
end
subgraph Stores["Zustand Stores (src/stores/)"]
S_Auth[authStore]
S_Onboarding[onboardingStore]
end
end
subgraph Server["Server (Next.js API Routes - src/app/api/)"]
direction TB
subgraph AuthMiddleware["Middleware"]
MW_WithAuth[withAuth HOF\nverifies Firebase Bearer token\nresolves tenantId + role from Firestore]
MW_WithPlatformAdmin[withPlatformAdmin HOF\nverifies Bearer token\nchecks platform_admin Firebase claim]
MW_WithHipaaAdmin[withHipaaAdminAuth HOF\nverifies httpOnly session cookie\nchecks hipaa_admin Firebase claim]
end
subgraph PolicyRoutes["Policy Routes (withAuth)"]
R_Policies["/api/policies\nGET list / POST create"]
R_PoliciesId["/api/policies/[id]\nGET / PATCH / DELETE"]
R_Submit["/api/policies/[id]/submit POST"]
R_Approve["/api/policies/[id]/approve POST"]
R_Publish["/api/policies/[id]/publish POST"]
R_Ack["/api/policies/[id]/acknowledge POST"]
R_Diff["/api/policies/[id]/template-diff GET"]
R_Accept["/api/policies/[id]/accept-template-update POST"]
R_Dismiss["/api/policies/[id]/dismiss-template-update POST"]
R_ApprovalReq["/api/policies/[id]/approval-request GET/POST"]
R_Comment["/api/policies/[id]/approval-request/comment POST"]
R_Recommend["/api/policies/recommend GET"]
R_Notices["/api/policies/template-notices GET"]
end
subgraph PlatformAdminRoutes["Platform-Admin Routes (withPlatformAdmin)"]
R_PATmpl["/api/platform-admin/policy-templates\nGET list / POST create"]
R_PATmplId["/api/platform-admin/policy-templates/[id]\nGET / PUT"]
R_PATmplPublish["/api/platform-admin/policy-templates/[id]/publish\nPOST - triggers fan-out notices"]
R_PARules["/api/platform-admin/template-rules\nGET list / POST create"]
R_PARulesId["/api/platform-admin/template-rules/[id]\nPUT / DELETE"]
end
subgraph HipaaAdminRoutes["HIPAA Admin Routes (withHipaaAdminAuth)"]
R_HipaaLoginAdmin["/api/hipaa/auth/login-admin POST\nverifies Firebase Bearer token\nissues httpOnly session cookie"]
R_HipaaLogout["/api/hipaa/auth/logout POST\nclears hipaa-admin-token cookie"]
R_HipaaOther["/api/hipaa/* (companies, participants,\nreports, assessments)"]
end
subgraph OtherRoutes["Other Domain Routes"]
R_Assets["/api/assets/[type]"]
R_Incidents["/api/incidents"]
R_Assessment["/api/assessment"]
R_Auth["/api/auth/register-init\n/api/auth/register-verify"]
end
end
subgraph Services["Business Logic (src/lib/)"]
direction TB
subgraph PolicyServices["Policy Services"]
SVC_PolicyService[policy-service.ts\ncreate / approve / publish / renew\nself-approval guard\nack tracking]
SVC_TemplateService[template-service.ts\nmaster template CRUD\npublishTemplate fan-out notices\nsendTemplateUpdateNotice]
SVC_RuleEngine[rule-engine.ts\nmatchTemplates\ngetRecommendationsForTenant\ntwo-layer unstable_cache\ninvalidateRuleCache]
end
subgraph InfraServices["Infrastructure Services"]
SVC_NotificationSvc[notification-service.ts\nFirestore notifications\ncreateMany]
SVC_Email[email.ts\nNodemailer / SMTP\nsendTemplateUpdateNotice]
SVC_FirestoreService[firestore-service.ts\ngeneric CRUD wrapper]
SVC_RBAC[rbac/checkAccess.ts]
end
subgraph QueueServices["Queue / Workers"]
SVC_BullMQ[BullMQ worker\nincident-queue.ts\napproval-queue.ts]
end
end
subgraph DataLayer["Data Layer (Firebase)"]
DB_Firebase[(Firestore)]
DB_Auth[(Firebase Auth\ncustom claims:\nplatform_admin\nhipaa_admin)]
DB_Redis[(Redis\nBullMQ backend)]
subgraph Collections["Key Collections"]
COL_Policies[policies\n+ approval_requests subcollection]
COL_Templates[policy_templates]
COL_Rules[template_rules]
COL_Notices[template_update_notices]
COL_Tenants[tenants\nnaicsCode, jurisdiction, businessFlags]
COL_Users[users\nroles, department]
COL_Incidents[incidents]
COL_Assets[assets/*]
end
end
LG_PA -->|renders| C_AdminShell
LG_Hipaa -->|renders| C_AdminShell
LG_PA -->|protects| P_PAHub
LG_PA -->|protects| P_PATemplates
LG_PA -->|protects| P_PATmplEdit
LG_PA -->|protects| P_PATmplNew
LG_PA -->|protects| P_PARulesPage
LG_PA -->|protects| P_PADocs
LG_Hipaa -->|protects| P_HipaaHub
LG_PA -->|verifies claims via| DB_Auth
LG_Hipaa -->|verifies claims via| DB_Auth
P_PALogin -->|signInWithEmailAndPassword| DB_Auth
P_PALogin -->|POST on hipaa_admin claim| R_HipaaLoginAdmin
P_PALogin -->|redirects to| P_PAHub
P_PAHub --> C_AdminShell
P_PATemplates --> C_AdminShell
P_PATmplEdit --> C_AdminShell
P_PARulesPage --> C_AdminShell
P_PADocs --> C_AdminShell
P_HipaaHub --> C_AdminShell
P_HipaaCompanies --> C_AdminShell
P_HipaaParticipants --> C_AdminShell
P_HipaaReports --> C_AdminShell
P_PATemplates --> C_TemplateEditorForm
P_PATmplEdit --> C_TemplateEditorForm
P_PATmplNew --> C_TemplateEditorForm
P_PARulesPage --> C_RuleBuilderForm
P_PAHub -->|GET| R_PATmpl
P_PATemplates -->|GET| R_PATmpl
P_PATmplNew -->|POST| R_PATmpl
P_PATmplEdit -->|GET / PUT| R_PATmplId
P_PATmplEdit -->|POST publish| R_PATmplPublish
P_PARulesPage -->|GET / POST| R_PARules
P_PARulesPage -->|PUT / DELETE| R_PARulesId
P_HipaaHub -->|requests| R_HipaaOther
P_HipaaCompanies -->|requests| R_HipaaOther
P_HipaaParticipants -->|requests| R_HipaaOther
P_HipaaReports -->|requests| R_HipaaOther
P_Policies --> C_PolicyStatusBadge
P_PoliciesNew --> C_PolicyForm
P_PoliciesNew --> C_TemplatePicker
P_PoliciesId --> C_PolicyEditor
P_PoliciesId --> C_PolicyStatusBadge
P_PoliciesId --> C_TemplateUpdateBanner
P_PoliciesId --> C_TemplateDiffView
P_PoliciesId --> C_ApprovalCommentThread
P_Register --> C_RegistrationForm
P_Policies --> H_UseAuth
P_PoliciesId --> H_UsePermission
H_UseAuth --> S_Auth
H_UsePermission --> H_UseAuth
P_PoliciesNew -->|POST /api/policies| R_Policies
P_PoliciesId -->|GET /api/policies/:id| R_PoliciesId
P_PoliciesId -->|POST .../submit| R_Submit
P_PoliciesId -->|POST .../approve| R_Approve
P_PoliciesId -->|POST .../publish| R_Publish
P_PoliciesId -->|POST .../acknowledge| R_Ack
C_TemplateDiffView -->|GET .../template-diff| R_Diff
C_TemplateUpdateBanner -->|POST .../accept| R_Accept
C_TemplateUpdateBanner -->|POST .../dismiss| R_Dismiss
C_TemplatePicker -->|GET /api/policies/recommend| R_Recommend
C_ApprovalCommentThread -->|GET/POST .../approval-request| R_ApprovalReq
C_ApprovalCommentThread -->|POST .../comment| R_Comment
R_Policies --> MW_WithAuth
R_PoliciesId --> MW_WithAuth
R_Recommend --> MW_WithAuth
R_PATmpl --> MW_WithPlatformAdmin
R_PATmplId --> MW_WithPlatformAdmin
R_PATmplPublish --> MW_WithPlatformAdmin
R_PARules --> MW_WithPlatformAdmin
R_PARulesId --> MW_WithPlatformAdmin
R_HipaaLoginAdmin --> MW_WithHipaaAdmin
R_HipaaLogout --> MW_WithHipaaAdmin
R_HipaaOther --> MW_WithHipaaAdmin
MW_WithAuth --> DB_Auth
MW_WithPlatformAdmin --> DB_Auth
MW_WithHipaaAdmin --> DB_Auth
R_Policies --> SVC_PolicyService
R_PoliciesId --> SVC_PolicyService
R_Submit --> SVC_PolicyService
R_Approve --> SVC_PolicyService
R_Publish --> SVC_PolicyService
R_Ack --> SVC_PolicyService
R_Recommend --> SVC_RuleEngine
R_Diff --> COL_Policies
R_Accept --> COL_Policies
R_Notices --> COL_Notices
R_PATmpl --> SVC_TemplateService
R_PATmplId --> SVC_TemplateService
R_PATmplPublish --> SVC_TemplateService
R_PARules --> SVC_TemplateService
R_PARulesId --> SVC_TemplateService
SVC_PolicyService --> SVC_NotificationSvc
SVC_TemplateService --> SVC_NotificationSvc
SVC_TemplateService --> SVC_Email
SVC_TemplateService --> SVC_RuleEngine
SVC_RuleEngine --> COL_Tenants
SVC_PolicyService --> DB_Firebase
SVC_TemplateService --> DB_Firebase
SVC_RuleEngine --> DB_Firebase
SVC_NotificationSvc --> DB_Firebase
SVC_BullMQ --> DB_Redis
DB_Firebase --> COL_Policies
DB_Firebase --> COL_Templates
DB_Firebase --> COL_Rules
DB_Firebase --> COL_Notices
DB_Firebase --> COL_Tenants
DB_Firebase --> COL_Users
DB_Firebase --> COL_Incidents
DB_Firebase --> COL_Assets
classDef page fill:#dbeafe,stroke:#3b82f6,color:#1e3a8a
classDef adminpage fill:#e0e7ff,stroke:#6366f1,color:#312e81
classDef guard fill:#fce7f3,stroke:#db2777,color:#831843
classDef component fill:#dcfce7,stroke:#16a34a,color:#14532d
classDef route fill:#fef3c7,stroke:#d97706,color:#78350f
classDef service fill:#f3e8ff,stroke:#9333ea,color:#581c87
classDef data fill:#fee2e2,stroke:#dc2626,color:#7f1d1d
classDef middleware fill:#ffedd5,stroke:#ea580c,color:#7c2d12
class P_Dashboard,P_Policies,P_PoliciesNew,P_PoliciesId,P_Incidents,P_Assets,P_Risk,P_Register page
class P_PALogin,P_PAHub,P_PADocs,P_PATemplates,P_PATmplEdit,P_PATmplNew,P_PARulesPage,P_HipaaHub,P_HipaaCompanies,P_HipaaParticipants,P_HipaaReports adminpage
class LG_PA,LG_Hipaa guard
class C_PolicyForm,C_PolicyEditor,C_PolicyStatusBadge,C_TemplatePicker,C_TemplateDiffView,C_TemplateUpdateBanner,C_ApprovalCommentThread,C_AdminShell,C_TemplateEditorForm,C_RuleBuilderForm,C_IncidentForm,C_IncidentStatusBadge,C_AssetTable,C_AssetForm,C_RegistrationForm,C_CompleteProfileModal component
class R_Policies,R_PoliciesId,R_Submit,R_Approve,R_Publish,R_Ack,R_Diff,R_Accept,R_Dismiss,R_ApprovalReq,R_Comment,R_Recommend,R_Notices,R_PATmpl,R_PATmplId,R_PATmplPublish,R_PARules,R_PARulesId,R_HipaaLoginAdmin,R_HipaaLogout,R_HipaaOther,R_Assets,R_Incidents,R_Assessment,R_Auth route
class SVC_PolicyService,SVC_TemplateService,SVC_RuleEngine,SVC_NotificationSvc,SVC_Email,SVC_FirestoreService,SVC_RBAC,SVC_BullMQ service
class DB_Firebase,DB_Auth,DB_Redis,COL_Policies,COL_Templates,COL_Rules,COL_Notices,COL_Tenants,COL_Users,COL_Incidents,COL_Assets data
class MW_WithAuth,MW_WithPlatformAdmin,MW_WithHipaaAdmin middleware