# povilaskarvelis/e2p-simulator architecture

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

- Interactive diagram: https://gitdiagram.com/povilaskarvelis/e2p-simulator
- Repository: https://github.com/povilaskarvelis/e2p-simulator

## Overview

##### Project Type and Purpose
- The project is a web-based simulator designed for quantitative, interactive exploration of effect sizes versus predictive utility. Its primary audience includes biomedical, behavioral science, and other research communities.
- The README outlines that users can interact with the simulator via a browser and that the tool is meant to help with interpretation of statistical metrics, research planning, and educational purposes.

##### Main Components
a. User Interface (UI) Layer:
– HTML files (index.html, get-started.html) present the simulator’s front end.
– CSS styles are located in the “css” directory, ensuring consistency in design (e.g., base.css, binary.css, continuous.css).
– Client-side JavaScript located in the “js” directory (binary.js, continuous.js, main.js, etc.) handles interactivity, calculations (e.g., effect sizes, predictive utilities), and shared utilities.
– Images (e.g., screenshots) enhance the visual layout.

b. Configuration and Build/Development Tools:
– package.json and package-lock.json to manage dependencies and scripts.
– Node.js is required, as indicated in the README.
– GitHub workflows in the “.github/workflows” directory including CI scripts (like draft-pdf.yml) to automate documentation or other build tasks.

c. Testing Framework:
– End-to-end tests reside in the “cypress” directory. These include:
- E2E test scripts within “cypress/e2e”
- Test fixtures (sample data) in “cypress/fixtures”
- Screenshots and support utilities in “cypress/screenshots” and “cypress/support”
– These components illustrate the testing infrastructure that validates functionality for both “binary” and “continuous” simulation tests.

d. Supporting Documentation and Research Files:
– “README.md” for project overview, setup, and usage instructions.
– “CONTRIBUTING.md” and “LICENSE” files for community collaboration.
– The “paper” directory contains the research document (paper.md) and associated bibliography (paper.bib), highlighting an academic research component that underpins the simulator’s concepts.

##### Architectural Relationships and Data Flow
- The browser (client) is the primary consumer of the application, loading the HTML, CSS, and JS which work together to provide the interactive simulation.
- The JavaScript components perform the core logic, such as rendering the simulation, calculating effect sizes, and updating the UI dynamically based on user input.
- There is a clear separation between presentation (HTML/CSS) and logic (JS), typical of client-side web applications.
- Testing with Cypress runs in a separate testing environment that simulates user interactions and validates the UI/logic workflow.

##### Architectural Patterns and Design Principles
- Frontend Architecture: The project follows a client-side application design. The separation of concerns is evident from distinct directories for HTML, CSS, and JavaScript.
- Automated Testing: Use of Cypress tests reflects an emphasis on quality and continuous integration, as evidenced by documented workflows in the ‘.github’ directory.
- Research Integration: The inclusion of a “paper” directory shows the project’s basis in academic research, linking theoretical concepts with practical simulation.

- Browser Client:
– HTML (index.html, get-started.html)
– CSS (base.css, binary.css, continuous.css)
– JavaScript (binary.js, continuous.js, main.js, utils.js, etc.)
- Testing Layer:
– Cypress tests (binary-tests.cy.js, continuous-tests.cy.js, etc.) and test fixtures.
- Build and CI/CD:
– Node.js/npm scripts and GitHub workflows.
- Documentation & Research:
– README, CONTRIBUTING, LICENSE, and Research Paper artifacts.

## Diagram (Mermaid)

