Multi-Tenant Auto Detailing SaaS Architecture
Comprehensive architecture and coding rules for building a scalable multi-tenant auto detailing business management platform using Next.js App Router.
Tech Stack
**Framework:** Next.js (App Router)**Language:** TypeScript (strict, no `any` types)**Authentication:** Clerk with RBAC**Database:** Convex (with MongoDB multi-tenant architecture)**Styling:** Tailwind CSS (utility-first)**UI Components:** ShadCN-UI**Visualization:** ShadCN-Graphs**AI/ML:** Ollama deep learning integration**Payments:** Stripe**Calendar:** Google Calendar (AI-powered scheduling)**Communication:** Google Chat integration**Hosting:** Vercel**File Storage:** Convex file storage + AI vector searchRole-Based Access Control (RBAC)
Implement strict role-based permissions using Clerk:
Admin Role
Access all featuresManage tenants (detailers)Manage clientsManage assessmentsView all analyticsDetailer Role
Read services, pricing, and assessmentsManage appointmentsManage clientsTake paymentsAccess dedicated dashboardConfigure pricing modelsClient Role
Access personal assessmentsSchedule appointmentsView estimatesCommunicate with detailerProvide paymentsUpload images/videos for assessmentsCode Quality Standards
1. **TypeScript Strict Mode:** No `any` types allowed. Use proper type definitions and interfaces.
2. **Developer Tooling:**
- ESLint configuration
- Prettier for code formatting
- EditorConfig for consistency
3. **Component Architecture:**
- Use ShadCN-UI reusable components
- Implement customizable theming
- Follow utility-first Tailwind CSS approach
Key Features to Implement
Authentication & Security
Clerk authentication with RBACInvite-only application accessResource authorization based on rolesMulti-tenant data isolationClient Self-Assessment
Vehicle information capture formsImage and video upload functionalityAI-powered assessment analysisEstimate generation based on assessment + pricing modelsAppointment Management
Google Calendar integrationAI-powered schedulingAutomated appointment remindersBooking notificationsPayment Processing
Stripe integration for paymentsSubscription management (cancellations, updates)Dynamic pricing models per detailerMarketing & Branding
Tenant-specific QR codes for self-marketingCustomizable theming per tenantSub-domain management via VercelCommunication
Google Chat integration for real-time supportNotification system for bookings and servicesRating and review systemAnalytics & Insights
Business analytics dashboardShadCN-Graphs for visualizationsPerformance metricsKnowledge Base
User guides and tutorialsComprehensive documentationDatabase Architecture
**Multi-tenant structure:** Separate data by tenant using MongoDB collections**Convex features:** - Real-time database
- File storage for images/videos
- AI vector search for assessments
**Data isolation:** Ensure tenant data separation at query levelScalability Requirements
Design system to handle minimum 10,000 concurrent usersOptimize Convex queries for performanceLeverage Vercel edge functions where appropriateImplement caching strategiesDevelopment Workflow
1. Follow Next.js App Router conventions
2. Use TypeScript strict mode throughout
3. Implement proper error handling and validation
4. Write reusable components with ShadCN-UI
5. Test RBAC permissions for all protected routes
6. Optimize for mobile responsiveness
7. Implement proper loading and error states
Integration Checklist
[ ] Clerk authentication configured with custom roles[ ] Convex database schema with multi-tenant architecture[ ] Stripe webhook handlers for payment events[ ] Google Calendar OAuth and scheduling logic[ ] Google Chat integration for support[ ] Ollama model integration for AI features[ ] Image/video upload with Convex file storage[ ] QR code generation for tenant marketing[ ] ShadCN-Graphs for analytics visualization[ ] Automated email/SMS reminders[ ] Rating and review system[ ] Feedback mechanism for continuous improvementImportant Notes
Never bypass RBAC checks in API routesAlways validate tenant context in database queriesSanitize user uploads (images/videos)Implement proper error boundariesUse environment variables for all third-party API keysFollow Vercel deployment best practicesMonitor Convex function execution timesImplement proper logging for debugging