Unclassified

Work Router Implementation Summary

Overview

Successfully 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.

Architecture

1. Data Layer (`lib/data/`)

Completely isolated data persistence layer with TypeScript-first design.

Files:

types.ts - TypeScript interfaces for all domain models (UserProfile, Tenant, Role, Capability, etc.)
in-memory-provider.ts - In-memory DataProvider implementation with seed data for dev/preview
index.ts - Factory function getDataProvider() for singleton instance

Key Design:

DataProvider interface abstracts all data access
Repository pattern for each domain (ProfileRepo, TenantRepo, UserRepo, etc.)
InMemoryDataProvider ships with seed data for 3 industries (SaaS, Healthcare, Fintech)
Drizzle ORM can be swapped in via DrizzleDataProvider (future)
No direct SQL/database calls - everything goes through repos

Database Schema (seeded):

Users, Profiles, Tenants, Roles, Permissions
Plugins, Capabilities, Agents, Deployments
Memory items, Audit logs

2. Onboarding Flow (`components/onboarding/`)

5-step form that collects user profile and persists to DataProvider.

Files:

layout.tsx - Onboarding container with progress stepper and navigation
steps.tsx - Five step components: Identity, Role, Department, Industry, Confirm
onboarding-container.tsx - State management and form orchestration
app/onboarding/page.tsx - Route entry point

Flow:

Identity - Name, Email, Organization
Role - Choose from 10 roles (Founder, Sales Rep, Sales Manager, CS Manager, Marketing, Finance, Operations, Product, Engineering, Admin)
Department - Prioritize team focus (Engineering, Sales, Marketing, Operations, Finance, CS, Product, Leadership)
Industry - SaaS, Healthcare, Fintech, or Other
Confirm - Review and persist UserProfile

UX:

Responsive design (mobile-first)
Full keyboard navigation (Enter to submit)
Back button navigation (hidden on step 1)
Step progress indicator with completion checks
Validation feedback on each step
All sections gated by required field validation

3. Work Router (`lib/work/`)

Runtime view resolution engine.

Files:

router.ts - Core resolveWorkView() function with 10 role definitions
industry-presets.ts - Industry-specific vocabulary and KPI overrides (SaaS, Healthcare, Fintech, Other)
admin-preview.ts - Admin preview mode for impersonating other profiles

Role Views (10 total):

Founder - Company Overview, Priorities, Revenue, Pipeline, Agent Activity
Sales Rep - My Accounts, Contacts, Opportunities, Activities, Playbooks
Sales Manager - Pipeline, Forecast, Team Performance, Deal Risk
CS Manager - Customer Portfolio, Account 360, Health, Renewals, QBRs
Marketing - Campaigns, Content, Calendar, Analytics, Product Launches
Finance - Revenue, Expenses, Subscriptions, Forecast, Infrastructure Costs
Operations - Queues, Tasks, Approvals, Incidents, Deployments
Product - Roadmap, Feedback, Releases, Decisions
Engineering - Connections, Capabilities, Runs, Logs, Deployments
Admin - Organizations, Users, Roles & Permissions, Plugins, Audit Log

Router Logic:

Reads role from persisted UserProfile
Filters sections by:
- Required permissions (from role definition)
- Required capabilities (installed/available)
- Required plugins (installed)
Department-based reordering (extensible for future filters)
Industry-specific vocabulary swapping via presets
Environment badge (production, staging, dev, etc.)

4. Work View Components (`components/work/`, `app/work/`)

Rendering layer that displays resolved views.

Files:

work-view-scaffold.tsx - Shared layout with header, sections grid, non-production banner
app/work/page.tsx - Main entry point that loads profile, resolves view, renders sections

UX:

Grid layout (1 col mobile, 2 col tablet, 3 col desktop)
Environment badge (production/staging/dev)
Impersonation banner (for admin preview mode)
Section cards with icons, descriptions, and placeholder content
Graceful error handling with redirect to onboarding
Loading state while fetching profile and resolving view

Integration Points

Descope Auth

Currently using mock auth in onboarding and work pages:

function getDemoUser() {
  return {
    userId: "user-demo-001",
    tenantId: "saas-demo",
  };
}

To integrate Descope:

Import Descope auth SDK in onboarding/page.tsx
Get userId from Descope session
Get tenantId from session metadata or org context
Pass to OnboardingContainer

Environment Variables

Uses existing project env vars:

DESCOPE_PROJECT_ID - Already configured
DESCOPE_MANAGEMENT_KEY - Already configured
NEXT_PUBLIC_DESCOPE_PROJECT_ID - Already configured

No new env vars required.

Platform API

Work Router integrates with existing Platform API:

DataProvider can read from platform.* surfaces
Future: Capabilities and Agents can come from platform registry
No modifications to existing Platform API needed

Isolation & Non-Disruption

All Work Router code is completely isolated:

Isolated Routes:

