# origamimagiro/flat-folder architecture

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

- Interactive diagram: https://gitdiagram.com/origamimagiro/flat-folder
- Repository: https://github.com/origamimagiro/flat-folder

## Overview

##### Project Type & Purpose
- Flat-Folder is a full-stack web application (client-side heavy) primarily built in JavaScript. Its purpose is to import crease pattern files, compute folding states (using Boolean variables and constraint graphs for overlapped crease faces), and display the results visually in the browser.
- The README details both the user interface flow (input file, crease pattern drawing, overlap graph, flat folded state, and export options) and the algorithmic details (computation of overlapping relationships, constraint propagation, and state enumeration).

##### Main Architectural Components
a. Presentation (UI) Layer:
- HTML/CSS/JS front end structure:
- index.html and batch.html serve as entry points.
- The GUI is handled by src/gui.js, which works together with the image assets (in the img folder) and uses SVG rendering (src/svg.js) to present the crease pattern and folded/overlap graph views.
- User Interaction:
- UI elements for file uploading, “Fold”, “Flip”, and “Export” options.
- Visualization of computed states (highlighted faces, overlays, text labels) and interactive components (e.g., clicking on a cell or face to display constraints).

b. Core Engine / Business Logic:
- Input/Output and File Handling:
- src/io.js manages file imports, parsing crease pattern formats.
- src/conversion.js converts data between FOLD, SVG, OPX, and CP formats.
- Computational Modules:
- src/compute.js and src/solver.js house the algorithms to compute valid fold states.
- src/constraints.js encapsulates computation of the four types of constraints (taco-taco, taco-tortilla, tortilla-tortilla, and transitivity) and manages Boolean variable assignments.
- src/math.js provides necessary mathematical operations used across the algorithm (for single-precision handling, distances, angles, etc.).
- src/note.js may be used for logging or debugging specific details in the folding process.
- src/examples.js assists with managing the examples available in the “examples” directory.

c. Parallel / Asynchronous Processing:
- Web Worker Integration:
- src/worker.js and modules in src/node_Worker_polyfill handle the heavy, asynchronous computation of the constraint graph and variable assignments.
- src/parallel.js coordinates dispatching work to these workers to avoid UI blocking during intensive computations.
- Flow: the UI invokes a computation → manager module dispatches work to a Web Worker → worker computes parts (constraint satisfaction, solution search) and returns results.

d. Data & Examples:
- Examples Folder:
- The “examples” directory contains numerous crease pattern files (*.fold) and CSV data files used for demonstration or testing.
- This folder’s content ties into the input modules and illustrates the variety of use cases.
- Export & Logging:
- The system supports export options (using src/svg.js to export snapshots, and “log” functionality to output console output).

##### Module Relationships and Data Flow
- Then, pass the parsed file to src/conversion.js to transform it into an internal data structure.
- This internal representation is handed to the Core Engine modules (src/compute.js, src/solver.js, src/constraints.js) which represent the computational “heart” of the application.
- That these modules use mathematical utilities (src/math.js) and delegate heavy tasks to asynchronous workers (src/worker.js via src/parallel.js).
- Once computations are finished, data is passed back to the GUI (src/gui.js) and the SVG renderer (src/svg.js) for display.
- The system also interacts with the “examples” data repository when a user wishes to load sample crease patterns.

