Management Dashboard
2022-01-25
Management Dashboard — Technical Documentation
Comprehensive system design documentation for the B2B Management Dashboard, covering architecture, data flow, authorization, data models, and feature gating.
Table of Contents
- High-Level Architecture
- Frontend Architecture
- Backend Architecture
- Authentication & Authorization
- Feature Gating System
- Data Models
- State Management
- API Layer
- Routing & Navigation
- Reporting & Analytics Pipeline
- Content Studio & Curriculum Mapping
- Assignment System
- Seat Management & Billing
- Key File Reference
1. High-Level Architecture
The Management Dashboard is a multi-tenant B2B platform that allows company administrators to manage users, assign training content, track progress, and generate reports. It sits within the main TryHackMe monorepo as a feature module in the React frontend, backed by Express API controllers and MongoDB.
Request Lifecycle
2. Frontend Architecture
Module Structure
The management dashboard is a self-contained feature module located at apps/frontend/src/features/management-dashboard/.
Component Hierarchy
3. Backend Architecture
Controller–Service–Model Pattern
All management dashboard endpoints follow the Express MVC pattern: Route → Middleware → Controller → Service → Model.
Middleware Pipeline
Every management dashboard request passes through a shared middleware stack before reaching the controller.
4. Authentication & Authorization
Identity Model
The system distinguishes between two types of company-affiliated users:
Authorization Flow
Role Matrix
| Capability | Company Admin | B2B User | Regular User |
|---|---|---|---|
| View Dashboard | Yes | Limited | No |
| Manage Users/Seats | Yes | No | No |
| Create Assignments | Yes | No | No |
| View Reports | Yes | Read-only | No |
| Configure Settings | Yes | No | No |
| Manage Billing | Yes | No | No |
| SSO Configuration | Yes (if enabled) | No | No |
| API Key Management | Yes (if enabled) | No | No |
5. Feature Gating System
Features are gated at two levels: Company Features (stored in MongoDB per company) and GrowthBook Feature Flags (remote config, gradual rollout).
Feature Gating Architecture
Plan Feature Matrix
| Feature | TEAM | B2B |
|---|---|---|
| THM Content | Yes | Yes |
| Additional Content | Yes | Yes |
| Learning Paths | Yes | Yes |
| Content Studio | Yes | Yes |
| SOC Simulator | No | Yes |
| Threat Hunting | No | Yes |
| Tabletop Exercises | No | Yes |
| Certifications | No | Yes |
| Assignments | No | Yes |
| Curriculum Mapping | No | Yes |
| CTF Builder | No | Yes |
| Skills Matrix | No | Yes |
| Skills Graph | No | Yes |
| MITRE ATT&CK | No | Yes |
| SSO | No | No (add-on) |
| API Access | No | Yes |
| Flexible Seats | No | No (add-on) |
| Private Group | Yes | No |
| Disable VM Internet | Yes | No |
| Transferable Licenses | No | Yes |
GrowthBook Feature Flags
| Flag Name | Purpose |
|---|---|
content-studio-all-tab | Enables the unified "All" tab in Content Studio |
curriculum-mapping | Enables curriculum mapping feature |
cta-content-studio-all | Enables learning unit creation CTA |
display-custom-page-search | Enables custom page search |
business-management-dashboard-certs | Enables certifications section |
self-onboarding-admins | Enables admin self-onboarding flow |
ttx-mgt-dashboard | Enables TTX section in dashboard |
b2b-reporting | Enables new reporting UI |
b2b-reporting-users-and-group | Enables user/group-level analytics |
slack-teams-cards | Enables Slack/Teams integration cards |
business-teams-checkout | Enables Teams plan checkout flow |
6. Data Models
Entity Relationship Diagram
Company Document Structure (Embedded Documents)
The Company model uses embedded subdocuments extensively rather than separate collections. This design optimizes for read-heavy dashboard operations by keeping related data co-located.
Key Indexes
| Collection | Index | Purpose |
|---|---|---|
companies | subscription.stripe.customerId | Stripe webhook lookup |
companies | subscription.stripe.subscriptionId | Subscription management |
companies | reminders (sparse) | Reminder queries |
company_assignment_completion | { userId, assignmentId, companyId } (unique) | Prevents duplicate completions |
analytics | { userId, action, inserted } | Report aggregation queries |
users | local.email | Login lookup |
users | subscription.stripe.customerId | Billing lookup |
7. State Management
State Architecture
RTK Query Data Flow
Key RTK Query Slices
| Slice | Location | Key Queries | Key Mutations |
|---|---|---|---|
| Dashboard | dashboard/dashboard.slice.ts | activeUserStats, assignmentStats, leaderboard, skillsProgression, usersActivityStatus | sendInactiveUsersEmailReminder |
| Assignments | assignments/assignments.slice.ts | companyAssignments, assignmentDetails, assignmentScoreboard, assignmentProgress, assignmentMetrics | createAssignment, cloneAssignment, deleteAssignment, updateDetails, bulkDelete |
| User Mgmt | users/.../user-management.slice.ts | estimateCost, groupsLatestAssignments, jobStatus | bulkImportUsers, addUserToSeat, removeUserFromSeat, redeemTokens, addFlexibleSeats |
| Settings | settings/settings.slice.ts | companyDomains, companyInviteLink, isTeamsBotInstalled | updateBranding, regenerateAPIKey, cancelSubscription, toggleVmInternetAccess |
| Analytics | reports/.../analytics.slice.ts | userAnalytics, userKPIs, groupAssignments | — |
| Content Studio | content-studio/content-studio.slice.ts | contentSearch | — |
8. API Layer
Endpoint Map
All endpoints are prefixed with /api/v2/companies/ and require the standard middleware stack (isLoggedIn → isCorporatePartner → isDashboardExpired).
9. Routing & Navigation
Route Tree
All management dashboard routes are nested under /client/:companyId/.
Route Protection Layers
Each route can apply multiple protection checks, evaluated in order:
10. Reporting & Analytics Pipeline
Data Collection and Aggregation
KPI Calculation Flow
11. Content Studio & Curriculum Mapping
Content Studio Architecture
Curriculum Mapping Flow
12. Assignment System
Assignment Lifecycle
Assignment Data Flow
13. Seat Management & Billing
Seat Lifecycle
Billing Integration
Bulk Import Flow
14. Key File Reference
Frontend
| File | Purpose |
|---|---|
features/management-dashboard/management-dashboard.tsx | Entry wrapper component |
features/management-dashboard/use-mgt-dashboard.ts | Main initialization hook |
features/management-dashboard/dashboard/dashboard.tsx | Dashboard overview page |
features/management-dashboard/dashboard/dashboard.slice.ts | Dashboard RTK Query slice |
features/management-dashboard/assignments/assignments.tsx | Assignments list page |
features/management-dashboard/assignments/assignments.slice.ts | Assignments RTK Query slice |
features/management-dashboard/content-studio/content-studio.tsx | Content Studio page |
features/management-dashboard/users/views/user-management/ | User management views |
features/management-dashboard/reports/ | All reporting views |
features/management-dashboard/settings/settings.tsx | Settings page |
features/management-dashboard/v3/components/navigation/ | Sidebar navigation |
features/management-dashboard/contexts/company/ | Company context provider |
router/sub-routes/management-dashboard.tsx | Route definitions |
common/hooks/use-company-features.ts | Feature checking hook |
router/route-protector.ts | Route protection utility |
Backend
| File | Purpose |
|---|---|
routes/companies/index.ts | Main company router |
controllers/companies/index.ts | Core company controller |
controllers/companies/assignments.ts | Assignment endpoints |
controllers/companies/analytics.ts | Analytics endpoints |
controllers/companies/company-seats.ts | Seat management endpoints |
controllers/companies/reports.ts | Report generation endpoints |
services/companies/index.ts | Core company service (2800+ LOC) |
services/companies/details.ts | Company detail transformation |
services/companies/assignments.ts | Assignment business logic |
services/companies/company-seats.ts | Seat management logic |
services/companies/reports.ts | Report aggregation pipelines |
services/companies/active-user-stats.ts | Active user statistics |
services/companies/user-activity-status.ts | User activity classification |
services/companies/content-studio-search.ts | Unified content search |
services/companies/curriculum/ | Curriculum parsing & matching |
services/companies/sso.ts | WorkOS SSO integration |
services/companies/stripe-subscription.ts | Stripe billing integration |
models/company/index.ts | Company Mongoose model |
models/company/company-user.ts | Company user subdocument |
models/company/assignment.ts | Assignment subdocument |
models/assignment-completion/index.ts | Assignment completion model |
common/constants/companies/features.ts | Plan feature configuration |
common/interfaces/company/features.ts | Feature interfaces |
middlewares/is-corporate-partner/index.ts | Corporate partner middleware |