# luanroger/electron-shadcn architecture

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

- Interactive diagram: https://gitdiagram.com/luanroger/electron-shadcn
- Repository: https://github.com/luanroger/electron-shadcn

## Overview

Based on our review of the file tree and README, this project is an Electron application template (named electron‑shadcn) that sets up a modern desktop application using Electron, Vite, React, TypeScript, and several other supporting libraries and tools. The primary purpose is to provide a template for building beautiful, fully featured desktop applications with a custom title bar, IPC (Inter-Process Communication) helpers, custom theming, localization, and testing support.

##### Main Components
- Electron Main Process – Represented by files like src/main.ts and the Vite main configuration (vite.main.config.ts). This is where the application’s backend and window lifecycle management reside.
- Preload Process – Found in src/preload.ts and vite.preload.config.ts. This script bridges the main process and the renderer, exposing IPC channels safely via context isolation.
- Renderer Process – Represented by src/renderer.ts and the React-based UI code inside src/App.tsx, src/pages, src/components, src/layouts, and src/styles. This is the front-end portion of the app.
- IPC Helpers – Located in src/helpers/ipc, these modules (with subdirectories for theme and window) encapsulate the communication logic between the renderer and the main process.
- Assets and Configuration – Assets (fonts, images) are stored under src/assets, while configuration and library files (like tsconfig.json, package.json, Vite configs, ESLint/Prettier configurations) indicate how the project is built and linted.
- Testing Infrastructure – The tests folder contains unit tests (with Vitest) and e2e tests (with Playwright), ensuring reliable behavior on both front-end and integration levels.
- Packaging and Distribution – Electron Forge related scripts and configurations (e.g., forge.config.ts) indicate steps for building and packaging the desktop app.

##### Relationships & Interactions
- The Main Process is responsible for creating and managing the native windows. It launches the Preload process, which exposes secure, context-isolated features to the Renderer.
- The Renderer houses the UI, composed of modular React components (organized into UI and template sections) that interact with helper functions for localization, theming, and routing. Emphasize how the UI sends events via IPC to perform OS-level actions.
- Testing components interact with both Renderer and underlying Electron behaviors, so include a testing block that connects to these layers.
- The build pipeline (Vite and Electron Forge) coordinates how code from these layers is bundled and packaged into distributable executables.

##### Architectural Patterns & Design Principles
- Separation of Concerns: Distinct directories and modules separate concerns (UI vs. IPC helpers vs. configurations).
- IPC Design: Dedicated directories and modules for handling IPC for window and theme management highlight a clear pattern for safe communication between processes.
- Modular, Component-Based UI: The project leverages React components for reusable UI elements (supported by Shadcn UI and Tailwind), integrated using a router (TanStack Router) for navigation.
- Testing Integration: Both unit (Vitest) and end-to-end (Playwright) tests are included, ensuring that components and IPC integrations work as expected.

## Diagram (Mermaid)

```mermaid
graph TD
  %% Electron Processes
  subgraph "Electron Processes"
    EMain["Electron Main Process (Manage windows, backend)"]:::main
    EMain1["Main File"]:::main
    EMain2["Vite Main Config"]:::main
    Preload["Preload Process (Expose context-isolated APIs)"]:::preload
    Preload1["Preload Script"]:::preload
    Preload2["Vite Preload Config"]:::preload

    EMain --> EMain1
    EMain --> EMain2
    Preload --> Preload1
    Preload --> Preload2
    EMain -->|"launches"| Preload
  end

  %% Renderer Process
  subgraph "Renderer Process"
    R1["Renderer Entry"]:::renderer
    R2["App Component"]:::renderer
    R3["Pages"]:::renderer
    R4["UI Components"]:::renderer
    R5["Layouts"]:::renderer
    R6["Styles"]:::renderer

    R1 --> R2
    R2 --> R3
    R3 --> R4
    R4 --> R5
    R5 --> R6
    Preload -->|"bridgesAPI"| R1
  end

  %% IPC & Communication
  subgraph "IPC & Communication"
    IPC["IPC Helpers"]:::ipc
  end
  R4 ---|"IPCcalls"| IPC

  %% Assets & Configurations
  subgraph "Assets & Configurations"
    Assets["Assets (Images, Fonts)"]:::assets
    Config["Configuration Files"]:::assets
  end
  R2 -->|"uses"| Assets
  Config <-->|"configures"| R1

  %% Build & Packaging
  subgraph "Build & Packaging"
    Packaging["Packaging & Distribution"]:::packaging
    PackEnv["Forge Env"]:::packaging
    Packaging --> PackEnv
  end
  EMain ---|"bundled"| Packaging
  R6 ---|"bundled"| Packaging

  %% Testing Infrastructure
  subgraph "Testing Infrastructure"
    Unit["Unit Tests"]:::testing
    E2E["E2E Tests"]:::testing
    CI["CI Workflows"]:::testing
  end
  R1 ---|"testedBy"| Unit
  IPC ---|"testedBy"| Unit
  EMain ---|"testedBy"| E2E
  Packaging ---|"testedBy"| CI

  %% Click Events
  click EMain1 "https://github.com/luanroger/electron-shadcn/blob/main/src/main.ts"
  click EMain2 "https://github.com/luanroger/electron-shadcn/blob/main/vite.main.config.ts"
  click Preload1 "https://github.com/luanroger/electron-shadcn/blob/main/src/preload.ts"
  click Preload2 "https://github.com/luanroger/electron-shadcn/blob/main/vite.preload.config.ts"
  click R1 "https://github.com/luanroger/electron-shadcn/blob/main/src/renderer.ts"
  click R2 "https://github.com/luanroger/electron-shadcn/blob/main/src/App.tsx"
  click R3 "https://github.com/luanroger/electron-shadcn/tree/main/src/pages"
  click R4 "https://github.com/luanroger/electron-shadcn/tree/main/src/components"
  click R5 "https://github.com/luanroger/electron-shadcn/tree/main/src/layouts"
  click R6 "https://github.com/luanroger/electron-shadcn/tree/main/src/styles"
  click IPC "https://github.com/luanroger/electron-shadcn/tree/main/src/helpers/ipc"
  click Assets "https://github.com/luanroger/electron-shadcn/tree/main/src/assets"
  click Config "https://github.com/luanroger/electron-shadcn/blob/main/package.json"
  click Unit "https://github.com/luanroger/electron-shadcn/tree/main/src/tests/unit"
  click E2E "https://github.com/luanroger/electron-shadcn/tree/main/src/tests/e2e"
  click CI "https://github.com/luanroger/electron-shadcn/tree/main/.github/workflows"
  click Packaging "https://github.com/luanroger/electron-shadcn/blob/main/forge.config.ts"
  click PackEnv "https://github.com/luanroger/electron-shadcn/blob/main/forge.env.d.ts"

  %% Styles
  classDef main fill:#ffcccc,stroke:#990000,stroke-width:2px;
  classDef preload fill:#cceeff,stroke:#006699,stroke-width:2px;
  classDef renderer fill:#ccffcc,stroke:#006600,stroke-width:2px;
  classDef ipc fill:#ffffcc,stroke:#cccc00,stroke-width:2px;
  classDef assets fill:#e6ccff,stroke:#660099,stroke-width:2px;
  classDef packaging fill:#d9d9d9,stroke:#666666,stroke-width:2px;
  classDef testing fill:#ffebcc,stroke:#cc6600,stroke-width:2px;
```
