# app-generator/free-site-builder architecture

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

- Interactive diagram: https://gitdiagram.com/app-generator/free-site-builder
- Repository: https://github.com/app-generator/free-site-builder

## Overview

##### Project type and purpose
- This is a full-stack, open-source “Free Site Builder” SPA (Single-Page Application) that uses Vanilla JS/TypeScript on the client side and a lightweight Flask server on the back end to store and serve HTML “kits” (template components).
- The builder lets end-users drag & drop pre-built Bootstrap 5, Pixel BS5, or Volt BS5 components into a page canvas, customize them, save/restore via Local Storage, and fetch new components from a remote server.

##### File structure
- Top-level directories:
- backend/ → Flask REST service; apps/templates holds raw HTML snippets, organized by kit (bs5, pixel, volt), plus scripts to generate JSON manifest (generate_json_kit.py), and run.py as entry point.
- src/ → TypeScript source of the SPA, includes main.ts, dnd.ts (drag & drop), config.ts (endpoints), utiles.ts (helpers).
- public/ → static assets (images).
- dist/ → compiled JS/CSS bundles for distribution (index.js, style-*.css).
- src-css/ → source CSS for custom themes.
- build.sh, vite.config.ts, tsconfig.json → build toolchain (Vite).
- Patterns:
- SPA communicates via REST to Flask server.
- Persistence: Local Storage holds page state and cached info.json from server.
- Build: TS→JS via Vite/yarn; Python virtualenv for backend.

##### README insights
- Core tech: Vanilla JS, Flask.
- Remote Components Server endpoint: /kits/bs5/, /kits/pixel/, /kits/volt/.
- info.json files describe available layouts/components, each HTML snippet referenced by a Base64 digest.
- No traditional DB; file system templates + JSON manifest.

