This document describes the architecture and project structure of the TourGuideAI application.
The project follows a feature-based architecture, with shared code extracted into core modules:
src/
├── __mocks__/ # Jest mocks
├── api/ # API clients and interfaces
├── components/ # Reusable UI components
│ ├── common/ # Common shared components
│ └── Timeline/ # Timeline component
├── config/ # Frontend configuration
├── contexts/ # React contexts for state management
├── core/ # Core functionality and services
│ ├── api/ # API clients for external services
│ └── services/ # Shared application services
│ └── storage/ # Storage services (cache, local storage, sync)
├── features/ # Feature modules
│ ├── beta-program/ # Beta program management feature
│ │ ├── components/ # Beta program components
│ │ │ ├── admin/ # Admin components
│ │ │ ├── analytics/ # Analytics dashboard components
│ │ │ ├── auth/ # Authentication components
│ │ │ ├── community/ # Community components
│ │ │ ├── feature-request/ # Feature request components
│ │ │ ├── feedback/ # Feedback collection components
│ │ │ ├── onboarding/ # User onboarding components
│ │ │ ├── survey/ # Survey components
│ │ │ ├── task-prompts/ # Task prompt components
│ │ │ ├── user/ # User management components
│ │ │ ├── user-testing/ # User testing components
│ │ │ └── ux-audit/ # UX audit components
│ │ ├── contexts/ # Beta program contexts
│ │ ├── hooks/ # Beta program hooks
│ │ ├── layouts/ # Beta program layouts
│ │ ├── pages/ # Beta program pages
│ │ ├── routes/ # Beta program routes
│ │ └── services/ # Beta program services
│ │ ├── analytics/ # Analytics services
│ │ └── feedback/ # Feedback services
│ ├── map-visualization/ # Map visualization feature
│ ├── travel-planning/ # Travel itinerary planning feature
│ │ ├── components/ # Travel planning components
│ │ └── services/ # Travel planning services
│ └── user-profile/ # User profile management feature
├── pages/ # Page components
├── services/ # Frontend services
│ └── storage/ # Storage services
├── styles/ # Global styles and themes
├── tests/ # Frontend test files
├── utils/ # Utility functions
├── App.js # Main application component
└── index.js # Entry point
The server component uses a layered architecture:
server/
├── clients/ # External API clients
├── config/ # Environment configuration
├── coverage/ # Test coverage reports
├── middleware/ # Express middleware
│ ├── authMiddleware.js # Authentication middleware
│ └── rbacMiddleware.js # Role-based access control
├── models/ # Database models
├── public/ # Static server assets
├── routes/ # API route handlers
│ ├── auth.js # Authentication routes
│ ├── inviteCodes.js # Invite code management routes
│ └── email.js # Email notification routes
├── scripts/ # Server utility scripts
├── services/ # Server services
│ └── emailService.js # SendGrid email service
├── tests/ # Server-side tests
├── utils/ # Utility functions
└── vault/ # Secure configuration storage
Static and service worker files:
public/
├── service-worker.js # Service worker for caching and offline support
├── offline.html # Offline fallback page
├── manifest.json # PWA manifest
├── favicon.ico # Application icon
└── static/ # Static assets
Deployment and CI/CD configuration:
.github/
└── workflows/ # GitHub Actions workflows
├── ci-cd.yml # CI/CD pipeline configuration
└── security-scan.yml # Security scanning workflow
tests/
├── config/ # Test configuration files
├── cross-browser/ # Cross-browser compatibility tests
│ └── specs/ # Test specifications
├── integration/ # Integration tests
├── load/ # Load and performance tests
│ └── scenarios/ # Load testing scenarios
├── security/ # Security tests
├── smoke/ # Smoke tests for deployment verification
├── stability/ # Stability tests
└── user-journey/ # End-to-end user journey tests
The project is built on the following architectural principles:
- Feature-First Organization: Code is organized around business features rather than technical layers.
- Core Shared Services: Common functionality is extracted into core modules.
- Component Composition: Features are composed of smaller, reusable components.
- Separation of Concerns: UI components are separated from business logic.
- Clean API Boundaries: Features communicate through well-defined APIs.
- Progressive Enhancement: Application works without JavaScript, then enhances with JS capabilities.
- Offline-First: Application designed to work offline with service worker caching.
The application follows a unidirectional data flow pattern:
- User Interaction: User interacts with a component
- Service Layer: Component calls feature-specific or core services
- API/Storage: Services interact with APIs or storage mechanisms
- State Update: Updated data flows back to components via React state or context
- Rendering: Components re-render with updated data
The application implements the following performance optimizations:
- Code Splitting: Route-based code splitting with React.lazy and Suspense
- Critical CSS: Prioritized loading of critical CSS
- Service Worker Caching: Different caching strategies for different resource types
- Image Optimization: Lazy loading, responsive images, and WebP format support
- API Response Caching: TTL-based caching with compression
- Bundle Size Optimization: Tree shaking and dependency optimization
- Rendering Performance: Component memoization and virtualization for long lists
- Web Workers: Background processing for CPU-intensive tasks
The application implements the following stability measures to ensure consistent behavior across environments:
- Router Structure: Single Router instance with proper nesting of Routes components
- Theme Provider: Centralized Material UI ThemeProvider at the application root
- Error Boundaries: Strategic placement of React error boundaries to prevent cascading failures
- Namespaced API Exports: Preventing naming conflicts in API modules
- Global Variable Declarations: Proper ESLint global directives for external libraries
- Backend Resilience: Graceful degradation when backend services are unavailable
- Fallback UI: User-friendly messaging during service disruptions
- Automated Stability Tests: Comprehensive test suite verifying architectural stability
- CI Stability Checks: Automated checks for Router structure, Theme Provider, and API organization
The application employs a comprehensive testing approach:
- Unit Testing: Testing individual components and services
- Integration Testing: Testing interactions between components
- Cross-Browser Testing: Ensuring compatibility across browsers and devices via Playwright and BrowserStack
- Load Testing: Simulating various user loads with k6
- Security Testing: Static analysis and OWASP ZAP scanning
- Smoke Testing: Verification of critical paths post-deployment
The continuous integration and deployment pipeline consists of:
- Automated Testing: Running unit, integration, and cross-browser tests
- Security Scanning: Detecting vulnerabilities in code and dependencies
- Build Optimization: Production build with performance optimizations
- Multi-Environment Deployment: Development, staging, and production environments
- Post-Deployment Verification: Smoke tests ensuring application functionality
- Performance Monitoring: Real-time monitoring for performance regressions
Security is implemented through multiple layers:
- Environment Variables: All sensitive information is stored in environment variables
- Server-side API Proxying: API keys are never exposed to the client
- Rate Limiting: Prevents API abuse
- Key Rotation: Regular rotation of API keys
- Secure Storage: Encryption of sensitive user data
- Static Code Analysis: Security-focused ESLint rules
- Dependency Scanning: Regular auditing of dependencies for vulnerabilities
- OWASP Compliance: Following OWASP security best practices
- Authentication: JWT-based authentication system with token validation
- Role-Based Access Control: Granular permissions system for user roles
- Email Verification: Account verification through secure email tokens
The application implements a comprehensive security model:
- JWT Authentication: Stateless token-based authentication
- Role System: Tiered user roles (Guest, Beta Tester, Moderator, Admin)
- Permission Framework: Granular permissions for specific actions
- Middleware Protection: Route-level access control through middleware
- Frontend Permission Guards: Component-level rendering based on permissions
- Email Verification: Two-step verification process for new accounts
- Password Reset: Secure token-based password recovery
- Invite Code System: Controlled beta program access through unique codes