# autoguru-au/overdrive architecture

> Architecture diagram of the GitHub repository autoguru-au/overdrive, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/autoguru-au/overdrive
- Repository: https://github.com/autoguru-au/overdrive

## Overview

##### Project Type and Purpose
- Overdrive is a product component library and design system built primarily as a reusable UI toolkit for AutoGuru.
- It uses React for rendering components, TypeScript for type safety, Vanilla Extract for CSS-in-JS styling, and Storybook for interactive component documentation and testing.
- The library is intended to be imported and used in other projects to have a consistent UI/UX, which means that its structure is focused around modular components, theming, and custom hooks.

##### Analyzing the File Structure
- The “lib” directory is the heart of the project, and it breaks down into several major submodules:
- Components: Located in “lib/components”, it contains all the individual reusable React components (e.g., Button, Modal, Tabs, etc.). Each component usually includes its main TSX file, supporting CSS styling files (often using Vanilla Extract), tests (using snapshot tests), and Storybook stories.
- Themes: Found under “lib/themes”, this part handles the theming system (base themes, neutral themes, flat_red theme, etc.) including token definitions and variables for building visual styles.
- Hooks: Included in “lib/hooks”, where custom hooks (e.g., useMedia, useResponsiveValue) add additional reusable logic.
- Styles & Utils: Under “lib/styles” and “lib/utils”, these are utility functions and CSS helpers that support the components.
- Reset: “lib/reset” sets baseline styles and fonts.
- In addition, there are directories for tests, stories, and templates which provide supplemental support for testing, development, and code generation.
- The “.storybook” folder shows Storybook’s configuration, emphasizing the interactive documentation side of the project.
- The project also includes various configuration files for GitHub workflows, linting (.editorconfig, .prettierignore), and build/testing, signifying a robust CI/CD integration.

##### Diagramming the Architecture
a. Main Components:
- Overdrive Provider: The entry point component (e.g., OverdriveProvider) that wraps any application to provide theming and context.
- Themes: A separate module representing the design system’s theming and tokens (from “lib/themes”). Show relationships between themes and components.
- Hooks & Utilities: Represent the custom hooks (in “lib/hooks”) and utilities (in “lib/utils” and “lib/styles”) that support component functionality and styling.
- Storybook: The interactive documentation portal that serves as both a showcase and testing ground for the components. Reference its configuration in “.storybook” and the live site.
- Testing & Snapshots: A module that groups in test files and snapshot directories (e.g., __snapshots__) that ensure component consistency.
- Build and CI/CD Pipeline: Include the configuration directories (.github/workflows, husky, linting configs) that manage code quality and deployment (e.g., Chromatic for visual regression testing).

b. Relationships and Interactions:
- That individual Components depend on both Themes (for styling) and Hooks/Utilities (for behavior and layout).
- That Storybook interacts with the Components module, pulling in individual component stories to render interactive docs.
- External dependencies (React, TypeScript, Vanilla Extract, Storybook) as external nodes that interact with the core modules.

c. Architectural Patterns:
- Separation of concerns: UI Components, styling/theming, and behavior (via hooks) are separated into distinct modules.
- Integration of snapshot testing for UI regression.
- Design system approach: theming tokens feed into styling which in turn drives the look and feel of every component.

d. Technologies and Frameworks:
- Vanilla Extract in the Themes/Styles sections.
- Storybook as the interactive documentation and UI playground.
- Optionally, note tools for CI/CD and testing (e.g., GitHub workflows, Chromatic, eslint, prettier).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Modules
    subgraph "Core Components"
        OP["OverdriveProvider"]:::component
        CL["Component Library"]:::component
    end

    %% Design System Layer
    subgraph "Design System"
        TH["Themes"]:::theme
        HK["Custom Hooks"]:::hook
        UT["Styles & Utilities"]:::utility
        RS["Reset Styles"]:::reset
    end

    %% Documentation & Testing Layer
    subgraph "Documentation & Testing"
        SB["Storybook"]:::storybook
        TS["Testing & Snapshots"]:::testing
    end

    %% Build and CI/CD Layer
    subgraph "Build & CI/CD"
        CD["Build/CI Pipeline"]:::cicd
    end

    %% External Dependencies
    subgraph "External Dependencies"
        EX1(("React")):::external
        EX2(("TypeScript")):::external
        EX3(("Vanilla Extract")):::external
        EX4(("Storybook Engine")):::external
    end

    %% Relationships and Data Flow
    OP -->|"wraps"| CL
    CL -->|"styled-by"| TH
    CL -->|"uses"| HK
    CL -->|"styled-by"| UT
    CL -->|"baseline-reset"| RS

    SB -->|"documents"| CL
    TS -->|"verifies"| CL

    CD -->|"builds & deploys"| SB
    CD -->|"integrates"| TS

    EX1 -->|"renders"| CL
    EX2 -->|"provides types"| CL
    EX3 -->|"styles"| TH
    EX4 -->|"powers"| SB

    %% Click Events
    click OP "https://github.com/autoguru-au/overdrive/blob/main/lib/components/OverdriveProvider/OverdriveProvider.tsx"
    click CL "https://github.com/autoguru-au/overdrive/tree/main/lib/components"
    click TH "https://github.com/autoguru-au/overdrive/tree/main/lib/themes"
    click HK "https://github.com/autoguru-au/overdrive/tree/main/lib/hooks"
    click UT "https://github.com/autoguru-au/overdrive/tree/main/lib/styles"
    click RS "https://github.com/autoguru-au/overdrive/tree/main/lib/reset"
    click SB "https://github.com/autoguru-au/overdrive/blob/main/.storybook"
    click TS "https://github.com/autoguru-au/overdrive/tree/main/lib/components/Button/__snapshots__"
    click CD "https://github.com/autoguru-au/overdrive/tree/main/.github/workflows"

    %% Style Definitions
    classDef component fill:#cce5ff,stroke:#007bff,stroke-width:2px;
    classDef theme fill:#d4edda,stroke:#28a745,stroke-width:2px;
    classDef hook fill:#fff3cd,stroke:#ffc107,stroke-width:2px;
    classDef utility fill:#f8d7da,stroke:#dc3545,stroke-width:2px;
    classDef reset fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
    classDef storybook fill:#d1ecf1,stroke:#17a2b8,stroke-width:2px;
    classDef testing fill:#f5c6cb,stroke:#dc3545,stroke-width:2px;
    classDef cicd fill:#ffeeba,stroke:#ffc107,stroke-width:2px;
    classDef external fill:#f0f0f0,stroke:#6f42c1,stroke-width:2px;
```
