Building a Scalable Monorepo Architecture
How we built and scaled a 7-app ecosystem serving 10,000+ users
Executive summary
A deep dive into how we architected and built the VietProHub ecosystem - a monorepo containing 7 Next.js applications with shared components, serving over 10,000 users with 99.9% uptime.
The Challenge
We needed to build multiple applications (public-facing and private) that shared code and design patterns while allowing independent deployment and scaling. The applications had different access levels, user bases, and requirements, but needed to maintain consistency.
Key problems
- 1Managing code sharing across 7 different applications
- 2Maintaining consistency in UI/UX across all apps
- 3Implementing different access control levels (public, private, role-based)
- 4Ensuring independent deployability while sharing dependencies
- 5Scaling to handle 10,000+ concurrent users
- 6Maintaining 99.9% uptime across all services
Constraints
- !Limited development team (3-5 developers)
- !Tight timeline (12 months for MVP)
- !Budget constraints for infrastructure
- !Need for rapid iteration and deployment
Our Solution
We implemented a Turborepo-based monorepo architecture with shared packages for common functionality. Each application is independently deployable but shares UI components, utilities, types, and business logic.
Monorepo Structure
Used Turborepo for efficient build caching and task orchestration. Organized code into apps/ and packages/ directories with clear separation of concerns.
- 7 applications in apps/ directory
- 10+ shared packages in packages/ directory
- Shared UI component library (@vietprohub/ui)
- Common utilities and hooks (@vietprohub/lib, @vietprohub/hooks)
- Shared TypeScript types (@vietprohub/types)
- Centralized configuration
Shared Component Library
Built a comprehensive UI component library with 50+ reusable components, ensuring consistency across all applications.
- 50+ accessible, responsive components
- Dark mode support built-in
- Comprehensive Storybook documentation
- TypeScript for type safety
- Tailwind CSS for styling
- Framer Motion for animations
Authentication & Authorization
Implemented Firebase Authentication with custom claims for role-based access control across all applications.
- Single sign-on (SSO) across all apps
- Role-based access control (RBAC)
- Custom claims for fine-grained permissions
- Session management with automatic refresh
- Secure middleware for protected routes
Infrastructure & Deployment
Leveraged Vercel for hosting with automatic deployments and Firebase for backend services.
- Vercel for hosting and CDN
- Firebase for authentication, database, and storage
- GitHub Actions for CI/CD
- Automated testing before deployment
- Preview deployments for pull requests
- Production monitoring with Sentry
Key technical decisions
Turborepo over Nx
Simpler configuration, better caching, and excellent Next.js integration
Firebase over custom backend
Faster development, built-in real-time features, and excellent scalability
Tailwind CSS over CSS-in-JS
Better performance, smaller bundle sizes, and easier theming
TypeScript everywhere
Type safety, better developer experience, and fewer runtime errors
Implementation Details
Project timeline
Phase 1: Foundation (Months 1-3)
- Set up monorepo structure with Turborepo
- Create shared UI component library
- Implement authentication system
- Build first two applications (Main, Blog)
Phase 2: Expansion (Months 4-6)
- Add Family and Kids applications
- Implement real-time features
- Create admin dashboard
- Set up CI/CD pipeline
Phase 3: Polish (Months 7-9)
- Add Work and Product applications
- Implement cross-app features
- Performance optimization
- Comprehensive testing
Phase 4: Launch (Months 10-12)
- Security hardening
- Load testing and optimization
- Documentation
- Production launch
Implementation challenges
Dependency Management
Solution: Used pnpm workspaces for efficient dependency management and deduplication
Build Performance
Solution: Leveraged Turborepo's caching to reduce build times by 70%
Type Safety Across Packages
Solution: Created shared types package and used TypeScript project references
Consistent Styling
Solution: Built design system with Tailwind CSS and documented in Storybook
Results & Impact
Key achievements
Business impact
Lessons Learned
Start with a solid foundation
Investing time in proper architecture and tooling upfront pays dividends later. Our monorepo structure has made adding new applications much faster.
Shared components are crucial
Building a comprehensive component library early ensured consistency and dramatically reduced development time for new features.
Type safety matters
TypeScript caught countless bugs before they reached production. The initial learning curve was worth it.
Automate everything
Our CI/CD pipeline and automated testing have prevented numerous issues and enabled confident deployments.
Monitor proactively
Setting up comprehensive monitoring and alerting early helped us maintain 99.9% uptime and catch issues before users noticed.
What we’d do differently
- Earlier implementation of E2E testing
- More comprehensive documentation from the start
- Better performance monitoring and optimization tools
- More structured approach to feature flags
Technologies used
In pictures
The project
See the full project
More details, screenshots, and information about VietProHub Ecosystem.
View project