# ocean-h1/pixie-ui architecture

> Architecture diagram of the GitHub repository ocean-h1/pixie-ui, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ocean-h1/pixie-ui
- Repository: https://github.com/ocean-h1/pixie-ui

## Overview

##### Overview and Main Components
- Monorepo Structure: Start with a high-level view that shows the monorepo managed by PNPM and Turborepo. Identify the three main sections:
- Packages: Contains the reusable code crafted into packages.
▸ Core: This folder (packages/core) includes all the UI components (Button, Card, Carousel, etc.) with demos, documentation, and source files.
▸ Hooks: Custom React hooks that supply additional functionality.
▸ Theme: Provides the theme provider and support for custom theming (ThemeProvider and related hooks).
▸ Utils: A set of utility functions (for object, string, dom handling, and more).
- Apps: Includes “apps/site,” which is the documentation/demos site generated with Dumi to showcase the components.
- Examples: Contains sample applications (for instance, a basic example) that demonstrate practical usage of the UI library.

##### Identifying Relationships and Component Interactions
- That the theme package (packages/theme) is used as a context provider for theming and is imported within sample applications and documentation.
- Demonstrate the support libraries (hooks and utils) as lateral support systems that can be used by the core components and possibly the theme module.
- External dependencies (React, TypeScript, Emotion, etc.) alongside these components to give context to the technology stack.

##### Architectural Patterns or Design Principles
- Modularization: Highlight that the system is designed with modularity in mind—each UI component is isolated in its own folder with clear demos and documentation.
- Monorepo & Package-based Development: Emphasize that the use of PNPM Workspaces and Turborepo allows inter-package dependencies and efficient development practices.
- Separation of Concerns: Distinguish between the UI component implementation (packages/core), custom hooks (packages/hooks), and theming (packages/theme), each handling specific responsibilities.
- Documentation Driven: Note the importance of the apps/site (using Dumi) for interactive component documentation and demos.

##### Relevant Technologies and Their Roles
- React and TypeScript: Core technologies used in building the components and hooks.
- Emotion (CSS-in-JS): For styling the components.
- Dumi: Used in the documentation website (in apps/site) to generate component docs.
- PNPM, Turborepo: For monorepo management, dependency management, and orchestrating builds.
- Jest: For unit testing.
- ESLint, Prettier, Stylelint: For maintaining code quality and consistency (configuration files present at the root).

## Diagram (Mermaid)

```mermaid
graph TD
    MONO["pixie-ui Monorepo"]:::packages

    subgraph "Packages"
        UIC["UI Core Components"]:::packages
        HOOK["Hooks"]:::packages
        THEME["Theme"]:::packages
        UTILS["Utils"]:::packages
    end

    subgraph "Apps & Examples"
        DOCS["Documentation Site"]:::apps
        EXAPP["Example Application"]:::apps
    end

    %% Internal Dependencies
    MONO -->|"contains"| UIC
    MONO -->|"contains"| HOOK
    MONO -->|"contains"| THEME
    MONO -->|"contains"| UTILS
    MONO -->|"contains"| DOCS
    MONO -->|"contains"| EXAPP

    UIC -->|"consumed_by"| DOCS
    UIC -->|"consumed_by"| EXAPP

    THEME -->|"provides"| DOCS
    THEME -->|"provides"| EXAPP

    HOOK -->|"supports"| UIC
    UTILS -->|"supports"| UIC

    %% External Dependencies
    REACT["React"]:::external
    TS["TypeScript"]:::external
    EMOTION["Emotion"]:::external
    DUMI["Dumi"]:::external

    REACT -->|"built_with"| UIC
    TS -->|"built_with"| UIC
    EMOTION -->|"styled_by"| UIC
    DUMI -->|"powers"| DOCS

    %% Infrastructure & Tooling
    PNPM["PNPM"]:::infra
    TUB["Turborepo"]:::infra
    JEST["Jest"]:::infra
    ESLINT["ESLint"]:::infra
    PRETTIER["Prettier"]:::infra
    STYLELINT["Stylelint"]:::infra

    PNPM -->|"manages"| MONO
    TUB -->|"orchestrates"| MONO
    JEST -->|"tests"| MONO
    ESLINT -->|"linters"| MONO
    PRETTIER -->|"formats"| MONO
    STYLELINT -->|"styles"| MONO

    %% Click Events
    click UIC "https://github.com/ocean-h1/pixie-ui/tree/master/packages/core"
    click HOOK "https://github.com/ocean-h1/pixie-ui/tree/master/packages/hooks"
    click THEME "https://github.com/ocean-h1/pixie-ui/tree/master/packages/theme"
    click UTILS "https://github.com/ocean-h1/pixie-ui/tree/master/packages/utils"
    click DOCS "https://github.com/ocean-h1/pixie-ui/tree/master/apps/site"
    click EXAPP "https://github.com/ocean-h1/pixie-ui/tree/master/examples/basic"

    %% Styles
    classDef packages fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef apps fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef infra fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef external fill:#f8d7da,stroke:#721c24,stroke-width:2px;
```
