How app-generator/free-site-builder works
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