/onboarding - New onboarding flow
/work - New Work Router view

Isolated Components:

components/onboarding/* - Onboarding UI only
components/work/* - Work Router UI only
lib/data/* - Data persistence only
lib/work/* - Router logic only

No Changes to:

Existing routes (/home, /inbox, /founder, /sales, etc.)
Existing components or navigation
Existing API endpoints
Existing database schema or migrations

Behavior:

Work Router is opt-in - existing UI untouched
First-time users with onboardedAt = null redirected to onboarding
After onboarding, users can visit /work voluntarily
Existing authenticated users unaffected

Development & Testing

Running the App

cd /vercel/share/v0-project/apps/web
npm run dev

Demo Flow

Visit /onboarding - Step through the 5-step form
Complete onboarding - Persists UserProfile to InMemoryDataProvider
Redirects to /work - Resolves and renders workspace
View all 10 role views by changing profile data
Use admin preview mode to test any role/dept/industry combo

Using Admin Preview Mode


// Create preview profile (not persisted)
const previewProfile = await createAdminPreviewProfile(
  {
    role: "founder",
    department: "engineering",
    industry: "healthcare",
    adminUserId: "admin-user-123",
  },
  "tenant-123"
);

// Use preview profile in resolveWorkView()

Data Models

UserProfile

{
  id: string;
  userId: string;
  tenantId: string;
  name: string;
  email: string;
  role: Role; // Set at onboarding
  department: Department; // Set at onboarding
  industry: Industry; // Set at onboarding
  onboardedAt: string;
  createdAt: string;
  updatedAt: string;
}

WorkContext

{
  profile: UserProfile;
  permissions: Permission[];
  installedPlugins: string[];
  availableCapabilities: Capability[];
  environment: Environment;
}

ResolvedWorkView

{
  role: Role;
  title: string;
  description: string;
  sections: WorkSection[];
  capabilities: Capability[];
  environmentBadge: { label: string; variant: string };
}

Future Enhancements

Drizzle ORM Integration
- Add DrizzleDataProvider implementation
- Create migrations for all schema tables
- Replace InMemoryDataProvider in production
Department-based Filtering
- Extend router to filter/reorder sections by department
- Add department-specific KPI overrides
Permissions Engine
- Wire in role_permissions table
- Extend router to check granular permissions
- Hide/disable actions based on permissions
Capability UI Integration
- Add capability rail in Work view
- Allow users to invoke capabilities inline
- Show capability status and errors
Real Section Implementations
- Replace placeholder components with actual sections
- Wire to existing dashboard templates
- Add drill-down navigation
Settings & User Preferences
- Allow users to change role/dept/industry (with permissions)
- Save workspace preferences
- Customize section visibility
Audit & Activity Logging
- Log all profile changes
- Track workspace access
- Show activity feed in settings

File Manifest

lib/data/
├── types.ts                    (257 lines) - Domain types and repo interfaces
├── in-memory-provider.ts       (564 lines) - In-memory DataProvider + seed data
└── index.ts                    (34 lines)  - Factory function

lib/work/
├── router.ts                   (530 lines) - 10 role view definitions + resolveWorkView
├── industry-presets.ts         (131 lines) - SaaS/Healthcare/Fintech/Other presets
└── admin-preview.ts            (100 lines) - Admin preview mode

components/onboarding/
├── layout.tsx                  (120 lines) - Onboarding page container
├── steps.tsx                   (293 lines) - 5 step components
└── onboarding-container.tsx    (189 lines) - Form state management

components/work/
└── work-view-scaffold.tsx      (117 lines) - Shared work view layout

app/
├── onboarding/page.tsx         (30 lines)  - Route entry point
└── work/page.tsx               (167 lines) - Work router entry point

Total: ~2,550 lines of TypeScript/React

Testing Checklist

Next Steps

Verify Descope Integration - Replace mock auth with real Descope calls
Start Preview Mode - Access /onboarding to test the flow
Build Real Sections - Implement individual section components
Connect Platform API - Wire capabilities/agents from platform registry
Add Drizzle - Swap InMemoryDataProvider for DrizzleDataProvider
Deploy & Monitor - Deploy to staging, gather feedback

Overview

Architecture

1. Data Layer (lib/data/)

2. Onboarding Flow (components/onboarding/)

3. Work Router (lib/work/)

4. Work View Components (components/work/, app/work/)

Integration Points

Descope Auth

Environment Variables

Platform API

Isolation & Non-Disruption

Development & Testing

Running the App

Demo Flow

Using Admin Preview Mode

Data Models

UserProfile

WorkContext

ResolvedWorkView

Future Enhancements

File Manifest

Testing Checklist

Next Steps

1. Data Layer (`lib/data/`)

2. Onboarding Flow (`components/onboarding/`)

3. Work Router (`lib/work/`)

4. Work View Components (`components/work/`, `app/work/`)