Technical Architecture & Implementation Guide

System Overview

This document provides a comprehensive technical overview of the RFG Studio's Internal Documentation platform. It covers the system architecture, implementation details, data flows, and technical decisions that form the foundation of our documentation system.

Core Architecture

The documentation system employs a static site generation approach with dynamic client-side features. This architecture provides optimal performance, security, and flexibility.

flowchart TD
    subgraph "Build Process"
        A[Markdown Files] --> B[MkDocs Engine]
        B --> C[Static HTML/CSS/JS]
        D[Theme Templates] --> B
        E[Configuration] --> B
        F[Plugins] --> B
    end

    subgraph "Client-Side Features"
        G[Authentication JS] --> H{Auth Check}
        H -->|Authenticated| I[Render Content]
        H -->|Unauthorized| J[Access Denied]
        K[Role-Based Permissions] --> L[UI Customization]
        M[Theme Toggle] --> N[UI Theme State]
    end

    subgraph "Deployment"
        C --> O[Web Server]
        O --> P[End User Browser]
    end

    P --> G

Technical Stack

Core Components

Technology Selection Rationale

The architecture was designed with these principles:

1. Performance First - Static site generation for fast page loads
2. Security Focused - Minimal attack surface with no server-side database
3. Developer Experience - Markdown-based authoring with Git integration
4. Extensibility - Plugin system for custom functionality

Authentication Architecture

The authentication system implements a client-side token-based approach that integrates with RFG Studio's SSO.

sequenceDiagram
    participant User
    participant Browser
    participant DocSite as Documentation Site
    participant SSO as RFG SSO Service
    participant PermService as Permission Service

    User->>Browser: Access documentation
    Browser->>DocSite: Request page
    DocSite->>DocSite: Check localStorage for token

    alt No token or expired
        DocSite->>SSO: Redirect for authentication
        SSO->>User: Display login form
        User->>SSO: Submit credentials
        SSO->>Browser: Set authentication token
        Browser->>DocSite: Return to documentation
    end

    DocSite->>PermService: Request user permissions
    PermService->>DocSite: Return role information

    alt Has sufficient permissions
        DocSite->>Browser: Render content
        Browser->>User: Display documentation
    else Insufficient permissions
        DocSite->>Browser: Show access denied
        Browser->>User: Display error message
    end

Authentication Flow Details

1. Token Acquisition
2. JWT tokens acquired via RFG Studio's SSO
3. Tokens stored in browser localStorage

4. Default expiration of 24 hours

5. Permission Verification

6. Roles retrieved from permission service
7. Client-side verification on each page load

8. Role-based content filtering

9. Role Hierarchy

graph TD
    A[System Tester] -->|Inherits| B[Admin]
    B -->|Inherits| C[Dev Manager]
    C -->|Inherits| D[Dev]
    D -->|Inherits| E[Staff]

    style A fill:#e91e63,color:white
    style B fill:#9c27b0,color:white
    style C fill:#3f51b5,color:white
    style D fill:#2196f3,color:white
    style E fill:#03a9f4,color:white

Data Architecture

Content Structure

The documentation content follows a hierarchical structure:

graph TD
    A[Root] --> B[Getting Started]
    A --> C[Guidelines]
    A --> D[Letter]
    A --> E[Extreme Obby Load]
    A --> F[Guides]
    A --> G[API]
    A --> H[Admin]

    B --> B1[Introduction]
    B --> B2[Main Rules]
    B --> B3[Editing & Task Assignment]
    B --> B4[Tools Installation]

    C --> C1[General Style]
    C --> C2[UI Style]
    C --> C3[File Organization]

    F --> F1[Editing Docs]
    F --> F2[Basic]
    F --> F3[Diagrams]
    F --> F4[Authentication]

    H --> H1[Overview]
    H --> H2[System Architecture]
    H --> H3[Security Protocols]
    H --> H4[Admin Guide]
    H --> H5[Technical Architecture]

    style H fill:#f44336,color:white
    style H1 fill:#f44336,color:white
    style H2 fill:#f44336,color:white
    style H3 fill:#f44336,color:white
    style H4 fill:#f44336,color:white
    style H5 fill:#f44336,color:white

File Storage

Content is stored as Markdown files with a consistent organization pattern:

