How autoguru-au/overdrive works
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).