##### Architectural Patterns and Design Principles
- Modular Design: Each functionality (I/O, Conversion, Computation, Parallel Processing, GUI) is encapsulated in its own JS module.
- Separation of Concerns: UI responsibilities are kept separate from the computational logic and data processing.
- Asynchronous Processing: Heavy computation is offloaded to Web Workers, ensuring the web interface remains responsive.
- Data Flow is clearly unidirectional: Input → Transformation → Computation → Rendering, with paths for exports and logging.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer"
        A1["index.html"]:::presentation
        A2["batch.html"]:::presentation
        A3["src/gui.js (UI Module)"]:::presentation
        A4["src/svg.js (SVG Renderer)"]:::presentation
        A5["img (Image Assets)"]:::presentation
    end

    %% Core Engine / Business Logic Layer
    subgraph "Core Engine / Business Logic"
        B1["src/io.js (File I/O)"]:::engine
        B2["src/conversion.js (Data Conversion)"]:::engine
        B3["src/compute.js (Computation)"]:::engine
        B4["src/solver.js (Solver)"]:::engine
        B5["src/constraints.js (Constraints Processing)"]:::engine
        B6["src/math.js (Math Utilities)"]:::engine
        B7["src/note.js (Logging/Debugging)"]:::engine
        B8["src/examples.js (Examples Management)"]:::engine
    end

    %% Parallel / Asynchronous Processing Layer
    subgraph "Parallel Processing Layer"
        C1["src/parallel.js (Parallel Coordinator)"]:::parallel
        C2["src/worker.js (Web Worker)"]:::parallel
        C3["src/node_Worker_polyfill (Polyfill)"]:::parallel
    end

    %% Data & Examples Layer
    subgraph "Data & Examples"
        D1["examples (Example Files)"]:::data
    end

    %% Data Flow Connections
    A1 -->|"uploadFile"| B1
    B1 -->|"parseFile"| B2
    B2 -->|"processData"| B3
    B2 -->|"processData"| B4
    B2 -->|"processData"| B5
    B3 -->|"useMath"| B6
    B4 -->|"useMath"| B6
    B5 -->|"log"| B7

    %% Parallel Processing Flow
    B3 -- "heavyTask" --> C1
    B4 -- "heavyTask" --> C1
    C1 -->|"distribute"| C2
    C2 -->|"support"| C3
    C1 -->|"returnResult"| B3

    %% GUI Rendering Flow
    B3 -->|"computedResult"| A3
    A3 -->|"renderSVG"| A4

    %% Examples Loading Flow
    A2 -->|"loadExamples"| B8
    B8 -->|"fetchExamples"| D1

    %% Click Events: Presentation Layer
    click A1 "https://github.com/origamimagiro/flat-folder/blob/main/index.html"
    click A2 "https://github.com/origamimagiro/flat-folder/blob/main/batch.html"
    click A3 "https://github.com/origamimagiro/flat-folder/blob/main/src/gui.js"
    click A4 "https://github.com/origamimagiro/flat-folder/blob/main/src/svg.js"
    click A5 "https://github.com/origamimagiro/flat-folder/tree/main/img"

    %% Click Events: Core Engine / Business Logic
    click B1 "https://github.com/origamimagiro/flat-folder/blob/main/src/io.js"
    click B2 "https://github.com/origamimagiro/flat-folder/blob/main/src/conversion.js"
    click B3 "https://github.com/origamimagiro/flat-folder/blob/main/src/compute.js"
    click B4 "https://github.com/origamimagiro/flat-folder/blob/main/src/solver.js"
    click B5 "https://github.com/origamimagiro/flat-folder/blob/main/src/constraints.js"
    click B6 "https://github.com/origamimagiro/flat-folder/blob/main/src/math.js"
    click B7 "https://github.com/origamimagiro/flat-folder/blob/main/src/note.js"
    click B8 "https://github.com/origamimagiro/flat-folder/blob/main/src/examples.js"

    %% Click Events: Parallel / Asynchronous Processing
    click C1 "https://github.com/origamimagiro/flat-folder/blob/main/src/parallel.js"
    click C2 "https://github.com/origamimagiro/flat-folder/blob/main/src/worker.js"
    click C3 "https://github.com/origamimagiro/flat-folder/tree/main/src/node_Worker_polyfill/"

    %% Click Events: Data & Examples
    click D1 "https://github.com/origamimagiro/flat-folder/tree/main/examples"

    %% Styles
    classDef presentation fill:#ffcccc,stroke:#990000,stroke-width:2px;
    classDef engine fill:#ccffcc,stroke:#009900,stroke-width:2px;
    classDef parallel fill:#ccccff,stroke:#000099,stroke-width:2px;
    classDef data fill:#ffffcc,stroke:#999900,stroke-width:2px;
```
