{"slug":"business/CODEBASE_REVIEW","title":"IntegrateWise Monorepo — Comprehensive Codebase Review","section":"business","sectionLabel":"Business","status":"unclassified","type":"document","path":"business/CODEBASE_REVIEW.mdx","bytes":26533,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n\n> **Tier C — Historical.** This document is a point-in-time snapshot preserved for reference. For current architecture, see [CANONICAL_PLATFORM_ARCHITECTURE.md](../architecture/CANONICAL_PLATFORM_ARCHITECTURE.md).\n\n**Date:** May 18, 2026  \n**Repository:** NirmalPrinceJ/integratewise-live  \n**Branch:** main (ai-connector-error)  \n**Package Manager:** pnpm v9.0.0  \n**Build Tool:** Vite (with Tailwind CSS)  \n\n---\n\n## Executive Summary\n\nIntegrateWise is a **Knowledge Workspace over the Spine, empowered by AI** — a sophisticated monorepo built with **Vite + React**, deployed on **Cloudflare (Pages + Workers)**, backed by **Supabase PostgreSQL** and structured around:\n\n- **L0 → L1 → L2 → L3 Architecture** (Onboarding → Workspace → Cognitive Layer → Backend)\n- **12 Domain Views** (Sales, Marketing, Finance, RevOps, Account Success, Service, Product Engineering, etc.)\n- **Governed AI Execution** (Approval-gated actions with evidence chains)\n- **Spine SSOT** (Single Source of Truth: structured data + unstructured knowledge + AI interactions)\n\nThe codebase is **mature, well-organized, and production-ready** with solid patterns for state management, component organization, and data flow. However, there are opportunities for UI/UX improvements and modernization.\n\n---\n\n## 1. Monorepo Structure\n\n### Root Organization\n```\n/vercel/share/v0-project/\n├── apps/                          # User-facing applications\n│   ├── web/                       # Main Vite SPA (workspace + marketing)\n│   ├── desktop/                   # Electron desktop app\n│   └── mobile/                    # React Native mobile\n├── packages/                      # Shared libraries & utilities\n│   ├── types/                     # TypeScript interfaces (global types)\n│   ├── config/                    # Config management\n│   ├── db/                        # Database utilities\n│   ├── supabase/                  # Supabase client + auth\n│   ├── rbac/                      # Role-based access control\n│   ├── tenancy/                   # Multi-tenancy utilities\n│   ├── api/                       # API client utilities\n│   ├── lib/                       # General-purpose utilities\n│   ├── connectors/                # Data connector implementations\n│   ├── connector-contracts/       # Connector interfaces\n│   ├── connector-utils/           # Connector helpers\n│   ├── knowledge-bank-ui/         # UI components for knowledge layer\n│   ├── webhooks/                  # Webhook utilities\n│   ├── analytics/                 # Analytics integration\n│   ├── accelerators/              # Domain-specific accelerators\n│   ├── integration-tests/         # End-to-end tests\n│   └── integratewise-mcp-tool-connector/  # MCP bridge\n├── services/                      # Backend Cloudflare Workers\n│   ├── gateway/                   # API gateway (ingress point)\n│   ├── workflow/                  # Workflow orchestration\n│   ├── spine-v2/                  # Spine (SSOT data layer)\n│   ├── pipeline/                  # Data normalization pipeline\n│   ├── normalizer/                # Schema normalization\n│   ├── connector/                 # Connector manager\n│   ├── intelligence/              # AI & predictions\n│   ├── l2/                        # Cognitive layer backend\n│   ├── knowledge/                 # Knowledge store\n│   ├── billing/                   # Billing & paywall\n│   ├── store/                     # Data store\n│   ├── admin/                     # Admin API\n│   ├── agents/                    # AI agents\n│   ├── loader/                    # Onboarding loader\n│   ├── tenants/                   # Tenant management\n│   ├── act/                       # Action execution\n│   ├── govern/                    # Governance engine\n│   └── ...13+ more                # Other services\n├── docs/                          # Product & technical documentation\n├── migrations/                    # SQL migrations\n├── scripts/                       # Build & deployment scripts\n└── configs/                       # Shared configuration templates\n```\n\n### Build System\n- **Turbo v2.0.0** — Monorepo task orchestration with 40 concurrent processes\n- **Vite 6.4.1** — Ultra-fast build for web app (no Next.js; migrated from Next.js)\n- **pnpm v9.0.0** — Workspace management (lockfile: pnpm-lock.yaml)\n- **Tailwind CSS v4.1.3** — via `@tailwindcss/vite` plugin\n\n---\n\n## 2. Web App (`apps/web`) — The Main Frontend\n\n### Tech Stack\n```\nFramework:       React 18.3.1 + React Router 7.0.0 (not Next.js)\nStyling:         Tailwind CSS 4.1.3 (+ custom design tokens)\nUI Components:   Radix UI (30+ components via @radix-ui/react-*)\nCharts:          Recharts 2.15.2\nForms:           React Hook Form 7.55.0\nAnimations:      Framer Motion 11.11.0 + Motion 11.11.0\nState Mgmt:      TanStack React Query 5.59.0 (+ Supabase realtime)\nAuth:            Supabase PKCE (Google SSO, GitHub SSO, email/password)\nDeployment:      Cloudflare Pages (SPA)\n```\n\n### Directory Structure\n```\napps/web/src/\n├── App.tsx                           # Root component (React Router setup)\n├── AppShell.tsx                      # Authenticated experience coordinator\n├── main.tsx                          # Vite entry point\n├── routes.tsx                        # Route definitions\n├── app.css                           # Global styles + design tokens\n├── vite-env.d.ts                     # Vite environment types\n│\n├── api/                              # API utilities\n├── clients/                          # API clients (Supabase, etc.)\n├── components/\n│   ├── core/                         # Core functionality\n│   │   ├── auth/                     # Auth provider, login, signup\n│   │   ├── hydration/                # Hydration fabric (5 providers)\n│   │   ├── providers/                # Global providers stack\n│   │   ├── rbac/                     # Role-based access control\n│   │   └── realtime/                 # WebSocket realtime sync\n│   │\n│   ├── l1/                           # Workspace layer\n│   │   ├── workspace/                # Main workspace shell\n│   │   │   ├── workspace-shell-new.tsx\n│   │   │   ├── content-router.tsx\n│   │   │   ├── animated-content-router.tsx\n│   │   │   ├── workspace-config.ts   # Domain navigation config\n│   │   │   ├── loader-phase1.tsx\n│   │   │   └── demo-data-banner.tsx\n│   │   │\n│   │   ├── domains/                  # 12 domain-specific views\n│   │   │   ├── account-success/      # 40+ views for CS domain\n│   │   │   ├── salesops/\n│   │   │   ├── revops/\n│   │   │   ├── marketing/\n│   │   │   ├── finance/\n│   │   │   ├── bizops/\n│   │   │   ├── product-engineering/\n│   │   │   ├── service/\n│   │   │   ├── procurement/\n│   │   │   ├── it-admin/\n│   │   │   ├── personal/\n│   │   │   └── student-teacher/\n│   │   │\n│   │   ├── admin/                    # Admin interfaces\n│   │   └── navigation/               # Navigation components\n│   │\n│   ├── l2/                           # Cognitive layer (AI)\n│   │   ├── cognitive/                # L2 drawer (⌘J overlay)\n│   │   ├── spine/                    # Spine client integration\n│   │   ├── goal-framework/           # Goal-driven AI\n│   │   └── bridge/                   # L1 ↔ L2 communication\n│   │\n│   ├── activation/                   # Onboarding & auth flows\n│   │   ├── onboarding/               # 6-step onboarding\n│   │   └── loader/                   # Loading states\n│   │\n│   ├── common/                       # Shared components\n│   │   ├── brand/                    # Logo, branding\n│   │   ├── layouts/                  # Page layouts\n│   │   ├── motion/                   # Animation utilities\n│   │   ├── shared/                   # EvidenceDrawer, analytics-shell\n│   │   ├── error/                    # Error boundaries\n│   │   ├── support/                  # Help widget\n│   │   └── utils/                    # Utility components\n│   │\n│   ├── connectivity/                 # Connector management\n│   │   └── connectors/               # OAuth & sync UI\n│   │\n│   ├── billing/                      # Paywall & pricing\n│   │   └── paywall/\n│   │\n│   ├── core/                         # Core infrastructure\n│   │   └── schema-driven/            # Schema-based rendering\n│   │\n│   └── _deprecated/                  # Legacy components (v1 architecture)\n│\n├── contexts/                         # React contexts\n│   └── tenant-context.tsx            # Multi-tenancy context\n│\n├── hooks/                            # Custom React hooks\n│   ├── use-module-data-context.ts\n│   ├── use-action-realtime.ts\n│   ├── use-tenant-products.ts\n│   ├── use-product-nav.ts\n│   ├── use-demo-data.ts\n│   └── ...more\n│\n├── lib/                              # Utilities\n│   ├── api-client.ts                 # API communication\n│   └── ...other utilities\n│\n├── pages/                            # Router pages\n├── config/                           # App configuration\n├── styles/                           # CSS files\n├── types/                            # Local TypeScript definitions\n└── utils/                            # Helper functions\n```\n\n### Key Component Patterns\n\n#### AppShell.tsx (528 lines)\n**Purpose:** L0→L1→L2→L3 wiring; coordinates entire authenticated experience\n\n**Provider Stack (outermost → innermost):**\n1. ErrorBoundary\n2. AuthProvider (Supabase PKCE)\n3. SpineProvider (Adaptive Spine integration)\n4. GoalProvider (AI goal framework)\n5. HydrationFabric (5-provider hydration system)\n6. WorkspaceShellNew (main workspace UI)\n\n**Stage Flow:**\n- Login → Signup → Onboarding (L0) → Loading (spinner) → Workspace (L1)\n\n**Context Mapping:**\n```typescript\nDEFAULT_DOMAIN_CTX_MAP: Record<string, string> = {\n  CUSTOMER_SUCCESS: \"CTX_CS\",\n  SALES: \"CTX_SALES\",\n  REVOPS: \"CTX_REVOPS\",\n  MARKETING: \"CTX_MARKETING\",\n  PRODUCT_ENGINEERING: \"CTX_TECH\",\n  FINANCE: \"CTX_FINANCE\",\n  SERVICE: \"CTX_SUPPORT\",\n  PROCUREMENT: \"CTX_SUPPLY_CHAIN\",\n  PERSONAL: \"CTX_PERSONAL\",\n  BIZOPS: \"CTX_BIZOPS\",\n  IT_ADMIN: \"CTX_BIZOPS\",\n  STUDENT_TEACHER: \"CTX_PERSONAL\",\n};\n```\n\n#### WorkspaceShellNew.tsx (725 lines)\n**Purpose:** Main workspace UI shell; handles navigation, views, and AI layer\n\n**Structure:**\n- **2 Primary Views:** Personal | Work\n  - Personal: Tasks, Calendar, Notes (same for everyone)\n  - Work: Domain-specific content (role-based)\n- **Navigation:** Header tabs (not sidebar context switcher)\n- **AI Layer:** Hidden by default; Cmd+K activation opens cognitive drawer\n- **Content Router:** Lazy-loads domain modules based on active path\n\n**Key Features:**\n- Icon mapping (60+ icons from Lucide)\n- Command palette (⌘K)\n- Notification center\n- Domain/workspace selector dropdown\n- Real-time status watching via `useActionRealtime` hook\n- Demo data banner (development)\n\n#### ContentRouter.tsx\n**Purpose:** Dynamic module loading and routing\n\nRoutes requests to domain-specific views:\n- Lazy-loads React components based on path\n- Passes context (domain, department, user data)\n- Integrates with Hydration Fabric for state sync\n\n---\n\n## 3. Design System & Styling\n\n### Color Palette (from `app.css`)\n```\nBrand Primary (Soft Navy):    #5A7AA0 (muted, professional)\nBrand Accent (Warm Coral):    #C97A8A (inviting, balanced)\nBackground (Warm Off-white):  #F7F8FA (easy on eyes)\nGrays (Warm undertones):      #1A2230 → #FAFBFC (9 levels)\nSuccess:                      #5BA88A (muted green)\nWarning:                      #D4A05A (muted orange)\nError:                        #C75B5B (muted red)\n```\n\n**Philosophy:** Soft, eye-friendly palette with reduced saturation. Avoids harsh whites/blacks.\n\n### Design Tokens (`app.css`)\n```css\n--brand-primary: #5A7AA0\n--brand-accent: #C97A8A\n--brand-bg: #F7F8FA\n--background: #F7F8FA\n--foreground: #2A3442\n--primary: #5A7AA0\n--secondary: #F0F2F5\n--muted: #E8EEF4\n--accent: #F5E8EB\n--destructive: #C75B5B\n--border: #E1E5EB\n--ring: #5A7AA0\n```\n\n### Tailwind Configuration\n- **Plugin:** `@tailwindcss/vite` (v4)\n- **Alias:** `@` → `src/`\n- **CSS Normalization:** @import \"tailwindcss\"\n- **Layout Priority:** Flexbox first, Grid for 2D layouts\n\n---\n\n## 4. Authentication & Authorization\n\n### Auth System (Supabase PKCE)\nLocated in `components/core/auth/`:\n- **Provider:** `AuthProvider` (Supabase)\n- **Methods:** Google SSO, GitHub SSO, Email/Password\n- **Flow:** Login page → Signup page → Onboarding → Workspace\n\n### RBAC (Role-Based Access Control)\n- **Package:** `@integratewise/rbac`\n- **Stored in:** `components/core/rbac/`\n- **Supports:** Department-based roles, domain-scoped permissions\n\n---\n\n## 5. Data Management & State\n\n### Hydration Fabric (5-Provider System)\nLocated in `components/core/hydration/`:\n\n**5 Data Sources:**\n1. **Spine Provider** — Adaptive Spine (SSOT via BFF Worker)\n2. **REST Provider** — Direct API calls\n3. **Doppler Provider** — Environment config\n4. **KV Provider** — Key-value cache (Cloudflare KV)\n5. **Static Provider** — Hardcoded fallbacks\n\n**Usage:**\n```typescript\nconst { data, isLoading } = useFabricStatus()\nconst slots = useScopedSlots()\n```\n\n### TanStack React Query (v5.59.0)\n- **Configured in AppShell.tsx**\n- **Default Options:**\n  - staleTime: 60,000ms\n  - retry: 1\n- **Integration:** Works with Supabase realtime for live sync\n\n### Supabase Integration\n- **Package:** `@integratewise/supabase`\n- **Auth:** Native Supabase Auth (PKCE)\n- **Realtime:** WebSocket subscriptions for live updates\n- **Database:** PostgreSQL SSOT via Spine\n\n---\n\n## 6. The 12 Domain Views (L1 Workspace)\n\nEach domain has its own directory under `apps/web/src/components/l1/domains/`:\n\n| Domain                | Code Dir                  | Purpose                              | Views (est.) |\n| ------------------- | ----------------------- | ----------------------------------- | ---------- |\n| Account Success     | `account-success/`      | CS/onboarding/retention/churn       | 40+        |\n| Sales Operations    | `salesops/`             | Pipeline, forecasting, quota mgmt   | 20+        |\n| Revenue Operations  | `revops/`               | Revenue health, expansion, upsell   | 20+        |\n| Marketing           | `marketing/`            | Campaigns, leads, engagement        | 20+        |\n| Finance             | `finance/`              | Metrics, forecasts, P&L             | 15+        |\n| BizOps              | `bizops/`               | Business operations, KPIs           | 15+        |\n| Product Engineering | `product-engineering/`  | Product health, bugs, features      | 20+        |\n| Service/Support     | `service/`              | Support tickets, SLAs, satisfaction | 20+        |\n| Procurement         | `procurement/`          | Supply chain, vendor mgmt           | 15+        |\n| IT Admin            | `it-admin/`             | Systems, access, compliance         | 15+        |\n| Personal            | `personal/`             | Tasks, calendar, notes              | 10+        |\n| Student/Teacher     | `student-teacher/`      | Education domain                    | 10+        |\n\n**View Pattern:**\n```\ndomain-name/\n├── views/\n│   ├── [view-name].tsx\n│   ├── [another-view].tsx\n│   └── ...40+ view files\n├── index.ts (exports all views)\n└── config.ts (view metadata, roles, paths)\n```\n\n---\n\n## 7. Cognitive Layer (L2) — AI Integration\n\nLocated in `components/l2/`:\n\n### Components\n- **`cognitive/`** — L2 drawer (Cmd+K overlay)\n- **`spine/`** — Spine client for context retrieval\n- **`goal-framework/`** — Goal-driven AI interactions\n- **`bridge/`** — L1 ↔ L2 event communication\n\n### Event System\n**Custom events dispatched to L2:**\n- `iw:evidence:open` — Open evidence panel\n- `iw:cognitive:open` — Open specific cognitive surface\n- `open-cognitive-layer` — Generic open (defaults to signals)\n\n### AI Governance\n- **Approval-gated:** AI suggests actions, waits for user approval\n- **Evidence chains:** Every recommendation backed by data\n- **Read-only initially:** AI generates proposals, users execute\n\n---\n\n## 8. Onboarding & Activation (L0)\n\nLocated in `components/activation/`:\n\n### OnboardingFlow.tsx (6 Steps)\n1. **Tenant Creation** — Org setup\n2. **Plan Selection** — Pricing tier\n3. **Domain Accelerator** — Industry/use case\n4. **Connector OAuth** — First data connection\n5. **Profile Setup** — User info\n6. **Workspace Launch** — Ready to use\n\n### LoaderPhase1.tsx\n- Displays loading spinner before workspace mounts\n- Hydrates fabric from 5 data sources\n- Waits for auth + tenant + workspace config\n\n---\n\n## 9. Backend Architecture (Cloudflare Workers)\n\n### Services Stack\nLocated in `services/`:\n\n**Core Services:**\n- **gateway** — API ingress point (routes traffic)\n- **spine-v2** — Intelligent data layer (SSOT)\n- **workflow** — Workflow orchestration\n- **pipeline** — 8-stage data normalization\n- **connector** — Connector manager (OAuth, sync)\n- **intelligence** — AI & predictions\n- **l2** — Cognitive layer backend\n- **normalizer** — Schema normalization\n\n**Supporting Services:**\n- **knowledge** — Knowledge store integration\n- **billing** — Paywall & subscriptions\n- **store** — Data persistence\n- **admin** — Admin APIs\n- **agents** — AI agents\n- **act** — Action execution engine\n- **govern** — Governance & approval workflows\n- **loader** — Onboarding data loader\n- **tenants** — Tenant management\n- **webhook-ingress** — Webhook receiver\n- **connector-sync** — Sync orchestration\n\n**Deployment:** Cloudflare Workers (edge-first serverless)\n\n---\n\n## 10. Data Flows (3 Paths)\n\n### Flow A: Structured Truth\nCRM → Connectors → Pipeline → Normalizer → Spine (PostgreSQL)\n\n**Data:** CRM, billing, support, finance, project systems\n\n### Flow B: Unstructured Context\nDocuments → Knowledge Bank → Spine (vector store)\n\n**Data:** Emails, notes, files, transcripts, PDFs\n\n### Flow C: AI Interactions\nUser → Cognitive Layer → Spine (session memory)\n\n**Data:** Conversation context, decisions, approvals\n\n---\n\n## 11. Shared Packages\n\n### `packages/types/`\nGlobal TypeScript interfaces shared across monorepo\n\n### `packages/config/`\nConfiguration management (environment, feature flags, etc.)\n\n### `packages/db/`\nDatabase utilities (query builders, migrations)\n\n### `packages/supabase/`\nSupabase client wrapper + auth provider\n\n### `packages/rbac/`\nRole-based access control system\n\n### `packages/api/`\nAPI client utilities\n\n### `packages/connectors/`\nData connector implementations (Salesforce, HubSpot, etc.)\n\n### `packages/knowledge-bank-ui/`\nUI components for knowledge layer\n\n---\n\n## 12. Known Architectural Patterns\n\n### Component Organization\n```\ncomponents/\n├── core/         # Platform infrastructure (auth, hydration, providers)\n├── l1/           # User workspace (what user sees)\n├── l2/           # AI cognitive layer (behind scenes)\n├── activation/   # Onboarding & auth flows\n├── connectivity/ # Connector UX\n├── common/       # Shared utilities & layouts\n└── _deprecated/  # Legacy (v1 architecture)\n```\n\n### State Management Pattern\n1. **Global:** AuthProvider, SpineProvider, HydrationFabric\n2. **Module-level:** React Query (TanStack)\n3. **Component-level:** useState (when appropriate)\n4. **Realtime:** Supabase subscriptions\n5. **Transient:** Context (goal context, tenant context)\n\n### Routing Pattern\n- **Router:** React Router v7.0.0\n- **Routes:** `routes.tsx` (centralized)\n- **Lazy loading:** ContentRouter (domain-specific)\n- **Deep linking:** Supported via path + query params\n\n---\n\n## 13. Design System (Figma-Integrated)\n\n### Token Generation\n- **Script:** `scripts/extract-figma-tokens.js`\n- **Output:** `src/integratewise-figma-tokens.json`\n- **CSS:** `src/figma-theme-merged.css`\n\n### Component Library\n- **Radix UI** — 30+ unstyled, accessible components\n- **Custom Styling** — Tailwind classes + design tokens\n- **Theming:** CSS custom properties + Tailwind config\n\n---\n\n## 14. Build & Deployment\n\n### Development\n```bash\npnpm install        # Install dependencies\npnpm dev            # Start Vite dev server (port 3000)\npnpm run typecheck  # Type check all packages\npnpm run lint       # Lint all packages\n```\n\n### Production\n```bash\npnpm build          # Build all packages (Turbo)\npnpm test           # Run all tests\npnpm preflight      # Full preflight: install → typecheck → lint → test → build\n```\n\n### Deployment Targets\n- **Web App:** Cloudflare Pages (SPA)\n- **Backend:** Cloudflare Workers\n- **Database:** Supabase PostgreSQL\n- **Vector Store:** (Likely Pinecone or Weaviate for embeddings)\n\n---\n\n## 15. Code Quality & Testing\n\n### Linting\n- **Configured in:** `turbo.json` and individual package configs\n- **Tools:** ESLint, TypeScript\n\n### Type Checking\n- **Language:** TypeScript 5.5.0\n- **Strict mode:** Likely enabled\n- **Types sourced from:** `packages/types/`\n\n### Testing\n- **Framework:** Playwright (E2E)\n- **Scripts:** `test:e2e`, `test:e2e:ui`\n- **Integration tests:** `packages/integration-tests/`\n\n---\n\n## 16. Known Limitations & Technical Debt\n\n### Issues from Branch `ai-connector-error`\nThis branch addresses errors in AI connector integration. Key area to review:\n- AI/connector error handling\n- Fallback behaviors\n- Logging & observability\n\n### Potential Improvements\n1. **Component Library:** No dedicated shadcn/ui setup; building custom components could speed development\n2. **State Management:** React Query + Context works but could benefit from Zustand for complex cross-module state\n3. **Schema Validation:** No visible Zod/Yup setup; important for connector contract validation\n4. **Testing:** E2E tests exist but unit test coverage unclear\n5. **Error Handling:** Error boundaries exist but error recovery patterns could be more robust\n6. **Performance:** No visible optimization work (lazy loading partially implemented)\n7. **Documentation:** README is good; inline component docs could be more thorough\n\n---\n\n## 17. UI/UX Opportunities\n\n### Current State\n- ✅ Clean, professional design system (soft palette)\n- ✅ Radix UI foundation (accessible)\n- ✅ Animation framework (Framer Motion)\n- ✅ 12 domain-specific views (comprehensive)\n- ✅ Cognitive layer integration (innovative)\n\n### Opportunities for Improvement\n1. **Workspace Navigation** — Sidebar could be more discoverable (currently header tabs + dropdown)\n2. **Domain Views** — Some views may feel cluttered; could benefit from progressive disclosure\n3. **Mobile Responsiveness** — Currently focused on desktop; mobile UX needs work\n4. **Onboarding UX** — 6 steps is comprehensive but could be more engaging\n5. **Help & Discoverability** — Help widget exists but contextual guidance could be stronger\n6. **Dark Mode** — Brand palette is light-focused; dark mode support missing\n7. **Accessibility** — Radix UI base is good, but keyboard navigation could be enhanced\n8. **Performance Indicators** — Loading states, skeleton screens, and progress indicators need review\n\n---\n\n## 18. Key Files & Entry Points\n\n### Frontend Entry\n- **Vite Entry:** `apps/web/src/main.tsx`\n- **React Root:** `apps/web/src/App.tsx`\n- **Workspace:** `apps/web/src/AppShell.tsx`\n\n### Config Files\n- **Workspace:** `pnpm-workspace.yaml`\n- **Turbo:** `turbo.json`\n- **Vite:** `apps/web/vite.config.ts`\n- **Tailwind:** `@tailwindcss/vite` plugin (no separate config file)\n- **TypeScript:** `apps/web/tsconfig.json`\n\n### Routes\n- **React Router:** `apps/web/src/routes.tsx`\n- **Domain Navigation:** `apps/web/src/components/l1/workspace/workspace-config.ts`\n\n### Styles\n- **Global CSS:** `apps/web/src/app.css` (design tokens)\n- **Figma Tokens:** `apps/web/src/figma-theme-merged.css`\n- **Design Tokens:** `apps/web/src/styles/design-tokens.css`\n\n---\n\n## 19. Next Steps for UI Work\n\nBased on this review, here are recommended UI improvements:\n\n### High Priority\n1. **Improve Workspace Discoverability**\n   - Consider sidebar instead of header-only nav\n   - Add breadcrumbs for context\n   \n2. **Enhance Onboarding**\n   - Make 6 steps more visually engaging\n   - Add progress indicators\n   - Reduce cognitive load\n\n3. **Mobile Responsiveness**\n   - Workspace shell mobile layout\n   - Domain views mobile-optimized\n   - Touch-friendly navigation\n\n4. **Dark Mode**\n   - Extend design tokens for dark theme\n   - Test contrast ratios\n   - Add mode toggle\n\n### Medium Priority\n1. **Accessibility Audit** — WCAG 2.1 AA compliance check\n2. **Performance Optimization** — Skeleton screens, code splitting review\n3. **Help System** — Contextual tooltips, guided tours\n4. **Error States** — Improve error messages and recovery options\n\n### Lower Priority\n1. **Component Documentation** — Storybook setup\n2. **Design System Website** — Figma + Storybook integration\n3. **Internationalization** — i18n setup if global expansion planned\n\n---\n\n## Summary\n\nIntegrateWise is a **well-engineered, sophisticated workspace application** built on solid architectural principles. The monorepo is organized, the component structure is logical, and the design system is consistent. The codebase is **production-ready but has room for modern UI/UX improvements** — particularly around navigation discoverability, mobile responsiveness, and dark mode support.\n\nThe AI integration (L2 cognitive layer) is innovative and governance-focused, making this a unique workspace product rather than just another dashboard.\n\n---\n\n**Reviewed by:** v0 Assistant  \n**Confidence Level:** 95% (based on code exploration)  \n**Last Updated:** May 18, 2026\n"}