# heychhavi/preswald architecture

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

- Interactive diagram: https://gitdiagram.com/heychhavi/preswald
- Repository: https://github.com/heychhavi/preswald

## Overview

##### Project Type and Purpose
- Preswald is an open-source framework for building interactive data dashboards, apps, and internal tools using Python. It provides pre-built UI components, stateful execution using a workflow DAG, and a simple one-command deployment, meaning the framework spans both a backend engine and a frontend interface.

##### File Structure
- Notice the separation into directories like “frontend”, “preswald”, “docs”, “examples”, “docker”, and “tests”.
- The “frontend” directory contains UI-related code and components (React/JSX files, Tailwind configuration, etc.) that build the user interface.
- The “preswald” directory contains the core engine and CLI modules, including execution management (in “engine”), browser integration (in “browser”), interfaces with components and workflows (in “interfaces”), and templating files.
- The “autotest”, “docker”, and “examples” directories indicate support for testing, containerized deployment, and various example applications.
- The configuration files (like preswald.toml, pyproject.toml, and setup.py) show how projects are initialized, configured, and deployed.

##### Key Architectural Components
a. Frontend:
- Client-side web interface built using modern JS frameworks (React, JSX components) to render interactive UI components.
- Assets (e.g., images, CSS) and configuration (like Vite, Tailwind) found in the “frontend” directory.
b. Backend / Core Engine:
- The “preswald/engine” modules that handle workflow execution, state tracking, dependency management, and overall orchestration using a Directed Acyclic Graph (DAG) based on the README.
- CLI and deployment functionalities in modules like “preswald/cli.py” and “preswald/deploy.py”.
- Additional supportive engines like telemetry, data and layout management (in “preswald/engine/managers”) and services (server_service.py, service.py).
c. Templating & Configuration:
- “preswald/templates” holds templates for Dockerfiles, configuration files (e.g., preswald.toml.template), and other starter files.
- Configuration files (preswald.toml, secrets.toml, etc.) which let users customize and extend the app.
d. Testing / Deployment:
- “docker” directory and related deployment entries (e.g., Dockerfiles).
- “autotest” for automated deployments/tests ensuring app reliability.
e. Examples and Documentation:
- “examples” directory shows how multiple real-world data apps (finance, SP500, health, etc.) are structured.
- “docs” folder provides detailed guides, including CLI instructions, usage examples, and API references.

##### Relationships and Data Flow
- The CLI commands (e.g., preswald init, run, deploy) serve as entry points that integrate with the backend.
- The configuration (from preswald.toml and other config files) flows into both the engine and the templating system to ensure the apps are rendered with consistent settings.
- The deployment pipeline (using Docker, autotest, etc.) ties into the release process and how the app is distributed to users (either locally or in the cloud).

##### Architectural Patterns and Design Principles
- MVC / Separation of Concerns: The division between the frontend (presentation layer) and backend (logic, state, workflow management) is central.
- Modular/Plugin Architecture: The distinct “managers” in the engine and the multiple UI component modules support extending functionality.
- Workflow DAG: Highlight that the execution order is managed via a DAG, ensuring that stateful updates occur only when necessary.
- Configuration-Driven: Use of configuration templates and TOML files denotes heavy reliance on declarative setup for customization.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI & Deployment Layer
    subgraph "CLI & Deployment Layer"
        CLI["CLI Module"]:::cliLayer
        Deploy["Deployment Module"]:::cliLayer
    end

    %% Templating & Configuration Layer
    subgraph "Templating & Configuration"
        Templates["Templates"]:::config
        ConfigFiles["Configuration Files"]:::config
    end

    %% Core Engine Layer
    subgraph "Core Engine Layer"
        EngineCore["Engine/Workflow Manager"]:::engine
        EngineRunner["Runner (Execution)"]:::engine
        EngineManagers["Engine Managers"]:::engine
    end

    %% Frontend/UI Layer
    subgraph "Frontend/UI Layer"
        UIComponents["UI Components"]:::frontend
        UIApp["App.jsx"]:::frontend
    end

    %% Testing & Deployment Infrastructure
    subgraph "Testing & Deployment Infrastructure"
        Docker["Docker Deployment"]:::infra
        Autotest["Autotest Deployments"]:::infra
    end

    %% Examples & Documentation
    subgraph "Examples & Documentation"
        Examples["Example Apps"]:::docs
        Docs["Documentation"]:::docs
    end

    %% Connections: CLI & Deployment to Core Engine
    CLI -->|"triggers"| EngineCore
    Deploy -->|"initiates"| EngineCore

    %% Connections: Templating & Configuration to Core Engine
    Templates -->|"configures"| EngineCore
    ConfigFiles -->|"configures"| EngineCore

    %% Internal Core Engine management
    EngineCore -->|"manages"| EngineRunner
    EngineCore -->|"manages"| EngineManagers

    %% Core Engine to Frontend/UI
    EngineCore -->|"rendersResults"| UIComponents
    EngineCore -->|"rendersResults"| UIApp

    %% Deployment integration with Testing Infrastructure
    Deploy -->|"deployPipeline"| Docker
    Deploy -->|"deployPipeline"| Autotest

    %% Examples & Documentation influence Frontend/UI
    Examples -->|"influences"| UIComponents
    Docs -->|"influences"| UIComponents

    %% Click Events
    click CLI "https://github.com/heychhavi/preswald/blob/main/preswald/cli.py"
    click Deploy "https://github.com/heychhavi/preswald/blob/main/preswald/deploy.py"
    click Templates "https://github.com/heychhavi/preswald/blob/main/preswald/templates/preswald.toml.template"
    click ConfigFiles "https://github.com/heychhavi/preswald/blob/main/preswald.toml"
    click EngineCore "https://github.com/heychhavi/preswald/tree/main/preswald/engine"
    click EngineRunner "https://github.com/heychhavi/preswald/blob/main/preswald/engine/runner.py"
    click EngineManagers "https://github.com/heychhavi/preswald/tree/main/preswald/engine/managers"
    click UIComponents "https://github.com/heychhavi/preswald/tree/main/frontend/src/components"
    click UIApp "https://github.com/heychhavi/preswald/blob/main/frontend/src/App.jsx"
    click Docker "https://github.com/heychhavi/preswald/blob/main/docker/preswald_app.Dockerfile"
    click Autotest "https://github.com/heychhavi/preswald/tree/main/autotest/deployments"
    click Examples "https://github.com/heychhavi/preswald/blob/main/examples/SP500/README.md"
    click Docs "https://github.com/heychhavi/preswald/blob/main/docs/README.md"

    %% Styles
    classDef frontend fill:#B3E5FC,stroke:#01579B,stroke-width:2px;
    classDef engine fill:#FFCDD2,stroke:#B71C1C,stroke-width:2px;
    classDef cliLayer fill:#FFF9C4,stroke:#F57F17,stroke-width:2px;
    classDef config fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px;
    classDef infra fill:#FFE082,stroke:#FF8F00,stroke-width:2px;
    classDef docs fill:#D1C4E9,stroke:#512DA8,stroke-width:2px;
```
