How enricllagostera/ponte works
Project Type & Purpose
• This is an Electron-based desktop application (full-stack in the desktop sense) with a Node.js “backend” (the main process) and a Svelte/Vite-powered UI (the renderer).
• Purpose: clone a GitHub game-dev repository, analyze & transform its contents into a REFI-QDA project file (.qdpx/.docx), ready for import into QDA tools.
File-Structure Highlights & Architectural Choices
• Top level: Electron build configs (electron-builder.yml, electron.vite.config.mjs), packaging scripts, PostCSS & Tailwind configs.
• src/main: Node/Electron “main” process modules (gitManager, fileSystemHandling, dataInitializer, qdpxExport, docxBuilder).
• src/preload: secure IPC bridge (index.js) exporting limited APIs to the renderer.
• src/renderer: Svelte app + Vite; subdivided into:
• index.html + main.ts (bootstraps the UI)
• stores/ (state management)
• fileSystem.ts & qdpxExport.ts (renderer-side request APIs)
• components/ (UI widgets: timeline, commit list, dialogs, settings).
• No external database—uses local file system and ephemeral in-memory stores.
• External service: GitHub (via git CLI).
Key Architectural Patterns & Principles
• Electron multi-process: clear separation of concerns between main (heavy IO, git calls, file transforms) and renderer (interactive UI).
• Preload script as security boundary—exposes only safe, typed IPC channels.
• MVVM-like UI in Svelte: components bind to stores for state, actions dispatch IPC requests.
• Modular export pipeline: dataInitializer → normalization → JSON-canvas conversion → QDPX/XML export → optional docxBuilder.
Components & Interactions
a. Main Components
• User (desktop)
• Electron App (boundary)
• Renderer process (Svelte UI + stores)
• Preload script (IPC bridge)
• Main process (Node modules)
• External GitHub service
• Local File System
• QDA Output file (.qdpx, .docx)
b. Data Flow / Relationships
1. User triggers “Import Repo” in Renderer UI.
2. Renderer → via Preload → IPC request to Main: cloneRepo(url).
3. Main process uses gitManager to clone into a temp folder on Local FS.
4. Main process sequentially invokes: dataInitializer → normalizePath → jsonCanvas → qdpxExport → docxBuilder.
5. Main writes .qdpx/.docx to Local FS; notifies Renderer via IPC event.
6. Renderer displays “Export Ready” and allows user to save/open file.
c. Important Patterns
• IPC channels with strict types (/clone, /export, /progress).
• Svelte stores push progress updates to UI.
• Build pipeline as chain-of-responsibility modules in main.
d. Technologies & Frameworks
• Electron (main, preload, renderer)
• Node.js core modules (fs, path, child_process for git)
• Svelte + Vite + TypeScript + Tailwind CSS in the renderer
• electron-builder for packaging
• PostCSS for styling