# kusti8/proton-native architecture

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

- Interactive diagram: https://gitdiagram.com/kusti8/proton-native
- Repository: https://github.com/kusti8/proton-native

## Overview

##### Main Components
- User Application Layer: At the top, show that consumers write desktop apps with standard React syntax. This is represented in the examples (like Calculator, CatApi, Notepad) and the API built with React components.
- Proton Native Framework Core:
- React Components: These are found in both the src/components and src/react-components directories. They define the visual elements (e.g., Button, Window, TextInput).
- Reconciler: Located in src/reconciler, this module integrates with the React rendering process, performing the diffing and managing the conversion from virtual components to native widgets.
- Render Layer: In src/render, responsible for mapping reconciled components into actual instructions that the respective native backend understands.
- Utilities & Helpers: Files in src/utils and src/misc provide auxiliary functions (like style conversion, prop checking, and hot reloading support).
- Native Backends:
- Backend Abstraction: In src/backends, with separate modules for qt.ts and wx.ts, which abstract the details of the native toolkits.
- Development & Tooling:
- Hot Reloading and Debugging: Documented both in the docs and implemented in modules like src/misc/hot.ts.
- Tests: The test folder contains tests that capture interactions with components and the rendering behavior.
- Build/Configuration: Files such as package.json, tsconfig.json, and build scripts indicate how the project is configured.

##### Out the Relationships and Data Flow
- The user’s React components are processed by Proton Native’s custom Reconciler (src/reconciler) and Render (src/render) modules.
- The React components (src/react-components and src/components) serve as the high-level abstraction of UI elements.
- Additionally, include side components for Utilities and Hot Reloading which support the main rendering flow, enabling live updates and debugging.

##### Architectural Patterns and Design Principles
- Component Abstraction: The separation between UI components (both base and React-specific components) and the rendering logic illustrates a clear separation of concerns.
- Platform Abstraction: The backends (QT and wx) are isolated in their own modules, showing the use of abstraction to support cross-platform compatibility.
- Modular Design: The division into several directories (components, reconciler, render, utils) shows a modular approach where each part handles a distinct role.
- Integration with React: Emphasize that the Proton Native reconciler is built to work with the standard React lifecycle, making it easily integrable with React-centric libraries like Redux.

##### Technologies and Frameworks
- React: The project leverages the familiar React model, now targeting desktop.
- Native Toolkits (QT and wxWidgets): Abstracted in the backends.
- TypeScript: Many source files (with .ts and .tsx extensions) indicate use of TypeScript for static type checking.
- Hot Reloading: Supported by modules and documented in the docs for a better developer experience.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Application Layer"
        UC["User Code"]:::user
        E1["Calculator"]:::example
        E2["CatApi"]:::example
        E3["Notepad"]:::example
    end

    subgraph "Proton Native Framework Core"
        RC["React Components (src/components)"]:::react
        RRC["React Components (src/react-components)"]:::react
        REC["Reconciler (src/reconciler)"]:::core
        REN["Render Engine (src/render)"]:::core
        UTILS["Utilities (src/utils)"]:::util
        MISC["Misc Helpers (src/misc)"]:::util
    end

    subgraph "Native Backends"
        QT["QT Backend (src/backends/qt.ts)"]:::backend
        WX["wx Backend (src/backends/wx.ts)"]:::backend
    end

    subgraph "Development & Tooling"
        H["Hot Reloading (src/misc/hot.ts, docs/hot_reloading.md)"]:::tooling
        TEST["Tests (test)"]:::tooling
        BUILD["Build/Config (package.json, tsconfig.json)"]:::tooling
    end

    %% Main pipeline flow
    UC -->|"uses"| RC
    UC -->|"uses"| RRC
    RC -->|"processed by"| REC
    RRC -->|"processed by"| REC
    REC -->|"renders via"| REN
    REN -->|"platform call"| QT
    REN -->|"platform call"| WX

    %% Supporting flow from utilities and hot reload into render process
    UTILS --- REN
    MISC --- REN
    H --- REN

    %% Development tools feedback to User Code
    TEST -.->|"tests"| UC
    BUILD -.->|"builds"| UC

    %% Click Events
    click E1 "https://github.com/kusti8/proton-native/tree/master/examples/Calculator"
    click E2 "https://github.com/kusti8/proton-native/tree/master/examples/CatApi"
    click E3 "https://github.com/kusti8/proton-native/tree/master/examples/Notepad"
    click RC "https://github.com/kusti8/proton-native/tree/master/src/components"
    click RRC "https://github.com/kusti8/proton-native/tree/master/src/react-components"
    click REC "https://github.com/kusti8/proton-native/tree/master/src/reconciler"
    click REN "https://github.com/kusti8/proton-native/tree/master/src/render"
    click UTILS "https://github.com/kusti8/proton-native/tree/master/src/utils"
    click MISC "https://github.com/kusti8/proton-native/tree/master/src/misc"
    click QT "https://github.com/kusti8/proton-native/blob/master/src/backends/qt.ts"
    click WX "https://github.com/kusti8/proton-native/blob/master/src/backends/wx.ts"
    click H "https://github.com/kusti8/proton-native/blob/master/src/misc/hot.ts"
    click TEST "https://github.com/kusti8/proton-native/tree/master/test"
    click BUILD "https://github.com/kusti8/proton-native/blob/master/package.json"

    %% Styles
    classDef user fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef example fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef react fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
    classDef core fill:#ABEBC6,stroke:#27AE60,stroke-width:2px;
    classDef util fill:#F5CBA7,stroke:#E67E22,stroke-width:2px;
    classDef backend fill:#D2B4DE,stroke:#8E44AD,stroke-width:2px;
    classDef tooling fill:#FADBD8,stroke:#C0392B,stroke-width:2px;
```
