AI Consultant Toolkit Pro ‐ Technical Architecture Report - magicplatforms/new-machine-workflows GitHub Wiki

AI Consultant Toolkit Pro - Technical Architecture Report

Executive Summary

The AI Consultant Toolkit Pro is a modern React-based Single Page Application (SPA) built with TypeScript and Vite. It features a sophisticated subdomain-based multi-tenancy system that allows different branded experiences while sharing a single codebase. The application is deployed on Azure Static Web Apps and uses GitHub Actions for CI/CD.

Table of Contents

  1. Technology Stack
  2. Application Architecture
  3. Subdomain & Templating System
  4. Deployment Architecture
  5. JavaScript Libraries
  6. Component Architecture
  7. Build & Development Workflow

Technology Stack

Core Technologies

  • Frontend Framework: React 18.3.1
  • Language: TypeScript 5.5.3
  • Build Tool: Vite 5.4.1
  • Styling: Tailwind CSS 3.4.11
  • Routing: React Router DOM 6.26.2
  • State Management: React Context API
  • Component Library: Shadcn/ui (Radix UI primitives)
  • Deployment: Azure Static Web Apps

Development Tools

  • Linting: ESLint 9.9.0
  • Package Manager: npm
  • Version Control: Git/GitHub
  • CI/CD: GitHub Actions

Application Architecture

graph TB
    subgraph "Client Browser"
        A[User Access] --> B{Subdomain Detection}
        B -->|URL Param| C[Query String Parser]
        B -->|Hostname| D[Domain Parser]
    end

subgraph "React Application"
    C --> E[useSubdomain Hook]
    D --> E
    E --> F[ContentProvider Context]
    F --> G[Content Configuration]
    G --> H[Dynamic Component Rendering]
    
    H --> I[Hero Component]
    H --> J[ProblemSection Component]
    H --> K[ToolkitOverview Component]
    H --> L[PricingTiers Component]
    H --> M[Footer Component]
end

subgraph "Content Management"
    G --> N[contentConfigs Object]
    N --> O[Default Config]
    N --> P[Healthcare Config]
    N --> Q[Developer Config]
    N --> R[Supply Chain Config]
    N --> S[Legal Config]
end

style A fill:#f9f,stroke:#333,stroke-width:2px
style F fill:#bbf,stroke:#333,stroke-width:2px
style N fill:#bfb,stroke:#333,stroke-width:2px

Subdomain & Templating System

How Subdomain Detection Works

sequenceDiagram
    participant User
    participant Browser
    participant useSubdomain Hook
    participant ContentProvider
    participant Components

User->>Browser: Access website
Browser->>useSubdomain Hook: Window.location

alt URL Parameter Present
    useSubdomain Hook->>useSubdomain Hook: Check ?subdomain=X
    useSubdomain Hook->>ContentProvider: Return subdomain from URL
else Azure Static App or Localhost
    useSubdomain Hook->>useSubdomain Hook: Check URL params first
    useSubdomain Hook->>ContentProvider: Return subdomain or 'default'
else Production Domain
    useSubdomain Hook->>useSubdomain Hook: Parse hostname
    useSubdomain Hook->>useSubdomain Hook: Extract first part
    useSubdomain Hook->>ContentProvider: Return subdomain
end

ContentProvider->>ContentProvider: Load content config
ContentProvider->>Components: Provide themed content
Components->>Browser: Render customized UI
Browser->>User: Display branded experience

Content Configuration Structure

The templating system uses a centralized configuration object that defines:

  1. Branding: Logo, company name, tagline
  2. Hero Section: Headlines, CTAs, value propositions
  3. Problem Section: Statistics, benefits, pain points
  4. Toolkit Overview: Features, tools, additional offerings
  5. Pricing: Tiers, features, special offers
  6. Theme: Primary colors, accent colors, backgrounds

Subdomain Configurations

  • default: General AI consulting toolkit
  • healthcare: Healthcare-specific AI solutions
  • developer: Developer-focused AI tools
  • supply: Supply chain AI optimization
  • legal: Legal practice AI solutions

Deployment Architecture

graph LR
    subgraph "Development"
        A[Local Development] --> B[Git Push]
    end

subgraph "GitHub"
    B --> C[GitHub Repository]
    C --> D[GitHub Actions]
    D --> E[Build Process]
    E --> F[Vite Build]