```mermaid
graph TD
    %% UI Layer: Browser Client
    subgraph "Browser Client (UI)"
        subgraph "HTML Files"
            HTMLIndex["index.html"]:::html
            HTMLGet["get-started.html"]:::html
        end
        subgraph "CSS Styles"
            CSSBase["base.css"]:::css
            CSSBinary["binary.css"]:::css
            CSSContinuous["continuous.css"]:::css
        end
        subgraph "JavaScript Simulation Logic"
            JSBinary["binary.js"]:::js
            JSContinuous["continuous.js"]:::js
            JSMain["main.js"]:::js
            JSUtils["utils.js"]:::js
        end
    end

    %% Testing Framework: Cypress
    subgraph "Testing Framework (Cypress)"
        E2ETests["E2E Test Scripts"]:::test
        TestFixtures["Test Fixtures"]:::test
        TestScreenshots["Screenshots"]:::test
        TestSupport["Support Utilities"]:::test
    end

    %% Build & CI/CD Tools
    subgraph "Build & CI/CD Tools"
        NpmDeps["npm Dependencies"]:::build
        GitHubWF["GitHub Workflows"]:::build
    end

    %% Documentation & Research
    subgraph "Documentation & Research"
        Readme["README.md"]:::docs
        Contrib["CONTRIBUTING.md"]:::docs
        License["LICENSE"]:::docs
        PaperDoc["Paper Document"]:::docs
        PaperBib["Paper Bibliography"]:::docs
    end

    %% Architectural Relationships
    %% UI interactions: within the Browser Client, HTML, CSS and JS work together
    HTMLIndex -->|"renders"| CSSBase
    HTMLGet  -->|"renders"| CSSContinuous
    JSMain    -->|"drives"| HTMLIndex
    JSMain    -->|"drives"| HTMLGet

    %% Testing: Cypress simulates and validates UI interactions
    JSMain -->|"triggers"| E2ETests
    E2ETests -->|"verifies"| JSMain

    %% Build & CI/CD: Build tools compile and deploy UI components
    NpmDeps -->|"builds"| HTMLIndex
    NpmDeps -->|"builds"| JSMain
    GitHubWF -->|"triggers"| NpmDeps
    GitHubWF -->|"deploys"| HTMLGet

    %% Documentation: Provides guidelines and research support
    Readme --- Contrib
    Readme --- License
    PaperDoc --- PaperBib

    %% Click Events for UI Layer Components
    click HTMLIndex "https://github.com/povilaskarvelis/e2p-simulator/blob/main/index.html"
    click HTMLGet "https://github.com/povilaskarvelis/e2p-simulator/blob/main/get-started.html"
    click CSSBase "https://github.com/povilaskarvelis/e2p-simulator/blob/main/css/base.css"
    click CSSBinary "https://github.com/povilaskarvelis/e2p-simulator/blob/main/css/binary.css"
    click CSSContinuous "https://github.com/povilaskarvelis/e2p-simulator/blob/main/css/continuous.css"
    click JSBinary "https://github.com/povilaskarvelis/e2p-simulator/blob/main/js/binary.js"
    click JSContinuous "https://github.com/povilaskarvelis/e2p-simulator/blob/main/js/continuous.js"
    click JSMain "https://github.com/povilaskarvelis/e2p-simulator/blob/main/js/main.js"
    click JSUtils "https://github.com/povilaskarvelis/e2p-simulator/blob/main/js/utils.js"

    %% Click Events for Testing Framework Components
    click E2ETests "https://github.com/povilaskarvelis/e2p-simulator/tree/main/cypress/e2e"
    click TestFixtures "https://github.com/povilaskarvelis/e2p-simulator/tree/main/cypress/fixtures"
    click TestScreenshots "https://github.com/povilaskarvelis/e2p-simulator/tree/main/cypress/screenshots"
    click TestSupport "https://github.com/povilaskarvelis/e2p-simulator/tree/main/cypress/support"

    %% Click Events for Build & CI/CD Components
    click NpmDeps "https://github.com/povilaskarvelis/e2p-simulator/blob/main/package.json"
    click GitHubWF "https://github.com/povilaskarvelis/e2p-simulator/blob/main/.github/workflows/draft-pdf.yml"

    %% Click Events for Documentation & Research Components
    click Readme "https://github.com/povilaskarvelis/e2p-simulator/blob/main/README.md"
    click Contrib "https://github.com/povilaskarvelis/e2p-simulator/blob/main/CONTRIBUTING.md"
    click License "https://github.com/povilaskarvelis/e2p-simulator/tree/main/LICENSE"
    click PaperDoc "https://github.com/povilaskarvelis/e2p-simulator/blob/main/paper/paper.md"
    click PaperBib "https://github.com/povilaskarvelis/e2p-simulator/blob/main/paper/paper.bib"

    %% Style Classes for Colour
    classDef html fill:#fceabb,stroke:#f08a5d,stroke-width:2px;
    classDef css fill:#c1f7dc,stroke:#49beb7,stroke-width:2px;
    classDef js fill:#c9c9ff,stroke:#7d7dff,stroke-width:2px;
    classDef test fill:#ffe0e0,stroke:#ff5858,stroke-width:2px;
    classDef build fill:#e0e0ff,stroke:#7070ff,stroke-width:2px;
    classDef docs fill:#e0ffec,stroke:#58ff7d,stroke-width:2px;
```