a. Main components
- User’s Browser (SPA UI)
- Static Asset Host (serves index.html, JS/CSS, images)
- SPA Modules:
– Drag-Drop Engine (dnd.ts)
– Component Renderer & Editor (main.ts + templates)
– Local Storage Persistence
– API Client (config.ts)
- Remote Flask Components Server (backend/run.py)
– Kits Manager (apps/templates/… + generate_json_kit.py)
– REST Endpoint (/kits/<kit>/)
- File Storage (file system templates & info.json)
- (Optional) CI/CD / Build Pipeline (Vite, Yarn, build.sh)
b. Relationships & Data Flows
1. Browser requests index.html + JS/CSS from Static Asset Host.
2. User interacts with SPA; drag-drop events processed by the Drag-Drop Engine.
3. SPA makes HTTP GET to Flask Server /kits/<kit>/ to fetch info.json (component list & Base64 hashes).
4. SPA fetches individual component HTML (if needed) or uses cached data from Local Storage.
5. User edits styles/text; SPA serializes page state & writes to Local Storage (“Save”).
6. (Optional) Developer runs build pipeline (Yarn/Vite) to regenerate dist/ assets or restarts Flask server in its virtualenv.
c. Architectural Patterns & Principles
- SPA + REST micro-service separation (clear front/back split)
- Client-side persistence via Local Storage (no DB)
- File-based manifest generation (generate_json_kit.py)
- Modular source: each kit and component lives in its own directory
d. Key Technologies & Frameworks
- Frontend: Vanilla JS/TypeScript, Vite, Drag-Drop API, Local Storage API
- CSS Frameworks: Bootstrap 5, Pixel BS5, Volt BS5
- Backend: Python 3, Flask, Jinja2 templates (apps/templates)
- Build: Yarn/NPM, Vite, virtualenv, pip

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% Frontend Zone
  subgraph "Frontend (Browser)"
    direction TB
    SPA["SPA Bundled Assets"]:::frontend
    DnD["Drag-Drop Engine"]:::frontend
    Renderer["Component Renderer & Editor"]:::frontend
    APIClient["API Client"]:::frontend
    LocalStore["Local Storage"]:::storage
  end

  StaticHost["Static Asset Host"]:::frontend
  publicImg["public/img/"]:::frontend

  %% Developer Build Pipeline
  subgraph "Developer Build Pipeline"
    direction TB
    tsconfig["tsconfig.json"]:::pipeline
    viteconfig["vite.config.ts"]:::pipeline
    buildRoot["build.sh (root)"]:::pipeline
    YarnVite["Yarn / Vite"]:::pipeline
    distIndex["dist/index.js"]:::frontend
    distUMD["dist/index.umd.cjs"]:::frontend
    styleCore["dist/style.css"]:::frontend
    stylePixel["dist/style-pixel.css"]:::frontend
    styleVolt["dist/style-volt.css"]:::frontend
  end

  %% Backend Zone
  subgraph "Backend (Server)"
    direction TB
    Flask["Flask Server"]:::backend
    Views["Flask Views / REST Endpoints"]:::backend
    Config["Flask App Configuration"]:::backend
    GenJSON["Kits JSON Manifest Generator"]:::backend
    KitsManager["Kits Manager Templates"]:::backend
    KitsList["Kits List Manifest"]:::database
    Manifests["Kits Manifests (info.json)"]:::database
    BackendBuild["backend/build.sh"]:::pipeline
  end

  %% Relationships
  Browser["User Browser"]:::external
  Browser -->|"GET index.html, JS/CSS"| StaticHost
  StaticHost -->|serves| SPA
  StaticHost -->|serves images| publicImg
  SPA -->|uses| DnD
  SPA -->|uses| Renderer
  SPA -->|calls| APIClient
  SPA -->|saves/loads| LocalStore
  APIClient -->|GET /kits/<kit>/| Flask
  Flask -->|invokes| Views
  Views -->|reads| KitsList
  Views -->|reads| Manifests
  KitsList -->|lists kits| KitsManager
  KitsManager -->|contains templates| Manifests
  GenJSON -->|generates| Manifests
  BackendBuild -->|runs| Flask
  tsconfig -->|configures| YarnVite
  viteconfig -->|configures| YarnVite
  buildRoot -->|invokes| YarnVite
  YarnVite -->|outputs| distIndex
  YarnVite -->|outputs| distUMD
  YarnVite -->|outputs| styleCore
  YarnVite -->|outputs| stylePixel
  YarnVite -->|outputs| styleVolt
  Browser -->|drag & drop| DnD

  %% Click Events
  click DnD "https://github.com/app-generator/free-site-builder/blob/main/src/dnd.ts"
  click Renderer "https://github.com/app-generator/free-site-builder/blob/main/src/main.ts"
  click APIClient "https://github.com/app-generator/free-site-builder/blob/main/src/config.ts"
  click LocalStore "https://github.com/app-generator/free-site-builder/blob/main/src/utiles.ts"
  click tsconfig "https://github.com/app-generator/free-site-builder/blob/main/tsconfig.json"
  click viteconfig "https://github.com/app-generator/free-site-builder/blob/main/vite.config.ts"
  click distIndex "https://github.com/app-generator/free-site-builder/blob/main/dist/index.js"
  click distUMD "https://github.com/app-generator/free-site-builder/blob/main/dist/index.umd.cjs"
  click styleCore "https://github.com/app-generator/free-site-builder/blob/main/dist/style.css"
  click stylePixel "https://github.com/app-generator/free-site-builder/blob/main/dist/style-pixel.css"
  click styleVolt "https://github.com/app-generator/free-site-builder/blob/main/dist/style-volt.css"
  click publicImg "https://github.com/app-generator/free-site-builder/tree/main/public/img/"
  click Flask "https://github.com/app-generator/free-site-builder/blob/main/backend/run.py"
  click Views "https://github.com/app-generator/free-site-builder/blob/main/backend/apps/views.py"
  click Config "https://github.com/app-generator/free-site-builder/blob/main/backend/apps/config.py"
  click GenJSON "https://github.com/app-generator/free-site-builder/blob/main/backend/generate_json_kit.py"
  click KitsManager "https://github.com/app-generator/free-site-builder/tree/main/backend/apps/templates/bs5/"
  click KitsManager "https://github.com/app-generator/free-site-builder/tree/main/backend/apps/templates/pixel/"
  click KitsManager "https://github.com/app-generator/free-site-builder/tree/main/backend/apps/templates/volt/"
  click Manifests "https://github.com/app-generator/free-site-builder/blob/main/backend/apps/templates/bs5/info.json"
  click Manifests "https://github.com/app-generator/free-site-builder/blob/main/backend/apps/templates/pixel/info.json"
  click Manifests "https://github.com/app-generator/free-site-builder/blob/main/backend/apps/templates/volt/info.json"
  click KitsList "https://github.com/app-generator/free-site-builder/blob/main/backend/apps/templates/kits.json"
  click BackendBuild "https://github.com/app-generator/free-site-builder/blob/main/backend/build.sh"
  click buildRoot "https://github.com/app-generator/free-site-builder/blob/main/build.sh"

  %% Styles
  classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#000
  classDef backend fill:#E8F5E9,stroke:#2E7D32,color:#000
  classDef storage fill:#FFF8E1,stroke:#F9A825,color:#000
  classDef database fill:#ECEFF1,stroke:#90A4AE,color:#000
  classDef pipeline fill:#F3E5F5,stroke:#8E24AA,color:#000
  classDef external fill:#FFEBEE,stroke:#C62828,color:#000
```
