System Architecture

Overview

This documentation site is built using MkDocs with the Material theme, enhanced with custom plugins and JavaScript. The architecture follows a modern static site generation approach with dynamic client-side features for authentication and role-based access control.

Core Components

The documentation system consists of these key components:

1. MkDocs Core - Static site generator that converts Markdown to HTML
2. Material Theme - Enhanced UI with responsive design
3. Custom JavaScript - Client-side authentication and role management
4. Custom Theme Overrides - Templates for header, footer, and layout customization

graph TD
    A[Markdown Content] -->|MkDocs Build| B[Static HTML]
    B -->|Served to Browser| C[Client Browser]
    C -->|JavaScript| D{Authentication Check}
    D -->|Authenticated| E[Render Content]
    D -->|Not Authenticated| F[Redirect to SSO]
    G[Custom Plugins] -->|Enhance| B
    H[Material Theme] -->|Style| B
    I[Custom JS] -->|Dynamic Features| C

Authentication Flow

The documentation uses a client-side authentication flow that integrates with RFG Studio's SSO system:

sequenceDiagram
    participant User
    participant DocSite as Documentation Site
    participant SSO as SSO Service
    participant Permissions as Permissions Service

    User->>DocSite: Access page
    DocSite->>DocSite: Check local storage for token

    alt No valid token
        DocSite->>SSO: Redirect to login
        SSO->>User: Present login form
        User->>SSO: Enter credentials
        SSO->>DocSite: Redirect with token
        DocSite->>DocSite: Store token in localStorage
    end

    DocSite->>Permissions: Request user roles
    Permissions->>DocSite: Return roles array

    alt Has sufficient permissions
        DocSite->>User: Show content
    else Insufficient permissions
        DocSite->>User: Show access denied
    end

File Structure

The documentation site follows this organizational structure:

internal-documentation/
├── docs/                  # Content root
│   ├── js/                # Custom JavaScript
│   │   ├── sso-auth.js    # Authentication logic
│   │   ├── admin-nav.js   # Admin navigation
│   │   └── ...            # Other JS utilities
│   ├── css/               # Custom CSS
│   ├── theme/             # Theme customizations
│   │   └── main.html      # Header & layout overrides
│   ├── index.md           # Home page
│   ├── getting-started/   # Getting started guides
│   ├── guidelines/        # Style guidelines
│   ├── guides/            # Usage guides
│   ├── hidden/            # Admin-only content
│   └── ...                # Other content sections
├── mkdocs.yml             # Configuration
└── requirements.txt       # Python dependencies

Authentication & Authorization

SSO Integration

The site integrates with RFG Studio's Single Sign-On (SSO) system for authentication. The implementation is primarily client-side using JavaScript:

1. sso-auth.js - Handles authentication flow, token management, and role verification
2. admin-nav.js - Provides role-specific UI elements based on permissions

graph LR
    A[User Visit] --> B{Check Auth}
    B -->|No Token| C[Redirect to SSO]
    C --> D[SSO Login]
    D --> E[Return with Token]
    E --> F[Store Token]
    F --> G[Check Roles]
    B -->|Has Token| G
    G -->|Admin| H[Show Admin UI]
    G -->|Dev| I[Show Dev UI]
    G -->|Other| J[Limited Access]

Role-Based Access

Access control is implemented through these mechanisms:

1. Client-side permission checks - Restricts UI elements based on user role
2. Hidden URL paths - Admin-only content under /hidden/
3. Role simulation - Allows admins to test as different roles

Customization

Theme Customizations

The MkDocs Material theme has been extended with custom:

1. Header elements - Title, settings button, and print button
2. Footer content - Copyright and links
3. Color schemes - Light and dark modes
4. Navigation - Tab-based top-level sections

JavaScript Enhancements

Several custom scripts enhance the functionality:

1. fix-mobile-sidebar.js - Ensures proper mobile navigation
2. image-gallery.js - Provides image gallery support
3. site-cleaner.js - Removes unnecessary UI elements
4. nav-helper.js - Improves navigation experience

Deployment Architecture

The documentation site is deployed using this architecture:

graph TD
    A[Git Repository] -->|Commit| B[CI/CD Pipeline]
    B -->|Build| C[MkDocs Build]
    C -->|Static Files| D[Web Server]
    D -->|Serve| E[End User]
    F[CDN] -->|Cache Assets| E

Local Development

Local development environment uses:

1. mkdocs serve for local preview
2. Automatic local-mode detection for SSO bypass
3. Role simulation capabilities for testing different permission levels

Security Considerations

1. Authentication - Client-side token storage in localStorage
2. Role verification - Role checks performed on each page load
3. Admin content - Hidden paths for sensitive content
4. Token expiration - Automatic logout after token expires

Performance Optimizations

1. Static generation - Pre-built HTML for fast loading
2. CSS minification - Reduced stylesheet size
3. JavaScript optimization - On-demand loading when possible
4. Image optimization - Proper sizing and formats

Known Limitations

1. Client-side authentication means initial page load may show restricted content briefly
2. Role simulation only works for admins testing lower permission levels
3. Mobile responsiveness has some edge cases on very small screens