internal-documentation/
├── docs/                  # Content root
│   ├── js/                # Client-side scripts
│   │   ├── sso-auth.js    # Authentication
│   │   ├── admin-nav.js   # Admin navigation
│   │   ├── theme-toggle.js # Theme switcher
│   │   └── ...            # Other utilities
│   ├── css/               # Custom styles
│   ├── theme/             # Theme customizations
│   │   └── main.html      # Custom template
│   ├── index.md           # Home page
│   ├── getting-started/   # Section files
│   ├── guidelines/        # Section files
│   ├── guides/            # Section files
│   ├── api/               # API documentation
│   └── hidden/            # Admin content
│       ├── index.md             # Admin home
│       ├── system-architecture.md # System docs
│       ├── security-protocols.md  # Security docs
│       ├── admin-guide.md         # Admin guide
│       └── technical-architecture.md # Technical docs
├── mkdocs.yml             # Configuration
└── requirements.txt       # Python dependencies

Frontend Implementation

Theme Customization

The Material for MkDocs theme has been extended with custom JavaScript and CSS to provide:

1. Role-based UI elements - Different UI components based on user role
2. Custom navigation - Enhanced navigation with role-specific visibility
3. Single theme toggle - Unified light/dark mode switching

classDiagram
    class BaseTheme {
        +header
        +footer
        +navigation
        +search
        +render()
    }

    class CustomTheme {
        +roleBasedUI
        +enhancedNavigation
        +themeToggle
        +adminFeatures
        +customStyles()
        +injectCustomJS()
    }

    BaseTheme <|-- CustomTheme

Theme Toggle Implementation

The theme toggle uses a custom implementation to replace the default theme switcher:

sequenceDiagram
    participant User
    participant ThemeToggle
    participant LocalStorage
    participant DOM

    User->>ThemeToggle: Click toggle button
    ThemeToggle->>DOM: Get current theme
    DOM->>ThemeToggle: Return theme state
    ThemeToggle->>ThemeToggle: Toggle theme state
    ThemeToggle->>DOM: Update data-md-color-scheme
    ThemeToggle->>LocalStorage: Store preference
    ThemeToggle->>ThemeToggle: Animate icon transition
    ThemeToggle->>User: Visual feedback

Custom JavaScript Architecture

The client-side JavaScript follows a modular pattern:

graph TD
    A[sso-auth.js] --> B[Authentication]
    C[admin-nav.js] --> D[Navigation Control]
    E[theme-toggle.js] --> F[Theme Switching]
    G[fix-mobile-sidebar.js] --> H[Mobile UI Fixes]
    I[site-cleaner.js] --> J[UI Cleanup]

    B --> K[User Session]
    K --> D
    K --> L[Role Permissions]
    L --> D
    F --> M[User Preferences]

Performance Optimization

Rendering Pipeline

The documentation uses an optimized rendering pipeline:

flowchart LR
    A[Markdown Source] --> B[MkDocs Parser]
    B --> C[HTML Generation]
    C --> D[Asset Optimization]
    D --> E[Minification]
    E --> F[Bundling]
    F --> G[Static Output]

    H[CSS] --> D
    I[JavaScript] --> D
    J[Images] --> D

Performance Metrics

Security Implementation

Client-Side Security Model

flowchart TD
    A[User Request] --> B{Has Token?}
    B -->|No| C[Redirect to SSO]
    B -->|Yes| D{Token Valid?}
    D -->|No| C
    D -->|Yes| E{Has Required Role?}
    E -->|No| F[Access Denied]
    E -->|Yes| G[Serve Content]

    H[URL Protection] --> I{Is Restricted Path?}
    I -->|Yes| J{Has Admin Role?}
    J -->|No| K[Redirect Home]
    J -->|Yes| L[Allow Access]
    I -->|No| M[Standard Access Check]

Role Simulation

The system includes a role simulation feature for testing:

stateDiagram-v2
    [*] --> NormalMode
    NormalMode --> SimulationMode: Admin activates simulation
    SimulationMode --> SimulatingDev: Select Dev role
    SimulationMode --> SimulatingStaff: Select Staff role
    SimulatingDev --> SimulationMode: Change role
    SimulatingStaff --> SimulationMode: Change role
    SimulationMode --> NormalMode: Reset simulation
    SimulationMode --> [*]
    NormalMode --> [*]

Deployment Pipeline

The documentation uses a CI/CD pipeline for deployment:

flowchart LR
    A[Git Repository] -->|Commit| B[CI/CD Trigger]
    B --> C{Tests Pass?}
    C -->|No| D[Notification]
    C -->|Yes| E[Build Process]
    E --> F[Test Build]
    F --> G{Build Successful?}
    G -->|No| D
    G -->|Yes| H[Deploy to Staging]
    H --> I[QA Verification]
    I --> J{Approved?}
    J -->|No| K[Fix Issues]
    K --> A
    J -->|Yes| L[Deploy to Production]
    L --> M[Post-Deploy Verification]

Local Development Environment

Development Workflow

graph TD
    A[Clone Repository] --> B[Install Dependencies]
    B --> C[Run Local Server]
    C --> D[Make Changes]
    D --> E[Preview Changes]
    E --> F{Satisfied?}
    F -->|No| D
    F -->|Yes| G[Commit Changes]
    G --> H[Push to Repository]
    H --> I[CI/CD Pipeline]

Environment Setup

1. Dependencies
2. Python 3.9+
3. MkDocs and plugins (pip install -r requirements.txt)

4. Node.js 16+ (for advanced customization)

5. Local Server

6. python -m mkdocs serve - Basic server

7. python -m mkdocs serve --dirtyreload - Fast reload for large sites

8. Authentication Bypass

9. Local development automatically bypasses SSO
10. Default admin permissions on localhost
11. Role simulation available for testing

Future Technical Roadmap

gantt
    title Technical Roadmap
    dateFormat  YYYY-MM-DD
    section Authentication
    Enhanced SSO Integration    :2025-07-01, 2025-09-30
    2FA for Admin Access        :2025-08-15, 2025-10-15
    section Performance
    Asset Optimization          :2025-07-01, 2025-08-15
    Search Improvements         :2025-08-01, 2025-09-30
    section Features
    Expanded API Documentation  :2025-07-15, 2025-10-30
    Interactive Tutorials       :2025-09-01, 2025-12-31
    section Infrastructure
    CDN Integration             :2025-07-01, 2025-08-31
    Containerized Deployment    :2025-09-01, 2025-11-30

Technical Debt & Known Issues

Performance Monitoring

The system includes performance monitoring via the following metrics:

graph LR
    A[User Session] --> B[Performance Data Collection]
    B --> C[Analytics Processing]
    C --> D[Performance Dashboard]

    E[Page Load Time] --> B
    F[Navigation Timing] --> B
    G[Resource Timing] --> B
    H[User Interactions] --> B

    D --> I[Optimization Decisions]
    I --> J[Implementation]
    J --> A

Key Performance Indicators

xychart-beta
    title "Documentation Performance Metrics"
    x-axis [Jan, Feb, Mar, Apr, May, Jun]
    y-axis "Time (ms)" 0 --> 2500
    bar [1800, 1650, 1500, 1350, 1200, 950]
    line [2200, 2000, 1800, 1600, 1400, 1100]

Legend: Blue = Initial Load Time, Red = Time to Interactive

API Integration

The documentation includes API reference documentation generated from OpenAPI specifications.

graph TD
    A[OpenAPI Spec] --> B[Swagger UI Tag]
    B --> C[Interactive API Docs]
    D[API Updates] --> E[CI/CD Pipeline]
    E --> F[Auto-Generated Docs]
    F --> G[Published Documentation]

Implementation Best Practices

Code Organization Standards

1. JavaScript Modularization
2. One responsibility per file
3. Clear module interfaces

4. Minimal dependencies between modules

5. CSS Structure

6. Component-based styling
7. CSS variables for theming

8. Mobile-first responsive design

9. Content Organization

10. Logical nesting of topics
11. Consistent file naming
12. Clear separation of admin content

Technical Support & Troubleshooting

Common Issues & Resolutions

Technical Support Process

flowchart TD
    A[Issue Reported] --> B{Is Authentication Issue?}
    B -->|Yes| C[Check SSO Status]
    B -->|No| D{Is UI Issue?}
    D -->|Yes| E[Check Browser Console]
    D -->|No| F{Is Content Issue?}
    F -->|Yes| G[Verify Content in Repository]
    F -->|No| H[General Troubleshooting]

    C --> I{SSO Working?}
    I -->|Yes| J[Check Token Validity]
    I -->|No| K[Contact SSO Team]

    E --> L{JS Errors?}
    L -->|Yes| M[Debug JavaScript]
    L -->|No| N[Check CSS Issues]

    G --> O{Content Correct?}
    O -->|Yes| P[Check Build Process]
    O -->|No| Q[Update Content]

    H --> R[Gather Diagnostic Info]
    R --> S[Escalate to Dev Team]