end

subgraph "Azure"
    F --> G[Azure Static Web Apps]
    G --> H[CDN Distribution]
    H --> I[Global Edge Nodes]
end

subgraph "Users"
    I --> J[End Users]
end

style C fill:#f96,stroke:#333,stroke-width:2px
style G fill:#69f,stroke:#333,stroke-width:2px

Deployment Configuration

  • Build Output: dist directory
  • API Location: None (frontend only)
  • Routing: Client-side with fallback to index.html
  • GitHub Secret: AZURE_STATIC_WEB_APPS_API_TOKEN

JavaScript Libraries

Core Dependencies

Library Version Purpose
react 18.3.1 UI framework
react-dom 18.3.1 React DOM rendering
react-router-dom 6.26.2 Client-side routing
@tanstack/react-query 5.56.2 Server state management
react-hook-form 7.53.0 Form handling
zod 3.23.8 Schema validation

Component Architecture

graph TD
    subgraph "Entry Points"
        A[main.tsx] --> B[App.tsx]
    end

subgraph "Context Layer"
    B --> C[QueryClientProvider]
    C --> D[ContentProvider]
    D --> E[TooltipProvider]
end

subgraph "Routing"
    E --> F[BrowserRouter]
    F --> G[Routes]
    G --> H[Index Page]
    G --> I[NotFound Page]
end

subgraph "Page Components"
    H --> J[Hero]
    H --> K[ProblemSection]
    H --> L[ToolkitOverview]
    H --> M[PricingTiers]
    H --> N[Footer]
    H --> O[SubdomainDemo]
end

subgraph "Shared Systems"
    J --> P[useContentConfig]
    K --> P
    L --> P
    M --> P
    
    P --> Q[ContentContext]
    Q --> R[useSubdomain Hook]
end

style A fill:#f9f,stroke:#333,stroke-width:2px
style D fill:#bbf,stroke:#333,stroke-width:2px
style R fill:#bfb,stroke:#333,stroke-width:2px

Component Structure

  1. Layout Components

    • Hero.tsx: Landing page hero section
    • ProblemSection.tsx: Problem/opportunity presentation
    • ToolkitOverview.tsx: Feature showcase
    • PricingTiers.tsx: Pricing and tier display
    • Footer.tsx: Site footer

  2. UI Components (Shadcn/ui)

    • 50+ pre-built components
    • Based on Radix UI primitives
    • Styled with Tailwind CSS
    • Type-safe with TypeScript

  3. Demo Components

    • SubdomainDemo.tsx: Development subdomain switcher

Build & Development Workflow

graph LR
    subgraph "Development"
        A[npm run dev] --> B[Vite Dev Server]
        B --> C[Hot Module Replacement]
        C --> D[localhost:8080]
    end

subgraph "Build Process"
    E[npm run build] --> F[TypeScript Compilation]
    F --> G[Vite Build]
    G --> H[Minification]
    H --> I[dist/]
end

subgraph "Deployment"
    I --> J[GitHub Push]
    J --> K[GitHub Actions]
    K --> L[Azure Deploy]
end

style A fill:#9f9,stroke:#333,stroke-width:2px
style E fill:#f99,stroke:#333,stroke-width:2px
style L fill:#99f,stroke:#333,stroke-width:2px

Development Features

  1. Hot Module Replacement: Instant updates without page reload
  2. TypeScript Support: Full type safety and IntelliSense
  3. Path Aliases: @/ maps to src/ directory
  4. Component Tagging: Development-only component inspection
  5. CSS Processing: PostCSS with Tailwind CSS

Build Optimization

  1. Code Splitting: Automatic route-based splitting
  2. Tree Shaking: Removes unused code
  3. Minification: JavaScript and CSS optimization
  4. Asset Optimization: Image and font optimization
  5. Source Maps: Debug support in production

Security & Best Practices

Security Measures

  1. Content Security Policy: Configured in Azure Static Web Apps
  2. HTTPS Only: Enforced by Azure
  3. No Server-Side Code: Static site reduces attack surface
  4. Environment Variables: Managed through Azure configuration

Performance Optimizations

  1. Lazy Loading: Routes loaded on demand
  2. CDN Distribution: Global edge caching
  3. Optimized Bundle Size: ~250KB gzipped
  4. Efficient Re-renders: React Context optimization
  5. Tailwind Purge: Removes unused CSS classes

