Architectural Overview
This document provides a comprehensive overview of the NextJS Web Monorepo architecture, detailing the structure, components, and relationships within the Schwab development ecosystem.
High-Level Architecture
The NextJS Web Monorepo follows a structured approach that separates applications from shared packages, promoting code reusability and maintainability. The diagram below illustrates the hierarchical organization where the root nextjs-web repository contains two primary directories: apps/ for deployable applications and packages/ for shared libraries and utilities.
Each application in the apps/ directory serves specific business domains, from public-facing websites to internal tools and content management systems. The packages/ directory contains reusable components, utilities, and configurations that can be consumed by any application, eliminating code duplication and ensuring consistency across the ecosystem.
Repository Structure
Applications Layer
The applications layer consists of domain-specific NextJS applications, each serving different business requirements:
| Application | Purpose | Domain |
|---|---|---|
www.schwab.com | Public website and marketing | Public-facing |
client.schwab.com | Client portal and authenticated experiences | Client-facing |
nextapi.schwab.com | API services and backend functionality | Internal API |
nexttools.schwab.com | Internal tools and utilities | Internal tools |
client-central | Centralized client services | Client services |
meganav-mfe | Micro-frontend for navigation | Component library |
sanity-studio | Content management system (Sanity Studio) | CMS |
sanity-next | Sanity CMS frontend application | CMS Frontend |
storybook | Component documentation and showcase | Development |
docs | Technical documentation (Docusaurus) | Documentation |
beacon-docs | Design system documentation (Docusaurus) | Documentation |
Shared Packages Layer
The packages provide reusable functionality across applications:
| Package | Description | Type |
|---|---|---|
@schwab/ui | React component library with shadcn/ui integration | Components |
@schwab/utilities | Common utility functions and helpers | Utilities |
@schwab/security | Security utilities and authentication helpers | Security |
@schwab/server-actions | NextJS server actions and API utilities | Server |
@schwab/fetch | HTTP client and data fetching utilities | Data |
@schwab/processors | Data processing and transformation utilities | Processing |
@schwab/test | Testing utilities and shared test configurations | Testing |
@schwab/schema | Type definitions and validation schemas | Types |
@schwab/cli | Command-line tools and scripts | Tooling |
@schwab/transformer | Data transformation utilities | Processing |
@schwab/tsconfig | Shared TypeScript configurations | Configuration |
@schwab/twconfig | Shared Tailwind CSS configurations | Configuration |
@schwab/mock-data | Mock data for development and testing | Development |
Technology Stack
Core Technologies
Our technology stack is built on modern, production-ready tools that ensure scalability, maintainability, and developer experience. The frontend stack leverages React 19 with NextJS 15.2 for server-side rendering and static site generation, enhanced by TypeScript for type safety and TailwindCSS with shadcn/ui for consistent design systems.
The build and development ecosystem utilizes Turborepo for monorepo orchestration, pnpm for efficient package management, and Vercel for seamless deployment. Quality assurance is maintained through comprehensive testing with Jest, code quality enforcement via Biome, and architectural conformance validation.
Runtime Environment
| Technology | Version | Purpose |
|---|---|---|
| Node.js | 20.18 | Runtime environment |
| React | 19.0 | UI framework |
| NextJS | 15.2 | Full-stack framework |
| TypeScript | 5.8 | Type safety |
| TailwindCSS | 4.1 | Styling |
| Zod | 3.24 | Schema validation |
Build Pipeline Architecture
The build pipeline follows a systematic approach to ensure code quality and consistency across all applications and packages. Turborepo orchestrates the entire process, managing task dependencies and caching for optimal performance. The pipeline executes parallel build tasks including type checking, linting, testing, and compilation before proceeding to conformance validation and deployment.
This architecture ensures that all code changes meet quality standards through automated validation at each step, preventing issues from reaching production while maintaining fast build times through intelligent caching and parallelization.
Build Configuration
The build system is orchestrated through Turborepo with the following task dependencies:
- Build: Depends on package builds, outputs to
.next/**andstorybook-static/** - Development: Concurrent development servers with hot reloading
- Testing: Jest-based unit and integration tests
- Type Checking: TypeScript compilation validation
- Linting: Biome-based code quality checks
- Conformance: Vercel conformance rules validation
Data Flow Architecture
The data flow architecture illustrates how information moves through our ecosystem from external systems to frontend applications. External systems including Drupal CMS, Sanity CMS, RRBUS Services, Branch Services, SFMC, Launch Darkly, and Bynder DAM provide content, configuration, and business data.
The API layer acts as an intermediary, with nextapi.schwab.com serving as the primary API gateway, Server Actions handling server-side operations, and Fetch Utilities managing data retrieval. This layered approach ensures proper data transformation, validation, and security before reaching frontend applications, while maintaining clear separation of concerns and enabling independent scaling of different system components.
Component Architecture
UI Component Hierarchy
The UI component system is organized hierarchically through the @schwab/ui package, providing a comprehensive design system built on shadcn/ui components. The architecture categorizes components by complexity and purpose: basic components for fundamental UI elements, complex components for interactive widgets, layout components for page structure, and form components for user input.
This hierarchical organization ensures consistency across applications while enabling flexible composition and customization. All components are documented and showcased in Storybook, providing developers with visual examples, usage guidelines, and interactive testing capabilities.
Security Architecture
Security is implemented through multiple layers of protection, from authentication and authorization to data validation and secure communication protocols. The @schwab/security package provides standardized utilities for authentication, validation, and encryption, ensuring consistent security practices across all applications.
External security is enhanced through Launch Darkly's secure feature flag management, Vercel's edge security features, and Akamai's CDN-level protection. This multi-layered approach creates defense in depth, protecting against various attack vectors while maintaining performance and user experience.
Development Workflow
Local Development
The local development environment provides a consistent, containerized setup that mirrors production conditions while enabling rapid development iterations. Developers work within a Docker container running Red Hat Enterprise Linux 9.5, ensuring environment consistency across different development machines.
The development stack includes Node.js 20.18 for runtime, pnpm for efficient package management, and Turborepo for orchestrating development tasks. Hot reload capabilities enable immediate feedback during development, while browser preview provides real-time visualization of changes, creating an optimal developer experience for rapid prototyping and debugging.
Environment Matrix
| Environment | Purpose | Deployment |
|---|---|---|
| Local | Development and testing | Docker container |
| Development | Feature development | Vercel preview |
| SIT (System Integration Testing) | Integration testing | Vercel staging |
| Production | Live applications | Vercel production |
Deployment Architecture
The deployment architecture implements a robust CI/CD pipeline that automatically builds, tests, and deploys applications from GitHub repositories. Feature branches trigger preview deployments for testing and review, while the main branch deploys to production after successful validation.
GitHub Actions orchestrate the build and test processes, ensuring code quality before deployment to Vercel's platform. Vercel handles both preview and production deployments with automatic domain mapping, while Akamai CDN provides global distribution through edge locations, ensuring optimal performance and availability worldwide.
Monitoring & Observability
| Tool | Purpose | Integration |
|---|---|---|
| Vercel Analytics | Performance monitoring | Built-in |
| Launch Darkly | Feature flag monitoring | SDK integration |
| Splunk | Log aggregation | Custom logging |
| GitHub Actions | Build monitoring | CI/CD pipeline |
Package Dependencies
The package dependency structure illustrates how applications consume shared packages and their underlying dependencies. Applications primarily depend on our internal packages (@schwab/ui, @schwab/utilities, @schwab/security, @schwab/server-actions, and @schwab/fetch), which in turn depend on external libraries and frameworks.
This dependency hierarchy ensures that external library versions are managed centrally within shared packages, preventing version conflicts and reducing bundle size through deduplication. Each package encapsulates specific functionality and its dependencies, creating clear boundaries and enabling independent updates while maintaining compatibility across the ecosystem.
Configuration Management
Environment Variables
The system uses a comprehensive environment variable system for configuration:
- API Keys: Integration with external services
- Feature Flags: Runtime behavior control
- Build Configuration: Environment-specific builds
- Security Settings: Authentication and encryption
- Service URLs: External service endpoints
Shared Configurations
| Configuration Type | Package | Purpose |
|---|---|---|
| TypeScript | @schwab/tsconfig | Shared TS configurations |
| Tailwind CSS | @schwab/twconfig | Shared styling configurations |
| Testing | @schwab/test | Jest and testing configurations |
| Build | turbo.json | Monorepo build orchestration |
This architecture provides a scalable, maintainable foundation for the Schwab NextJS ecosystem, enabling efficient development, testing, and deployment of web applications across multiple domains and use cases.