# puruvj/macos-web architecture

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

- Interactive diagram: https://gitdiagram.com/puruvj/macos-web
- Repository: https://github.com/puruvj/macos-web

## Overview

##### Project Type and Purpose
- The README clearly explains that this project is a web-based recreation of the macOS desktop experience.
- It emphasizes that it is built in Svelte (previously in Preact), uses Vite for rapid development, and features styling with SCSS.
- Think of the system as a highly interactive, client-side user interface application that mimics the desktop operating system.

##### File Structure to Identify Main Components
- Top-level directories:
- “src”: The heart of the application, containing subdirectories for:
⮞ “components”: Organized by functionality (Desktop, Dock, TopBar, SystemUI, apps, and SVG components). These are the visual and interaction elements of the UI.
⮞ “actions”: Contains event and behavior helpers (e.g., click-outside, focus-outside, portal, trap-focus) that manage interactive behaviors.
⮞ “configs”: Holds configuration files for apps, menus, wallpapers, and themes, which guide how the UI is customized.
⮞ “helpers”: Utility functions to support various application needs such as fading animations, random values, or app configuration creation.
⮞ “state”: Svelte state management modules (using Svelte’s reactivity) for apps, dock, menubar, system settings, etc.
⮞ “assets”: Additional static resources (wallpapers, etc.) utilized by the components.
- “index.html” and “main.ts”: Serve as the application’s entry point, bootstrapping the Svelte app.
- Configuration and build files (e.g., package.json, vite.config.ts, svelte.config.js) which don’t map directly as components but are essential for project build and deployment.

##### Final Advice
- Be as detailed as possible — it’s best to break the application into every conceivable module rather than oversimplify.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Bootstrap Layer
    A["Bootstrap (index.html, main.ts)"]:::bootstrap

    %% UI Components Layer
    subgraph "UI Components"
        B["Desktop Module"]:::ui
        C["Window Management"]:::ui
        D["Dock"]:::ui
        E["TopBar"]:::ui
        F["Application Modules"]:::ui
        N["SVG Icons"]:::ui
        O["System UI Components"]:::ui
    end

    %% Application Modules Subgroup inside UI Components
    subgraph "Application Modules"
        G["Calculator"]:::ui
        H["Calendar"]:::ui
        I["PurusProfile"]:::ui
        J["VSCode"]:::ui
        K["WallpaperApp"]:::ui
        L["AppStore"]:::ui
        M["AppNexus"]:::ui
    end

    %% Utility and Support Layers
    P["State Management"]:::state
    Q["Configuration Files"]:::config
    R["Actions & Behaviors"]:::utility
    S["Helper Functions"]:::utility
    T["Public Assets"]:::asset

    %% Connections from Bootstrap to UI Components
    A -->|"initializes"| B
    A -->|"initializes"| D
    A -->|"initializes"| E
    A -->|"initializes"| N
    A -->|"initializes"| O

    %% Connections within UI Components
    B -->|"contains"| C
    B -->|"hosts"| F
    B -->|"integrates with"| D
    B -->|"integrates with"| E

    %% Interactions between UI and Application Modules
    F -->|"triggers state"| P
    D -->|"user interactions"| P
    E -->|"user interactions"| P

    %% UI Components consuming configurations and assets
    B -->|"reads"| Q
    D -->|"reads"| Q
    E -->|"reads"| Q
    F -->|"reads"| Q
    N -->|"uses"| Q

    T ---|"provides assets to"| B
    T ---|"provides assets to"| D
    T ---|"provides assets to"| E
    T ---|"provides assets to"| F
    T ---|"provides assets to"| N
    T ---|"provides assets to"| O

    %% UI Components using utility actions and helpers
    B ---|"invokes"| R
    D ---|"invokes"| R
    E ---|"invokes"| R
    F ---|"invokes"| R

    B ---|"utilizes"| S
    D ---|"utilizes"| S
    E ---|"utilizes"| S
    F ---|"utilizes"| S

    %% Application Modules interactions with State Management
    G -->|"updates"| P
    H -->|"updates"| P
    I -->|"updates"| P
    J -->|"updates"| P
    K -->|"updates"| P
    L -->|"updates"| P
    M -->|"updates"| P

    %% Click Events
    click B "https://github.com/puruvj/macos-web/tree/main/src/components/Desktop"
    click C "https://github.com/puruvj/macos-web/tree/main/src/components/Desktop/Window"
    click D "https://github.com/puruvj/macos-web/tree/main/src/components/Dock"
    click E "https://github.com/puruvj/macos-web/tree/main/src/components/TopBar"
    click G "https://github.com/puruvj/macos-web/tree/main/src/components/apps/Calculator"
    click H "https://github.com/puruvj/macos-web/tree/main/src/components/apps/Calendar"
    click I "https://github.com/puruvj/macos-web/tree/main/src/components/apps/PurusProfile"
    click J "https://github.com/puruvj/macos-web/tree/main/src/components/apps/VSCode"
    click K "https://github.com/puruvj/macos-web/tree/main/src/components/apps/WallpaperApp"
    click L "https://github.com/puruvj/macos-web/tree/main/src/components/apps/AppStore"
    click M "https://github.com/puruvj/macos-web/blob/main/src/components/apps/AppNexus.svelte"
    click N "https://github.com/puruvj/macos-web/tree/main/src/components/SVG"
    click O "https://github.com/puruvj/macos-web/tree/main/src/components/SystemUI"
    click P "https://github.com/puruvj/macos-web/tree/main/src/state"
    click R "https://github.com/puruvj/macos-web/tree/main/src/actions"
    click Q "https://github.com/puruvj/macos-web/tree/main/src/configs"
    click S "https://github.com/puruvj/macos-web/tree/main/src/helpers"
    click T "https://github.com/puruvj/macos-web/tree/main/public"

    %% Styles
    classDef bootstrap fill:#0277bd,stroke:#01579b,stroke-width:2px,color:#ffffff;
    classDef ui fill:#2e7d32,stroke:#1b5e20,stroke-width:2px,color:#ffffff;
    classDef state fill:#fbc02d,stroke:#f57f17,stroke-width:2px,color:#000000;
    classDef config fill:#ef6c00,stroke:#e65100,stroke-width:2px,color:#ffffff;
    classDef utility fill:#5e35b1,stroke:#311b92,stroke-width:2px,color:#ffffff;
    classDef asset fill:#ffb300,stroke:#ff6f00,stroke-width:2px,color:#ffffff;
```