Scalability Features

  1. Subdomain Multi-tenancy: Infinite branded experiences
  2. Static Hosting: No server scaling required
  3. Edge Caching: Global performance
  4. Configuration-driven: Easy to add new subdomains
  5. Component Reusability: Shared UI components

Monitoring & Analytics

Available Monitoring

  1. GitHub Actions: Build and deployment status
  2. Azure Portal: Traffic and performance metrics
  3. Application Insights: Optional detailed monitoring
  4. Browser DevTools: Client-side performance

Key Metrics to Track

  1. Page Load Time: Target < 2 seconds
  2. Time to Interactive: Target < 3 seconds
  3. Bundle Size: Monitor growth
  4. Error Rate: Track client-side errors
  5. Conversion Rate: Per subdomain tracking

Future Enhancements

Recommended Improvements

  1. Progressive Web App: Add offline support
  2. Internationalization: Multi-language support
  3. A/B Testing: Built-in experimentation
  4. Analytics Integration: Google Analytics or similar
  5. API Integration: Backend services for dynamic content
  6. CMS Integration: Content management system
  7. Authentication: User accounts and personalization
  8. SEO Optimization: Server-side rendering consideration

Conclusion

The AI Consultant Toolkit Pro demonstrates a modern approach to building multi-tenant SaaS applications using React and TypeScript. The subdomain-based templating system provides flexibility while maintaining a single codebase, and the Azure Static Web Apps deployment ensures global performance and reliability. The architecture is well-suited for scaling to support additional verticals and use cases with minimal development effort.

# AI Consultant Toolkit Pro - Technical Architecture Report

Executive Summary

The AI Consultant Toolkit Pro is a modern React-based Single Page Application (SPA) built with TypeScript and Vite. It features a sophisticated subdomain-based multi-tenancy system that allows different branded experiences while sharing a single codebase. The application is deployed on Azure Static Web Apps and uses GitHub Actions for CI/CD.

