{"slug":"business/MONOREPO_STRUCTURE","title":"IntegrateWise Monorepo Structure","section":"business","sectionLabel":"Business","status":"unclassified","type":"document","path":"business/MONOREPO_STRUCTURE.mdx","bytes":14577,"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## High-Level Vision\n\n```\nintegratewise/\n├── apps/                      # User-facing applications\n│   ├── ai-workspace/          # Flagship app (L3 Twin + L4 Memory + L2 Intelligence)\n│   ├── workbench-sales/       # Sales (Coming v1.1)\n│   ├── workbench-cs/          # Customer Success (Coming v1.1)\n│   ├── wise-docs/             # Documentation (Coming v1.2)\n│   ├── wise-ops/              # Operations (Coming v1.2)\n│   ├── wise-branding/         # Branding (Coming v1.3)\n│   ├── wise-erms/             # People/HRIS (Coming v1.3)\n│   └── admin/                 # Settings & platform admin\n│\n├── packages/                  # Shared platform services & UI\n│   ├── platform/\n│   │   ├── gateway/           # Request routing, identity resolution\n│   │   ├── spine/             # Adaptive Spine SDK\n│   │   ├── memory/            # Memory service SDK\n│   │   ├── entity360/         # Entity resolution\n│   │   ├── governance/        # Policy enforcement\n│   │   └── skills/            # Reusable actions\n│   │\n│   ├── auth/\n│   │   ├── stack-config/      # Stack Auth setup\n│   │   ├── middleware/        # Auth middleware\n│   │   └── hooks/             # useAuth, useSession, etc.\n│   │\n│   ├── ui/\n│   │   ├── components/        # shadcn components + custom\n│   │   ├── hooks/             # useWorkbench, useTwin, etc.\n│   │   ├── layouts/           # AppShell, AiWorkspaceShell, etc.\n│   │   └── theme/             # Design tokens, colors, typography\n│   │\n│   ├── design-system/         # Tailwind config, CSS variables\n│   ├── shared/                # Utilities, types, constants\n│   └── api-client/            # Generated API client\n│\n├── services/                  # Backend services (non-Next.js)\n│   ├── gateway/               # API gateway\n│   ├── spine/                 # Spine service\n│   ├── memory/                # Memory service\n│   ├── loader/                # Data loader\n│   ├── normalizer/            # Data normalizer\n│   └── identity/              # Identity service\n│\n├── infrastructure/            # Deployment, CI/CD, monitoring\n│   ├── docker/\n│   ├── k8s/\n│   ├── terraform/\n│   └── monitoring/\n│\n├── docs/                      # Architecture, guides, specs\n│   ├── architecture/          # System design docs\n│   ├── api/                   # API reference\n│   ├── guides/                # How-to guides\n│   └── specs/                 # Release specs, RFCs\n│\n└── scripts/                   # Development & deployment scripts\n    ├── setup.sh\n    ├── dev.sh\n    └── deploy.sh\n```\n\n---\n\n## apps/ — User-Facing Applications\n\nEach app is a full Next.js 16 application that consumes platform services via packages/.\n\n### ai-workspace/\n\n**Current: ✅ Live**\n\nEntry point for AI-first users. Primary Release 1.0 app.\n\n```\napps/ai-workspace/\n├── app/\n│   ├── layout.tsx             # Root layout with providers\n│   ├── page.tsx               # AI Home\n│   ├── (workspace)/\n│   │   ├── layout.tsx         # AI Workspace layout\n│   │   ├── chat/page.tsx      # Twin Chat\n│   │   ├── memory/page.tsx    # Memory Search\n│   │   └── actions/page.tsx   # Recent Actions\n│   └── api/\n│       ├── chat/route.ts      # Chat API\n│       └── memory/route.ts    # Memory API\n├── components/\n│   ├── ai-home/\n│   ├── twin-chat/\n│   ├── memory-search/\n│   └── shared/\n├── hooks/\n│   ├── useChat.ts\n│   ├── useMemory.ts\n│   └── useTwin.ts\n├── styles/\n│   └── ai-workspace.css       # App-specific overrides\n└── package.json\n```\n\n### workbench-sales/ (Shell)\n\n**Current: 🟡 Navigation Only**\n\nComing v1.1 as a full application.\n\n```\napps/workbench-sales/\n├── app/\n│   ├── layout.tsx\n│   ├── page.tsx               # Dashboard (shell)\n│   ├── accounts/page.tsx      # Coming soon\n│   ├── opportunities/page.tsx # Coming soon\n│   └── twin/page.tsx          # Coming soon\n├── components/\n│   ├── dashboard/\n│   └── coming-soon-banner/\n└── package.json\n```\n\n### workbench-cs/ (Shell)\n\n**Current: 🟡 Navigation Only**\n\nComing v1.1.\n\n### wise-docs/ (Shell)\n\n**Current: 🟡 Navigation Only**\n\nComing v1.2.\n\n### wise-ops/ (Shell)\n\n**Current: 🟡 Navigation Only**\n\nComing v1.2.\n\n### wise-branding/ (Shell)\n\n**Current: 🟡 Navigation Only**\n\nComing v1.3.\n\n### wise-erms/ (Shell)\n\n**Current: 🟡 Navigation Only**\n\nComing v1.3.\n\n### admin/\n\n**Current: 🟡 Partial Implementation**\n\nSettings and platform administration.\n\n```\napps/admin/\n├── app/\n│   ├── settings/page.tsx      # Organization settings\n│   ├── users/page.tsx         # User directory\n│   ├── roles/page.tsx         # Role management\n│   ├── connectors/page.tsx    # Connected apps\n│   └── audit/page.tsx         # Audit log\n└── components/\n    ├── user-form/\n    ├── role-editor/\n    └── connector-manager/\n```\n\n---\n\n## packages/ — Shared Platform\n\n### platform/gateway/\n\n**SDK for Gateway access.**\n\n```\npackages/platform/gateway/\n├── src/\n│   ├── gateway-client.ts      # Main client\n│   ├── types/\n│   │   ├── requests.ts\n│   │   └── responses.ts\n│   └── hooks/\n│       ├── useGateway.ts\n│       └── useIdentity.ts\n├── tests/\n├── package.json\n└── README.md\n```\n\nUsage in apps:\n\n```typescript\n\nconst { user, org, role } = useGateway()\nconst users = await gateway.getUsers()\n```\n\n### platform/spine/\n\n**SDK for Adaptive Spine access.**\n\n```\npackages/platform/spine/\n├── src/\n│   ├── spine-client.ts\n│   ├── types/\n│   │   ├── schema.ts          # Entity types\n│   │   └── operations.ts\n│   └── hooks/\n│       ├── useSpine.ts\n│       ├── useCustomers.ts\n│       ├── useProjects.ts\n│       └── useTasks.ts\n├── tests/\n├── package.json\n└── README.md\n```\n\nUsage in apps:\n\n```typescript\n\nconst { customers, loading } = useSpine().getCustomers()\nconst customer = await spine.getEntityById(\"customer\", id)\n```\n\n### platform/memory/\n\n**SDK for Memory access.**\n\n```\npackages/platform/memory/\n├── src/\n│   ├── memory-client.ts\n│   ├── types/\n│   │   ├── conversation.ts\n│   │   ├── decision.ts\n│   │   └── timeline.ts\n│   └── hooks/\n│       ├── useMemory.ts\n│       ├── useConversations.ts\n│       ├── useTimeline.ts\n│       └── useSearch.ts\n├── tests/\n├── package.json\n└── README.md\n```\n\n### platform/entity360/\n\n**SDK for Entity360 resolution.**\n\nUnified view of any entity (customer, project, person, etc.).\n\n```\npackages/platform/entity360/\n├── src/\n│   ├── entity360-client.ts\n│   ├── types/\n│   │   └── entity.ts\n│   └── hooks/\n│       └── useEntity360.ts\n└── package.json\n```\n\nUsage:\n\n```typescript\nconst entity = await entity360.resolve(\"customer\", customerId)\n// Returns customer data + relationships + context\n```\n\n### platform/governance/\n\n**Policy enforcement SDK.**\n\n```\npackages/platform/governance/\n├── src/\n│   ├── governance-client.ts\n│   ├── types/\n│   │   ├── policy.ts\n│   │   ├── context.ts\n│   │   └── decision.ts\n│   └── hooks/\n│       ├── usePolicy.ts\n│       └── useCanAccess.ts\n└── package.json\n```\n\n### platform/skills/\n\n**Reusable actions SDK.**\n\n```\npackages/platform/skills/\n├── src/\n│   ├── skill-registry.ts\n│   ├── types/\n│   │   └── skill.ts\n│   ├── builtin/\n│   │   ├── send-email.ts\n│   │   ├── create-task.ts\n│   │   ├── update-customer.ts\n│   │   └── send-message.ts\n│   └── hooks/\n│       ├── useSkills.ts\n│       └── useExecuteSkill.ts\n└── package.json\n```\n\n### auth/\n\n**Authentication setup & hooks.**\n\n```\npackages/auth/\n├── src/\n│   ├── stack-provider.tsx     # StackProvider wrapper\n│   ├── middleware.ts          # Auth middleware\n│   ├── types/\n│   │   ├── user.ts\n│   │   ├── session.ts\n│   │   └── auth.ts\n│   └── hooks/\n│       ├── useAuth.ts\n│       ├── useUser.ts\n│       └── useSession.ts\n├── tests/\n├── package.json\n└── README.md\n```\n\n### ui/\n\n**Shared UI components & design system.**\n\n```\npackages/ui/\n├── src/\n│   ├── components/            # shadcn + custom\n│   │   ├── sidebar/\n│   │   ├── card/\n│   │   ├── button/\n│   │   ├── input/\n│   │   ├── dialog/\n│   │   └── custom/\n│   │       ├── app-shell/\n│   │       ├── ai-workspace-shell/\n│   │       └── navigation/\n│   ├── hooks/\n│   │   ├── useWorkbench.ts\n│   │   ├── useTwin.ts\n│   │   └── useTheme.ts\n│   ├── layouts/\n│   │   ├── app-layout.tsx\n│   │   ├── workspace-layout.tsx\n│   │   └── admin-layout.tsx\n│   ├── theme/\n│   │   ├── colors.ts\n│   │   ├── typography.ts\n│   │   └── tokens.ts\n│   └── styles/\n│       └── globals.css\n├── tests/\n├── package.json\n└── README.md\n```\n\n### design-system/\n\n**Tailwind & design tokens.**\n\n```\npackages/design-system/\n├── tailwind.config.ts\n├── globals.css\n├── tokens.css               # CSS variables\n├── src/\n│   ├── colors.ts\n│   ├── spacing.ts\n│   ├── typography.ts\n│   └── theme.ts\n└── package.json\n```\n\n### shared/\n\n**Utilities, types, constants.**\n\n```\npackages/shared/\n├── src/\n│   ├── types/\n│   │   ├── user.ts\n│   │   ├── org.ts\n│   │   ├── entity.ts\n│   │   └── errors.ts\n│   ├── utils/\n│   │   ├── format.ts\n│   │   ├── validate.ts\n│   │   ├── parse.ts\n│   │   └── api.ts\n│   ├── constants/\n│   │   ├── routes.ts\n│   │   ├── roles.ts\n│   │   └── permissions.ts\n│   └── hooks/\n│       ├── useLocalStorage.ts\n│       ├── useAsync.ts\n│       └── useDebounce.ts\n├── tests/\n├── package.json\n└── README.md\n```\n\n### api-client/\n\n**Generated API client (if using OpenAPI/code-gen).**\n\n```\npackages/api-client/\n├── src/\n│   ├── generated/            # Auto-generated from OpenAPI\n│   │   ├── chat.ts\n│   │   ├── spine.ts\n│   │   └── memory.ts\n│   └── client.ts\n└── package.json\n```\n\n---\n\n## services/ — Backend Services\n\nThese are separate services that may be deployed independently.\n\n### services/gateway/\n\nAPI Gateway service (Node.js or similar).\n\n### services/spine/\n\nAdaptive Spine service.\n\n### services/memory/\n\nMemory service.\n\n### services/loader/\n\nData loader service.\n\n### services/normalizer/\n\nData normalizer service.\n\n### services/identity/\n\nIdentity resolution service.\n\n---\n\n## Root package.json Scripts\n\n```json\n{\n  \"scripts\": {\n    \"dev\": \"turbo run dev --parallel\",\n    \"build\": \"turbo run build\",\n    \"test\": \"turbo run test\",\n    \"lint\": \"turbo run lint\",\n    \"type-check\": \"turbo run type-check\",\n    \"format\": \"prettier --write \\\"**/*.{ts,tsx,json,md}\\\"\",\n    \"clean\": \"turbo run clean && rm -rf node_modules\",\n    \"db:migrate\": \"cd services/spine && npm run migrate\",\n    \"ai-workspace:dev\": \"turbo run dev --filter=ai-workspace\",\n    \"ai-workspace:build\": \"turbo run build --filter=ai-workspace\",\n    \"admin:dev\": \"turbo run dev --filter=admin\"\n  }\n}\n```\n\n---\n\n## pnpm-workspace.yaml\n\n```yaml\npackages:\n  - 'apps/*'\n  - 'packages/*'\n  - 'packages/platform/*'\n  - 'services/*'\n  - 'infrastructure/*'\n```\n\n---\n\n## Dependency Guidelines\n\n- **apps/** depend on **packages/**\n- **packages/** depend on other **packages/** and **shared/**\n- **packages/** do NOT depend on **apps/**\n- **services/** are independent (deployed separately)\n- **All** depend on **shared/**\n\n---\n\n## Deployment Strategy\n\n### CI/CD Pipeline\n\n1. **Lint & Type Check** — All packages\n2. **Test** — All packages with tests\n3. **Build** — All packages\n4. **Build Docker Images** — One per service + one per app\n5. **Push to Registry** — Image per artifact\n6. **Deploy** — Services first, then apps\n\n### Service Deployment (k8s or cloud-run)\n\n```\ngateway/      → Internal load-balanced service\nspine/        → Scalable database + API\nmemory/       → Cache + storage\nloader/       → Job runner\nnormalizer/   → Job runner\nidentity/     → Microservice\n```\n\n### App Deployment (Vercel or similar)\n\n```\nai-workspace/ → Vercel\nadmin/        → Vercel\n(shells)      → Same Vercel project\n```\n\n---\n\n## Onboarding New Developer\n\n```bash\n# Clone repo\ngit clone https://github.com/integratewise/integratewise.git\ncd integratewise\n\n# Install dependencies\npnpm install\n\n# Start dev server (all apps)\npnpm dev\n\n# Or start specific app\npnpm ai-workspace:dev\n\n# Run tests\npnpm test\n\n# Type check\npnpm type-check\n```\n\n---\n\n## Release Process\n\n### Release 1.0\n- All packages in packages/\n- Single app: ai-workspace/\n- Shell apps: workbench-sales/, workbench-cs/, wise-docs/, wise-ops/, wise-branding/, wise-erms/\n- Admin app: admin/\n\n### Release 1.1\n- workbench-sales/ → Full implementation\n- workbench-cs/ → Full implementation\n\n### Release 1.2\n- wise-docs/ → Full implementation\n- wise-ops/ → Full implementation\n\n### Release 2.0\n- Additional workbenches (Finance, Executive, Projects)\n- New platform services as needed\n"}