# enricllagostera/ponte architecture

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

- Interactive diagram: https://gitdiagram.com/enricllagostera/ponte
- Repository: https://github.com/enricllagostera/ponte

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Entities
    User["User"]:::external
    GitHub["GitHub Service"]:::external

    %% Electron App Boundary
    subgraph "Electron App" 
        direction TB

        %% Renderer Process
        subgraph "Renderer" 
            direction TB
            UI["UI Components"]:::ui
            Stores["Svelte Stores"]:::ui
            RFSAPI["fileSystem.ts"]:::api
            RQDAPI["qdpxExport.ts"]:::api
        end

        %% Preload IPC Bridge
        Preload["Preload Script\n(src/preload/index.js)"]:::ipc

        %% Main Process
        subgraph "Main Process" 
            direction TB
            MainIndex["index.ts"]:::backend
            GitMgr["gitManager.ts"]:::backend
            FSHandle["fileSystemHandling.ts"]:::backend
            DataInit["dataInitializer.js"]:::backend
            NormPath["normalize-path.ts"]:::backend
            JSONCanvas["jsonCanvas.ts"]:::backend
            QDPXExp["qdpxExport.js"]:::backend
            DOCX["docxBuilder.js"]:::backend
        end

        %% Local File System & Output
        FS["Local File System"]:::storage
        Output["QDA Output (.qdpx/.docx)"]:::storage

    end

    %% User interactions
    User -->|"click Import"| UI

    %% Renderer to Preload
    UI -->|"cloneRepo(url)"| Preload
    UI -->|"exportQDPX()"| Preload

    %% Preload to Main IPC Channels
    Preload -->|"ipc:/clone"| MainIndex
    Preload -->|"ipc:/export"| MainIndex

    %% Main pipeline orchestration
    MainIndex -->|"invoke gitManager"| GitMgr
    GitMgr -->|"git clone"| FS
    MainIndex -->|"invoke fileSystemHandling"| FSHandle
    FSHandle --> FS
    MainIndex -->|"invoke dataInitializer"| DataInit
    DataInit --> NormPath
    NormPath --> JSONCanvas
    JSONCanvas --> QDPXExp
    QDPXExp --> DOCX
    DOCX --> FS

    %% Notify Renderer when done
    MainIndex -->|"ipc:/progress"| Preload
    MainIndex -->|"ipc:/export:ready"| Preload
    Preload -->|"exportReady"| UI

    %% External GitHub interaction
    GitMgr -->|"clone via CLI"| GitHub

    %% Links for click events
    click MainIndex "https://github.com/enricllagostera/ponte/blob/main/src/main/index.ts"
    click GitMgr "https://github.com/enricllagostera/ponte/blob/main/src/main/gitManager.ts"
    click FSHandle "https://github.com/enricllagostera/ponte/blob/main/src/main/fileSystemHandling.ts"
    click DataInit "https://github.com/enricllagostera/ponte/blob/main/src/main/dataInitializer.js"
    click NormPath "https://github.com/enricllagostera/ponte/blob/main/src/main/normalize-path.ts"
    click JSONCanvas "https://github.com/enricllagostera/ponte/blob/main/src/main/jsonCanvas.ts"
    click QDPXExp "https://github.com/enricllagostera/ponte/blob/main/src/main/qdpxExport.js"
    click DOCX "https://github.com/enricllagostera/ponte/blob/main/src/main/docxBuilder.js"
    click Preload "https://github.com/enricllagostera/ponte/blob/main/src/preload/index.js"
    click RFSAPI "https://github.com/enricllagostera/ponte/blob/main/src/renderer/src/fileSystem.ts"
    click RQDAPI "https://github.com/enricllagostera/ponte/blob/main/src/renderer/src/qdpxExport.ts"
    click UI "https://github.com/enricllagostera/ponte/tree/main/src/renderer/src/components"
    click Stores "https://github.com/enricllagostera/ponte/blob/main/src/renderer/src/stores/stores.ts"

    %% Styles
    classDef external fill:#dddddd,stroke:#888888,color:#000000
    classDef ui fill:#cdeffd,stroke:#0366d6,color:#000000
    classDef api fill:#a0e7e5,stroke:#0098a8,color:#000000
    classDef ipc fill:#ffd966,stroke:#d97706,color:#000000
    classDef backend fill:#b7e4c7,stroke:#2f7d32,color:#000000
    classDef storage fill:#f0e68c,stroke:#b8860b,color:#000000
```