Table of Contents

  1. [Technology Stack](#technology-stack)
  2. [Application Architecture](#application-architecture)
  3. [Subdomain & Templating System](#subdomain--templating-system)
  4. [Deployment Architecture](#deployment-architecture)
  5. [JavaScript Libraries](#javascript-libraries)
  6. [Component Architecture](#component-architecture)
  7. [Build & Development Workflow](#build--development-workflow)

Technology Stack

Core Technologies

  • Frontend Framework: React 18.3.1
  • Language: TypeScript 5.5.3
  • Build Tool: Vite 5.4.1
  • Styling: Tailwind CSS 3.4.11
  • Routing: React Router DOM 6.26.2
  • State Management: React Context API
  • Component Library: Shadcn/ui (Radix UI primitives)
  • Deployment: Azure Static Web Apps

Development Tools

  • Linting: ESLint 9.9.0
  • Package Manager: npm
  • Version Control: Git/GitHub
  • CI/CD: GitHub Actions

Application Architecture

graph TB
    subgraph "Client Browser"
        A[User Access] --> B{Subdomain Detection}
        B -->|URL Param| C[Query String Parser]
        B -->|Hostname| D[Domain Parser]
    end
    
    subgraph "React Application"
        C --> E[useSubdomain Hook]
        D --> E
        E --> F[ContentProvider Context]
        F --> G[Content Configuration]
        G --> H[Dynamic Component Rendering]
        
        H --> I[Hero Component]
        H --> J[ProblemSection Component]
        H --> K[ToolkitOverview Component]
        H --> L[PricingTiers Component]
        H --> M[Footer Component]
    end
    
    subgraph "Content Management"
        G --> N[contentConfigs Object]
        N --> O[Default Config]
        N --> P[Healthcare Config]
        N --> Q[Developer Config]
        N --> R[Supply Chain Config]
        N --> S[Legal Config]
    end
    
    style A fill:#f9f,stroke:#333,stroke-width:2px
    style F fill:#bbf,stroke:#333,stroke-width:2px
    style N fill:#bfb,stroke:#333,stroke-width:2px
Loading

Subdomain & Templating System

How Subdomain Detection Works

sequenceDiagram
    participant User
    participant Browser
    participant useSubdomain Hook
    participant ContentProvider
    participant Components
    
    User->>Browser: Access website
    Browser->>useSubdomain Hook: Window.location
    
    alt URL Parameter Present
        useSubdomain Hook->>useSubdomain Hook: Check ?subdomain=X
        useSubdomain Hook->>ContentProvider: Return subdomain from URL
    else Azure Static App or Localhost
        useSubdomain Hook->>useSubdomain Hook: Check URL params first
        useSubdomain Hook->>ContentProvider: Return subdomain or 'default'
    else Production Domain
        useSubdomain Hook->>useSubdomain Hook: Parse hostname
        useSubdomain Hook->>useSubdomain Hook: Extract first part
        useSubdomain Hook->>ContentProvider: Return subdomain
    end
    
    ContentProvider->>ContentProvider: Load content config
    ContentProvider->>Components: Provide themed content
    Components->>Browser: Render customized UI
    Browser->>User: Display branded experience
Loading

Content Configuration Structure

The templating system uses a centralized configuration object that defines:

  1. Branding: Logo, company name, tagline
  2. Hero Section: Headlines, CTAs, value propositions
  3. Problem Section: Statistics, benefits, pain points
  4. Toolkit Overview: Features, tools, additional offerings
  5. Pricing: Tiers, features, special offers
  6. Theme: Primary colors, accent colors, backgrounds

Subdomain Configurations

  • default: General AI consulting toolkit
  • healthcare: Healthcare-specific AI solutions
  • developer: Developer-focused AI tools
  • supply: Supply chain AI optimization
  • legal: Legal practice AI solutions

Deployment Architecture

graph LR
    subgraph "Development"
        A[Local Development] --> B[Git Push]
    end
    
    subgraph "GitHub"
        B --> C[GitHub Repository]
        C --> D[GitHub Actions]
        D --> E[Build Process]
        E --> F[Vite Build]
    end
    
    subgraph "Azure"
        F --> G[Azure Static Web Apps]
        G --> H[CDN Distribution]
        H --> I[Global Edge Nodes]
    end
    
    subgraph "Users"
        I --> J[End Users]
    end
    
    style C fill:#f96,stroke:#333,stroke-width:2px
    style G fill:#69f,stroke:#333,stroke-width:2px
Loading

Deployment Configuration

  • Build Output: dist directory
  • API Location: None (frontend only)
  • Routing: Client-side with fallback to index.html
  • GitHub Secret: AZURE_STATIC_WEB_APPS_API_TOKEN

JavaScript Libraries

Core Dependencies

Library Version Purpose
react 18.3.1 UI framework
react-dom 18.3.1 React DOM rendering
react-router-dom 6.26.2 Client-side routing
@tanstack/react-query 5.56.2 Server state management
react-hook-form 7.53.0 Form handling
zod 3.23.8 Schema validation

UI Libraries

Library Version Purpose
@radix-ui/* Various Headless UI components
lucide-react 0.462.0 Icon library
tailwindcss 3.4.11 Utility-first CSS
clsx 2.1.1 Conditional classes
tailwind-merge 2.5.2 Merge Tailwind classes
class-variance-authority 0.7.1 Component variants

Additional Libraries

Library Version Purpose
date-fns 3.6.0 Date manipulation
recharts 2.12.7 Data visualization
sonner 1.5.0 Toast notifications
cmdk 1.0.0 Command menu
vaul 0.9.3 Drawer component

Component Architecture

graph TD
    subgraph "Entry Points"
        A[main.tsx] --> B[App.tsx]
    end
    
    subgraph "Context Layer"
        B --> C[QueryClientProvider]
        C --> D[ContentProvider]
        D --> E[TooltipProvider]
    end
    
    subgraph "Routing"
        E --> F[BrowserRouter]
        F --> G[Routes]
        G --> H[Index Page]
        G --> I[NotFound Page]
    end
    
    subgraph "Page Components"
        H --> J[Hero]
        H --> K[ProblemSection]
        H --> L[ToolkitOverview]
        H --> M[PricingTiers]
        H --> N[Footer]
        H --> O[SubdomainDemo]
    end
    
    subgraph "Shared Systems"
        J --> P[useContentConfig]
        K --> P
        L --> P
        M --> P
        
        P --> Q[ContentContext]
        Q --> R[useSubdomain Hook]
    end
    
    style A fill:#f9f,stroke:#333,stroke-width:2px
    style D fill:#bbf,stroke:#333,stroke-width:2px
    style R fill:#bfb,stroke:#333,stroke-width:2px
Loading

Component Structure

  1. Layout Components

    • Hero.tsx: Landing page hero section
    • ProblemSection.tsx: Problem/opportunity presentation
    • ToolkitOverview.tsx: Feature showcase
    • PricingTiers.tsx: Pricing and tier display
    • Footer.tsx: Site footer

  2. UI Components (Shadcn/ui)

    • 50+ pre-built components
    • Based on Radix UI primitives
    • Styled with Tailwind CSS
    • Type-safe with TypeScript

  3. Demo Components

    • SubdomainDemo.tsx: Development subdomain switcher

Build & Development Workflow

graph LR
    subgraph "Development"
        A[npm run dev] --> B[Vite Dev Server]
        B --> C[Hot Module Replacement]
        C --> D[localhost:8080]
    end
    
    subgraph "Build Process"
        E[npm run build] --> F[TypeScript Compilation]
        F --> G[Vite Build]
        G --> H[Minification]
        H --> I[dist/]
    end
    
    subgraph "Deployment"
        I --> J[GitHub Push]
        J --> K[GitHub Actions]
        K --> L[Azure Deploy]
    end
    
    style A fill:#9f9,stroke:#333,stroke-width:2px
    style E fill:#f99,stroke:#333,stroke-width:2px
    style L fill:#99f,stroke:#333,stroke-width:2px
Loading

Development Features

  1. Hot Module Replacement: Instant updates without page reload
  2. TypeScript Support: Full type safety and IntelliSense
  3. Path Aliases: @/ maps to src/ directory
  4. Component Tagging: Development-only component inspection
  5. CSS Processing: PostCSS with Tailwind CSS

Build Optimization

  1. Code Splitting: Automatic route-based splitting
  2. Tree Shaking: Removes unused code
  3. Minification: JavaScript and CSS optimization
  4. Asset Optimization: Image and font optimization
  5. Source Maps: Debug support in production

Security & Best Practices

Security Measures

  1. Content Security Policy: Configured in Azure Static Web Apps
  2. HTTPS Only: Enforced by Azure
  3. No Server-Side Code: Static site reduces attack surface
  4. Environment Variables: Managed through Azure configuration

Performance Optimizations

  1. Lazy Loading: Routes loaded on demand
  2. CDN Distribution: Global edge caching
  3. Optimized Bundle Size: ~250KB gzipped
  4. Efficient Re-renders: React Context optimization
  5. Tailwind Purge: Removes unused CSS classes

Scalability Features

  1. Subdomain Multi-tenancy: Infinite branded experiences
  2. Static Hosting: No server scaling required
  3. Edge Caching: Global performance
  4. Configuration-driven: Easy to add new subdomains
  5. Component Reusability: Shared UI components

Monitoring & Analytics

Available Monitoring

  1. GitHub Actions: Build and deployment status
  2. Azure Portal: Traffic and performance metrics
  3. Application Insights: Optional detailed monitoring
  4. Browser DevTools: Client-side performance

Key Metrics to Track

  1. Page Load Time: Target < 2 seconds
  2. Time to Interactive: Target < 3 seconds
  3. Bundle Size: Monitor growth
  4. Error Rate: Track client-side errors
  5. Conversion Rate: Per subdomain tracking

Future Enhancements

Recommended Improvements

  1. Progressive Web App: Add offline support
  2. Internationalization: Multi-language support
  3. A/B Testing: Built-in experimentation
  4. Analytics Integration: Google Analytics or similar
  5. API Integration: Backend services for dynamic content
  6. CMS Integration: Content management system
  7. Authentication: User accounts and personalization
  8. SEO Optimization: Server-side rendering consideration

Conclusion

The AI Consultant Toolkit Pro demonstrates a modern approach to building multi-tenant SaaS applications using React and TypeScript. The subdomain-based templating system provides flexibility while maintaining a single codebase, and the Azure Static Web Apps deployment ensures global performance and reliability. The architecture is well-suited for scaling to support additional verticals and use cases with minimal development effort.

⚠️ **GitHub.com Fallback** ⚠️