{"slug":"operations/WORK_ROUTER_QUICKSTART","title":"Work Router - Quick Start Guide","section":"operations","sectionLabel":"Operations","status":"unclassified","type":"document","path":"operations/WORK_ROUTER_QUICKSTART.mdx","bytes":6661,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n## What We Built\n\nA complete **Work Router system** that creates role-specific workspaces for IntegrateWise users. After onboarding (collecting Role, Department, Industry), users see a customized dashboard tailored to their role.\n\n## Key Features\n\n✅ **5-Step Onboarding** - Collect user profile info + role selection  \n✅ **10 Role Views** - Founder, Sales Rep, Manager, CS, Marketing, Finance, Ops, Product, Engineering, Admin  \n✅ **Dynamic Routing** - Views resolve at runtime based on profile + permissions  \n✅ **Industry Presets** - SaaS, Healthcare, Fintech vocab/KPI overrides  \n✅ **Admin Preview** - Test any role/dept/industry combo  \n✅ **Zero Disruption** - Completely isolated from existing UI\n\n## How to Test\n\n### 1. Start Dev Server\n\n```bash\ncd /vercel/share/v0-project/apps/web\nnpm run dev\n```\n\nServer starts at http://localhost:3000\n\n### 2. Visit Onboarding\n\n```\nhttp://localhost:3000/onboarding\n```\n\nComplete the 5-step form:\n\n- Step 1: Enter name, email, company name\n- Step 2: Select your role (see all 10 roles)\n- Step 3: Select your department\n- Step 4: Select your industry (SaaS, Healthcare, Fintech)\n- Step 5: Review and confirm\n\n**Continue button is enabled once each step is valid.**\n\n### 3. Auto-Redirect to Work View\n\nAfter completing onboarding, you're automatically redirected to:\n\n```\nhttp://localhost:3000/work\n```\n\nYour personalized workspace displays sections relevant to your role.\n\n### 4. Preview Different Roles\n\nEdit the demo user in `/app/work/page.tsx` to test different profiles:\n\n```typescript\n// Change userId to test different profiles\nfunction getDemoUser() {\n  return {\n    userId: \"user-demo-001\", // Change this\n    tenantId: \"saas-demo\", // Or change this\n  };\n}\n```\n\nThen refresh to see a different workspace.\n\n## File Structure\n\n```\napps/web/\n├── lib/\n│   ├── data/                     # Data persistence layer\n│   │   ├── types.ts              # Domain types\n│   │   ├── in-memory-provider.ts # InMemory data store + seed\n│   │   └── index.ts              # Factory function\n│   └── work/                     # Work router logic\n│       ├── router.ts             # resolveWorkView + 10 role definitions\n│       ├── industry-presets.ts   # Vocabulary/KPI overrides\n│       └── admin-preview.ts      # Admin impersonation mode\n├── components/\n│   ├── onboarding/               # Onboarding flow\n│   │   ├── layout.tsx            # Stepper + container\n│   │   ├── steps.tsx             # 5 step components\n│   │   └── onboarding-container.tsx  # Form state\n│   └── work/                     # Work view\n│       └── work-view-scaffold.tsx    # Shared layout\n└── app/\n    ├── onboarding/page.tsx       # Route: /onboarding\n    └── work/page.tsx             # Route: /work\n```\n\n## Data Flow\n\n```\nUser starts at /onboarding\n         ↓\nOnboardingContainer collects profile\n         ↓\nDataProvider.profiles.create(UserProfile)\n         ↓\nRedirect to /work\n         ↓\nLoad profile from DataProvider\n         ↓\nresolveWorkView(context)\n         ↓\nFilter sections by role/permissions/capabilities\n         ↓\nDisplay WorkViewScaffold with sections\n```\n\n## Customization\n\n### Add a New Role View\n\n1. Add role to `ROLE_DEFINITIONS` in `lib/work/router.ts`\n2. Define sections, descriptions, icons\n3. Role automatically appears in onboarding step 2\n\n### Change Industry Presets\n\nEdit `lib/work/industry-presets.ts`:\n\n- Add vocabulary translations\n- Change KPI definitions\n- Add default filters\n\n### Modify Onboarding Steps\n\nEdit step components in `components/onboarding/steps.tsx`:\n\n- Add/remove fields\n- Change validation rules\n- Update UI styling\n\n### Customize Work View Layout\n\nEdit `components/work/work-view-scaffold.tsx`:\n\n- Change grid columns\n- Add sections header\n- Modify card styling\n\n## API\n\n### getDataProvider()\n\n```typescript\n\nconst provider = getDataProvider();\n\n// Access data\nconst profile = await provider.profiles.get(userId);\nconst permissions = await provider.permissions.listAll();\nconst capabilities = await provider.capabilities.listByTenant(tenantId);\n```\n\n### resolveWorkView()\n\n```typescript\n\nconst context: WorkContext = {\n  profile,\n  permissions,\n  installedPlugins: [],\n  availableCapabilities: [],\n  environment: \"development\",\n};\n\nconst view = await resolveWorkView(context);\n// Returns: { role, title, description, sections, capabilities }\n```\n\n### Admin Preview\n\n```typescript\n\nconst preview = await createAdminPreviewProfile(\n  {\n    role: \"founder\",\n    department: \"engineering\",\n    industry: \"healthcare\",\n    adminUserId: \"admin-123\",\n  },\n  \"tenant-123\"\n);\n\nconst view = await resolveWorkView({\n  profile: preview,\n  // ... other context\n});\n```\n\n## Next Steps\n\n1. **Integrate Descope Auth** - Replace mock auth in `/onboarding/page.tsx` and `/work/page.tsx`\n2. **Build Real Sections** - Create actual components for each section (currently placeholders)\n3. **Connect Platform API** - Wire in real capabilities/agents from IntegrateWise registry\n4. **Add Drizzle ORM** - Replace InMemoryDataProvider with DrizzleDataProvider for production\n5. **Test Permissions** - Add real role-permission mappings and verify gating\n6. **Deploy to Staging** - Gather user feedback on role views\n\n## Troubleshooting\n\n**Onboarding not persisting?**\n\n- Check browser console for errors\n- Verify DataProvider is initialized\n- Make sure onboarding steps are all valid before submit\n\n**Work view not loading?**\n\n- Check that profile exists in DataProvider\n- Verify tenant and role are valid\n- Check console for resolveWorkView errors\n\n**Missing sections?**\n\n- Sections are hidden if you lack permissions\n- Check the role definition in `lib/work/router.ts`\n- Admin role shows all sections\n\n## Descope Integration (TODO)\n\nReplace mock auth functions with real Descope calls:\n\n```typescript\n// Before (current mock)\nfunction getDemoUser() {\n  return { userId: \"user-demo-001\", tenantId: \"saas-demo\" };\n}\n\n// After (Descope)\n\nasync function getAuthenticatedUser() {\n  const user = await getSessionUser();\n  return {\n    userId: user.userId,\n    tenantId: user.tenantId || \"default-tenant\",\n  };\n}\n```\n\nThen call `getAuthenticatedUser()` instead of `getDemoUser()` in pages.\n\n## Support\n\nSee `WORK_ROUTER_IMPLEMENTATION.md` for full technical documentation.\n"}