{"slug":"operations/WORK_ROUTER_IMPLEMENTATION","title":"Work Router Implementation Summary","section":"operations","sectionLabel":"Operations","status":"unclassified","type":"document","path":"operations/WORK_ROUTER_IMPLEMENTATION.mdx","bytes":10896,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n## Overview\n\nSuccessfully built a complete Work Router system for IntegrateWise that maps users to role-specific workspace views at runtime based on their onboarding profile (Role × Department × Industry). The system is fully isolated, non-disruptive, and ready for integration with Descope auth.\n\n## Architecture\n\n### 1. **Data Layer** (`lib/data/`)\n\nCompletely isolated data persistence layer with TypeScript-first design.\n\n**Files:**\n\n- `types.ts` - TypeScript interfaces for all domain models (UserProfile, Tenant, Role, Capability, etc.)\n- `in-memory-provider.ts` - In-memory DataProvider implementation with seed data for dev/preview\n- `index.ts` - Factory function `getDataProvider()` for singleton instance\n\n**Key Design:**\n\n- DataProvider interface abstracts all data access\n- Repository pattern for each domain (ProfileRepo, TenantRepo, UserRepo, etc.)\n- InMemoryDataProvider ships with seed data for 3 industries (SaaS, Healthcare, Fintech)\n- Drizzle ORM can be swapped in via DrizzleDataProvider (future)\n- No direct SQL/database calls - everything goes through repos\n\n**Database Schema (seeded):**\n\n- Users, Profiles, Tenants, Roles, Permissions\n- Plugins, Capabilities, Agents, Deployments\n- Memory items, Audit logs\n\n### 2. **Onboarding Flow** (`components/onboarding/`)\n\n5-step form that collects user profile and persists to DataProvider.\n\n**Files:**\n\n- `layout.tsx` - Onboarding container with progress stepper and navigation\n- `steps.tsx` - Five step components: Identity, Role, Department, Industry, Confirm\n- `onboarding-container.tsx` - State management and form orchestration\n- `app/onboarding/page.tsx` - Route entry point\n\n**Flow:**\n\n1. **Identity** - Name, Email, Organization\n2. **Role** - Choose from 10 roles (Founder, Sales Rep, Sales Manager, CS Manager, Marketing, Finance, Operations, Product, Engineering, Admin)\n3. **Department** - Prioritize team focus (Engineering, Sales, Marketing, Operations, Finance, CS, Product, Leadership)\n4. **Industry** - SaaS, Healthcare, Fintech, or Other\n5. **Confirm** - Review and persist UserProfile\n\n**UX:**\n\n- Responsive design (mobile-first)\n- Full keyboard navigation (Enter to submit)\n- Back button navigation (hidden on step 1)\n- Step progress indicator with completion checks\n- Validation feedback on each step\n- All sections gated by required field validation\n\n### 3. **Work Router** (`lib/work/`)\n\nRuntime view resolution engine.\n\n**Files:**\n\n- `router.ts` - Core resolveWorkView() function with 10 role definitions\n- `industry-presets.ts` - Industry-specific vocabulary and KPI overrides (SaaS, Healthcare, Fintech, Other)\n- `admin-preview.ts` - Admin preview mode for impersonating other profiles\n\n**Role Views (10 total):**\n\n1. **Founder** - Company Overview, Priorities, Revenue, Pipeline, Agent Activity\n2. **Sales Rep** - My Accounts, Contacts, Opportunities, Activities, Playbooks\n3. **Sales Manager** - Pipeline, Forecast, Team Performance, Deal Risk\n4. **CS Manager** - Customer Portfolio, Account 360, Health, Renewals, QBRs\n5. **Marketing** - Campaigns, Content, Calendar, Analytics, Product Launches\n6. **Finance** - Revenue, Expenses, Subscriptions, Forecast, Infrastructure Costs\n7. **Operations** - Queues, Tasks, Approvals, Incidents, Deployments\n8. **Product** - Roadmap, Feedback, Releases, Decisions\n9. **Engineering** - Connections, Capabilities, Runs, Logs, Deployments\n10. **Admin** - Organizations, Users, Roles & Permissions, Plugins, Audit Log\n\n**Router Logic:**\n\n- Reads role from persisted UserProfile\n- Filters sections by:\n  - Required permissions (from role definition)\n  - Required capabilities (installed/available)\n  - Required plugins (installed)\n- Department-based reordering (extensible for future filters)\n- Industry-specific vocabulary swapping via presets\n- Environment badge (production, staging, dev, etc.)\n\n### 4. **Work View Components** (`components/work/`, `app/work/`)\n\nRendering layer that displays resolved views.\n\n**Files:**\n\n- `work-view-scaffold.tsx` - Shared layout with header, sections grid, non-production banner\n- `app/work/page.tsx` - Main entry point that loads profile, resolves view, renders sections\n\n**UX:**\n\n- Grid layout (1 col mobile, 2 col tablet, 3 col desktop)\n- Environment badge (production/staging/dev)\n- Impersonation banner (for admin preview mode)\n- Section cards with icons, descriptions, and placeholder content\n- Graceful error handling with redirect to onboarding\n- Loading state while fetching profile and resolving view\n\n## Integration Points\n\n### Descope Auth\n\nCurrently using mock auth in onboarding and work pages:\n\n```typescript\nfunction getDemoUser() {\n  return {\n    userId: \"user-demo-001\",\n    tenantId: \"saas-demo\",\n  };\n}\n```\n\n**To integrate Descope:**\n\n1. Import Descope auth SDK in onboarding/page.tsx\n2. Get userId from Descope session\n3. Get tenantId from session metadata or org context\n4. Pass to OnboardingContainer\n\n### Environment Variables\n\nUses existing project env vars:\n\n- `DESCOPE_PROJECT_ID` - Already configured\n- `DESCOPE_MANAGEMENT_KEY` - Already configured\n- `NEXT_PUBLIC_DESCOPE_PROJECT_ID` - Already configured\n\nNo new env vars required.\n\n### Platform API\n\nWork Router integrates with existing Platform API:\n\n- DataProvider can read from platform.\\* surfaces\n- Future: Capabilities and Agents can come from platform registry\n- No modifications to existing Platform API needed\n\n## Isolation & Non-Disruption\n\nAll Work Router code is completely isolated:\n\n**Isolated Routes:**\n\n- `/onboarding` - New onboarding flow\n- `/work` - New Work Router view\n\n**Isolated Components:**\n\n- `components/onboarding/*` - Onboarding UI only\n- `components/work/*` - Work Router UI only\n- `lib/data/*` - Data persistence only\n- `lib/work/*` - Router logic only\n\n**No Changes to:**\n\n- Existing routes (`/home`, `/inbox`, `/founder`, `/sales`, etc.)\n- Existing components or navigation\n- Existing API endpoints\n- Existing database schema or migrations\n\n**Behavior:**\n\n- Work Router is opt-in - existing UI untouched\n- First-time users with `onboardedAt = null` redirected to onboarding\n- After onboarding, users can visit `/work` voluntarily\n- Existing authenticated users unaffected\n\n## Development & Testing\n\n### Running the App\n\n```bash\ncd /vercel/share/v0-project/apps/web\nnpm run dev\n```\n\n### Demo Flow\n\n1. Visit `/onboarding` - Step through the 5-step form\n2. Complete onboarding - Persists UserProfile to InMemoryDataProvider\n3. Redirects to `/work` - Resolves and renders workspace\n4. View all 10 role views by changing profile data\n5. Use admin preview mode to test any role/dept/industry combo\n\n### Using Admin Preview Mode\n\n```typescript\n\n// Create preview profile (not persisted)\nconst previewProfile = await createAdminPreviewProfile(\n  {\n    role: \"founder\",\n    department: \"engineering\",\n    industry: \"healthcare\",\n    adminUserId: \"admin-user-123\",\n  },\n  \"tenant-123\"\n);\n\n// Use preview profile in resolveWorkView()\n```\n\n## Data Models\n\n### UserProfile\n\n```typescript\n{\n  id: string;\n  userId: string;\n  tenantId: string;\n  name: string;\n  email: string;\n  role: Role; // Set at onboarding\n  department: Department; // Set at onboarding\n  industry: Industry; // Set at onboarding\n  onboardedAt: string;\n  createdAt: string;\n  updatedAt: string;\n}\n```\n\n### WorkContext\n\n```typescript\n{\n  profile: UserProfile;\n  permissions: Permission[];\n  installedPlugins: string[];\n  availableCapabilities: Capability[];\n  environment: Environment;\n}\n```\n\n### ResolvedWorkView\n\n```typescript\n{\n  role: Role;\n  title: string;\n  description: string;\n  sections: WorkSection[];\n  capabilities: Capability[];\n  environmentBadge: { label: string; variant: string };\n}\n```\n\n## Future Enhancements\n\n1. **Drizzle ORM Integration**\n   - Add DrizzleDataProvider implementation\n   - Create migrations for all schema tables\n   - Replace InMemoryDataProvider in production\n\n2. **Department-based Filtering**\n   - Extend router to filter/reorder sections by department\n   - Add department-specific KPI overrides\n\n3. **Permissions Engine**\n   - Wire in role_permissions table\n   - Extend router to check granular permissions\n   - Hide/disable actions based on permissions\n\n4. **Capability UI Integration**\n   - Add capability rail in Work view\n   - Allow users to invoke capabilities inline\n   - Show capability status and errors\n\n5. **Real Section Implementations**\n   - Replace placeholder components with actual sections\n   - Wire to existing dashboard templates\n   - Add drill-down navigation\n\n6. **Settings & User Preferences**\n   - Allow users to change role/dept/industry (with permissions)\n   - Save workspace preferences\n   - Customize section visibility\n\n7. **Audit & Activity Logging**\n   - Log all profile changes\n   - Track workspace access\n   - Show activity feed in settings\n\n## File Manifest\n\n```\nlib/data/\n├── types.ts                    (257 lines) - Domain types and repo interfaces\n├── in-memory-provider.ts       (564 lines) - In-memory DataProvider + seed data\n└── index.ts                    (34 lines)  - Factory function\n\nlib/work/\n├── router.ts                   (530 lines) - 10 role view definitions + resolveWorkView\n├── industry-presets.ts         (131 lines) - SaaS/Healthcare/Fintech/Other presets\n└── admin-preview.ts            (100 lines) - Admin preview mode\n\ncomponents/onboarding/\n├── layout.tsx                  (120 lines) - Onboarding page container\n├── steps.tsx                   (293 lines) - 5 step components\n└── onboarding-container.tsx    (189 lines) - Form state management\n\ncomponents/work/\n└── work-view-scaffold.tsx      (117 lines) - Shared work view layout\n\napp/\n├── onboarding/page.tsx         (30 lines)  - Route entry point\n└── work/page.tsx               (167 lines) - Work router entry point\n```\n\n**Total: ~2,550 lines of TypeScript/React**\n\n## Testing Checklist\n\n- [x] Data persistence (create/read/update profiles)\n- [x] Onboarding flow (all 5 steps)\n- [x] Form validation (required fields)\n- [x] Work view resolution (all 10 roles)\n- [x] Section filtering by permissions\n- [x] Environment badge display\n- [x] Admin preview mode logic\n- [x] Industry preset vocabulary mapping\n- [x] Responsive design (mobile, tablet, desktop)\n- [ ] Descope auth integration (pending)\n- [ ] Real section implementations (pending)\n- [ ] End-to-end user flow (pending Descope)\n\n## Next Steps\n\n1. **Verify Descope Integration** - Replace mock auth with real Descope calls\n2. **Start Preview Mode** - Access `/onboarding` to test the flow\n3. **Build Real Sections** - Implement individual section components\n4. **Connect Platform API** - Wire capabilities/agents from platform registry\n5. **Add Drizzle** - Swap InMemoryDataProvider for DrizzleDataProvider\n6. **Deploy & Monitor** - Deploy to staging, gather feedback\n"}