{"slug":"operations/QUICK_START_TENANT_ROUTING","title":"Quick Start: Tenant Routing System","section":"operations","sectionLabel":"Operations","status":"unclassified","type":"document","path":"operations/QUICK_START_TENANT_ROUTING.mdx","bytes":7956,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n## What's New\n\nYour IntegrateWise app now has **multi-tenant support via subdomains**. Each tenant gets:\n\n- ā Branded landing page at their own subdomain\n- ā Customizable colors, logo, and copy\n- ā Industry-specific content (SaaS/Healthcare/Fintech)\n- ā Automatic tenant scoping for all features\n\n## Test It Locally\n\n### Start the dev server\n\n```bash\ncd apps/web\nnpm run dev\n```\n\n### Visit the demo workspaces\n\nOpen these URLs in your browser (on localhost:3000):\n\n| URL | Workspace | Industry | Color |\n| --------------------------------------- | ----------------- | ---------- | --------- |\n| http://saas-corp.localhost:3000 | SaaS Corp | SaaS | Blue š |\n| http://healthtech.localhost:3000 | HealthTech Inc | Healthcare | Green āļø |\n| http://fintech-solutions.localhost:3000 | Fintech Solutions | Fintech | Purple š° |\n| http://app.localhost:3000 | Workspace Picker | Hub | Default |\n\n### Try it out\n\nEach landing page has:\n\n1. **Navigation** with tenant logo and sign-in\n2. **Hero section** with industry-specific headline\n3. **Features grid** showing key capabilities\n4. **Industry section** with relevant stats\n5. **Call-to-action** buttons\n6. **Footer** with links\n\n### Test flows\n\n**Not signed in:**\n\n- Click \"Get Started\" or \"Sign In\" ā redirects to `/auth/sign-in`\n\n**Signed in, not onboarded:**\n\n- Click any CTA ā redirects to `/onboarding`\n\n**Signed in, onboarded:**\n\n- Click any CTA ā redirects to `/work`\n\n**Try tenant picker:**\n\n- Visit http://app.localhost:3000 ā see all workspaces\n- Click on any workspace card ā navigates to subdomain\n\n## How It Works\n\n### Subdomain Resolution\n\n```\nRequest: saas-corp.localhost:3000\n ā\nMiddleware reads Host header\n ā\nExtracts \"saas-corp\" subdomain\n ā\nLooks up tenant in DataProvider\n ā\nInjects X-Tenant-Slug & X-Tenant-Id headers\n ā\nRoutes to (tenant) route group\n ā\nTenantProvider loads tenant data\n ā\nLanding page gets branding from tenant.branding\n ā\nCSS variables apply colors & logo\n ā\nPage renders with industry-specific copy\n```\n\n### Available Hooks\n\n```typescript\n// In any client component inside (tenant) route group:\n\n const tenant = useTenant();\n\n return (\n
\n
{tenant?.name}
\n
{tenant?.branding?.tagline}
\n \n
\n );\n}\n```\n\n## File Structure\n\n```\napps/web/\nāāā middleware.ts # Subdomain routing\nāāā lib/\nā āāā context/\nā ā āāā tenant-context.tsx # React context for tenant\nā āāā data/\nā ā āāā types.ts # Extended Tenant type\nā ā āāā in-memory-provider.ts # Seed data + methods\nā āāā tenant-lookup.ts # (Optional) Lookup utility\nāāā components/\nā āāā tenant/\nā āāā landing-page.tsx # Per-tenant landing page\nā āāā tenant-picker.tsx # Workspace picker\nāāā app/\n āāā (tenant)/\n ā āāā layout.tsx # Tenant context wrapper\n ā āāā page.tsx # Landing route\n ā āāā onboarding/ # Tenant-scoped\n ā āāā work/ # Tenant-scoped\n āāā app/\n āāā page.tsx # Workspace picker\n```\n\n## Customizing Tenants\n\n### Add a new tenant\n\nEdit `lib/data/in-memory-provider.ts`:\n\n```typescript\nconst SEED_TENANTS: Record> = {\n \"my-company\": {\n name: \"My Company\",\n slug: \"my-company\",\n industry: \"saas\",\n environment: \"customer-zero\",\n status: \"active\",\n branding: {\n logoUrl: \"š\",\n primaryColor: \"#EC4899\",\n backgroundColor: \"#FCE7F3\",\n tagline: \"Custom tagline here\",\n },\n landing: {\n headline: \"Custom headline\",\n subhead: \"Custom subheading\",\n featuredPluginIds: [],\n featuredAgentIds: [],\n },\n createdAt: new Date().toISOString(),\n updatedAt: new Date().toISOString(),\n },\n // ... other tenants\n};\n```\n\nThen restart dev server and visit:\n\n```\nhttp://my-company.localhost:3000\n```\n\n### Customize branding\n\nUpdate the `branding` object:\n\n- `logoUrl`: emoji or image URL\n- `primaryColor`: hex color (e.g., \"#3B82F6\")\n- `backgroundColor`: hex color (e.g., \"#F0F9FF\")\n- `tagline`: short tagline\n\n### Customize landing copy\n\nUpdate the `landing` object:\n\n- `headline`: main heading\n- `subhead`: subheading\n- `featuredPluginIds`: array of plugin IDs to highlight\n- `featuredAgentIds`: array of agent IDs to highlight\n\n## Slug Requirements\n\nSlugs must be:\n\n- ā Lowercase alphanumeric + hyphens: `my-company`, `saas-corp`\n- ā 2-63 characters long\n- ā No leading/trailing hyphens\n- ā Not reserved: www, app, api, admin, docs, localhost, staging, dev\n- ā Not already taken\n\nUse the validation method:\n\n```typescript\nconst provider = getDataProvider();\nconst isValid = await provider.tenants.validateSlug(\"my-company\");\n// Returns true if valid and available\n```\n\n## Production Readiness\n\n### What's ready for production:\n\n- ā Subdomain routing\n- ā Tenant context propagation\n- ā Branding system\n- ā Landing page components\n- ā Error handling & fallbacks\n\n### What needs work for production:\n\n- ā ļø Move to persistent database (Neon PostgreSQL)\n- ā ļø Add admin UI for tenant provisioning\n- ā ļø Implement custom domain support (CNAME)\n- ā ļø Add caching layer (Redis) for slug lookups\n- ā ļø Set up RLS policies on database for tenant isolation\n- ā ļø Add audit logging for tenant operations\n\nSee `TENANT_ROUTING_IMPLEMENTATION.md` for full details.\n\n## Troubleshooting\n\n### Subdomain not resolving\n\n1. Check `/etc/hosts` on Mac/Linux or `C:\\Windows\\System32\\drivers\\etc\\hosts` on Windows\n2. Add: `127.0.0.1 saas-corp.localhost`\n3. Restart browser\n\nOr use the browser's developer tools to test:\n\n```javascript\n// In console:\nconsole.log(window.location.hostname); // should show subdomain\n```\n\n### Branding not applying\n\n1. Check browser DevTools ā Elements tab\n2. Look for `--primary-color` CSS variable on root element\n3. Verify tenant data loaded: check `useTenant()` return value\n4. Check network tab: confirm X-Tenant-Slug header sent\n\n### Tenant not found\n\n1. Check DataProvider has tenant slug: `npm run dev` and check console\n2. Verify slug matches exactly (case-sensitive)\n3. Check reserved list in `middleware.ts`\n4. Try accessing tenant picker first: http://app.localhost:3000\n\n## Next Features to Build\n\n### Suggested Enhancements\n\n1. **Admin Dashboard**\n - Create/edit/delete tenants\n - Manage branding\n - View usage stats\n - Team member management\n\n2. **Custom Domains**\n - Support CNAME mappings (acme.com ā acme.integratewise.com)\n - DNS validation\n - SSL certificate provisioning\n\n3. **Database Integration**\n - Migrate from in-memory to Neon\n - Add Redis caching\n - Implement RLS policies\n\n4. **Advanced Branding**\n - Upload custom fonts\n - Design theme builder\n - Custom CSS injection\n\n5. **Analytics**\n - Workspace creation tracking\n - Usage metrics per tenant\n - Admin reporting dashboard\n\n## Documentation\n\n- **Full Details**: See `TENANT_ROUTING_IMPLEMENTATION.md`\n- **Architecture**: See `TENANT_ARCHITECTURE.md`\n- **Delivery**: See `DELIVERY_SUMMARY.md`\n\n## Support\n\nFor questions or issues:\n\n1. Check the architecture diagrams in `TENANT_ARCHITECTURE.md`\n2. Review the data flow section in `DELIVERY_SUMMARY.md`\n3. Check component source code (well-commented)\n4. Test with the seed data tenants first\n\n---\n\n**Happy multi-tenant building!** š\n"}