# carl-labs/feeller-app architecture

> Architecture diagram of the GitHub repository carl-labs/feeller-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/carl-labs/feeller-app
- Repository: https://github.com/carl-labs/feeller-app

## Overview

##### Project type and purpose
- This is a front-end single-page application (SPA) written in React + TypeScript, built and served by Vite.
- It includes a minimal plugin-driven “core engine,” an ESLint setup, and supports HMR via either Babel or SWC.

##### File structure
- Top-level
- package.json, package-lock.json – dependencies & scripts
- vite.config.ts – Vite build/dev server config (plugins, aliases)
- eslint.config.js – linting rules (including optional React-X, React-DOM plugins)
- tsconfig*.json – TS compiler setups for app and Node
- main.cjs, preload.cjs – (optional) Node/Electron main & preload scripts
- index.html – application shell
- src/
- main.tsx – React entry point
- App.jsx – top-level React component
- components/ – UI pieces (e.g. TitleBar.tsx)
- utils/@core-engine.jsx – plugin host
- utils/Plugins/*.jsx – placeholderPlugin, etc.
- assets/css – global & module CSS

##### README for architectural hints
- Describes a minimal React+TS+Vite template
- Mentions two HMR plugins: @vitejs/plugin-react (Babel) or plugin-react-swc (SWC)
- Guides on expanding ESLint for type-aware rules

##### Main components & their interactions
A. Development & Build Layer
- ESLint (in-editor / CI) enforces code quality via eslint.config.js + tsconfig*.json
- Vite Dev Server (via vite.config.ts + React plugin) watches src/, transforms TSX/JSX, and pushes HMR updates
- TypeScript compiler ensures type safety
B. Source Code Layer
- index.html bootstraps main.tsx
- main.tsx renders <App /> into the DOM
- App.jsx initializes @core-engine, loads Plugins dynamically
- Components (e.g. TitleBar) consume props, core-engine APIs, and CSS modules
- Assets (CSS, images) are imported and processed by Vite’s asset pipeline
C. Runtime & Hosting Layer
- Browser (or Electron’s renderer if main.cjs/preload.cjs are used) executes the bundled code
- Production build: Vite bundles modules (Rollup under the hood) into /dist → served by static host or CDN
D. (Optional) Node/Electron Layer
- main.cjs spawns BrowserWindow
- preload.cjs injects APIs into renderer

##### Architectural patterns & design principles
- SPA with unidirectional data flow (React)
- Plugin architecture (core-engine + Plugins folder) for extensibility
- Clear separation of concerns:
- Dev vs. Prod (Vite server vs. static build)
- UI components vs. engine vs. assets
- CSS Modules for scoped styling

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% Development Tools Layer
  subgraph "Development Tools"
    ESLint["ESLint (eslint.config.js)"]:::dev
    TSChecker["TypeScript Checker (tsconfig*.json)"]:::dev
    EditorCI["Editor / CI"]:::dev
  end

  %% Build & Bundler Layer
  subgraph "Build & Bundler Processes"
    ViteDev["Vite Dev Server (vite.config.ts)"]:::build
    BabelSWC["Babel/SWC Plugin"]:::build
    Watcher["File Watcher"]:::build
    HMR["HMR WebSocket"]:::build
    ProdBundle["Production Bundle (Rollup → /dist)"]:::build
  end

  %% Source Code Layer
  subgraph "Source Code Modules"
    HTML["index.html"]:::src
    Entry["main.tsx"]:::src
    AppComp["App.jsx"]:::src
    ComponentsDir["src/components/"]:::src
    TitleBar["TitleBar.tsx"]:::src
    CoreEngine["@core-engine.jsx"]:::src
    PluginsDir["src/utils/Plugins/"]:::src
    PlaceholderPlugin["placeholderPlugin.jsx"]:::src
    GlobalCSS["index.css"]:::src
    CSSModulesDir["src/assets/css/"]:::src
    NoteCSS["note.module.css"]:::src
    EnvTypes["vite-env.d.ts"]:::src
  end

  %% Runtime & Hosting Layer
  subgraph "Runtime & Hosting"
    Browser["Browser Renderer"]:::runtime
    ElectronMain["main.cjs"]:::runtime
    Preload["preload.cjs"]:::runtime
    CDN["Static Host / CDN"]:::runtime
  end

  %% Development flow
  EditorCI -->|edits| ESLint
  EditorCI -->|edits| TSChecker
  ESLint -->|validates| ViteDev
  TSChecker -->|types| ViteDev

  Watcher -->|detects changes| ViteDev
  ViteDev -->|uses| BabelSWC
  ViteDev -->|transforms| Entry
  ViteDev -->|serves| HMR
  HMR -->|push updates| Browser

  %% Source code flow
  HTML -->|bootstraps| Entry
  Entry -->|renders| AppComp
  AppComp -->|initializes| CoreEngine
  CoreEngine -->|loads| PlaceholderPlugin
  AppComp -->|renders| ComponentsDir
  ComponentsDir -->|includes| TitleBar
  Entry -->|imports| GlobalCSS
  AppComp -->|imports| CSSModulesDir
  CSSModulesDir -->|contains| NoteCSS
  Entry -->|loads| EnvTypes

  %% Production flow
  Entry -->|bundles| ProdBundle
  ProdBundle -->|deployed to| CDN
  CDN -->|serves| Browser

  %% Electron optional
  ElectronMain -->|spawns| Browser
  Preload -->|injects APIs| Browser

  %% Class Definitions
  classDef dev fill:#e3fcef,stroke:#2f855a,stroke-width:1px
  classDef build fill:#fff0d4,stroke:#dd6b20,stroke-width:1px
  classDef src fill:#ebf4ff,stroke:#3182ce,stroke-width:1px
  classDef runtime fill:#faf5ff,stroke:#805ad5,stroke-width:1px

  %% Click Events
  click ESLint "https://github.com/carl-labs/feeller-app/blob/main/eslint.config.js"
  click TSChecker "https://github.com/carl-labs/feeller-app/blob/main/tsconfig.json"
  click TSChecker "https://github.com/carl-labs/feeller-app/blob/main/tsconfig.app.json"
  click TSChecker "https://github.com/carl-labs/feeller-app/blob/main/tsconfig.node.json"
  click ViteDev "https://github.com/carl-labs/feeller-app/blob/main/vite.config.ts"
  click HTML "https://github.com/carl-labs/feeller-app/blob/main/index.html"
  click Entry "https://github.com/carl-labs/feeller-app/blob/main/src/main.tsx"
  click AppComp "https://github.com/carl-labs/feeller-app/blob/main/src/App.jsx"
  click ComponentsDir "https://github.com/carl-labs/feeller-app/tree/main/src/components/"
  click TitleBar "https://github.com/carl-labs/feeller-app/blob/main/src/components/TitleBar.tsx"
  click CoreEngine "https://github.com/carl-labs/feeller-app/blob/main/src/utils/@core-engine.jsx"
  click PluginsDir "https://github.com/carl-labs/feeller-app/tree/main/src/utils/Plugins/"
  click PlaceholderPlugin "https://github.com/carl-labs/feeller-app/blob/main/src/utils/Plugins/placeholderPlugin.jsx"
  click GlobalCSS "https://github.com/carl-labs/feeller-app/blob/main/src/index.css"
  click CSSModulesDir "https://github.com/carl-labs/feeller-app/tree/main/src/assets/css/"
  click NoteCSS "https://github.com/carl-labs/feeller-app/blob/main/src/assets/css/note.module.css"
  click ElectronMain "https://github.com/carl-labs/feeller-app/blob/main/main.cjs"
  click Preload "https://github.com/carl-labs/feeller-app/blob/main/preload.cjs"
  click EnvTypes "https://github.com/carl-labs/feeller-app/blob/main/src/vite-env.d.ts"
```
