# avaiga/taipy architecture

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

- Interactive diagram: https://gitdiagram.com/avaiga/taipy
- Repository: https://github.com/avaiga/taipy

## Overview

1. This is a monorepo for the Taipy platform, centered on a Python runtime with several installable subpackages: `taipy-common`, `taipy-core`, `taipy-gui`, `taipy-rest`, and `taipy-templates`. The top-level `taipy` package acts as the umbrella entry point and bundles the pieces into a single developer-facing product.

2. `taipy/common` is the shared foundation. It owns CLI plumbing, configuration models and serialization, logging, version metadata, and common validation utilities. Other subsystems inherit these conventions rather than defining their own configuration or command-line behavior.

3. `taipy/core` is the domain and orchestration engine. It models workflow entities such as scenarios, sequences, tasks, jobs, cycles, submissions, and data nodes. The architecture here is manager/repository oriented: managers coordinate domain logic, repositories persist models, converters serialize them, and orchestrator/dispatcher components submit and run jobs.

4. Core persistence is storage-agnostic but clearly layered. The `_repository` and `_manager` packages abstract entity access, while concrete data modules support file-based, in-memory, JSON, CSV, Excel, Parquet, pickle, SQL, MongoDB, and S3-backed data nodes. This makes storage an important boundary in the architecture diagram.

5. Core also has a versioning and migration subsystem. The `_version` and `_entity/_migrate` packages indicate explicit support for versioned persisted state, migration between repository layouts, and compatibility handling for older stored artifacts.

6. Events are a first-class cross-cutting concern in core. The `notification` package provides event publishing/consumption, topic registration, and event models, allowing state changes in scenarios, jobs, and data nodes to propagate to other layers without tight coupling.

7. `taipy/gui` is the Python-side application framework for building interactive interfaces. It includes page abstractions, builder APIs, renderers for Markdown and HTML, state handling, data accessors, and server integration. The Python layer is responsible for turning user-defined variables and callbacks into a structured UI model.

8. The GUI runtime is split between backend and frontend. On the backend, `taipy/gui/servers` exposes the app, with Flask-based server support and request handling. On the frontend, `frontend/taipy-gui` is a React + TypeScript component library that renders Taipy controls, pages, themes, drag-and-drop/table helpers, WebSocket/context utilities, and supporting tests.

9. GUI data flow is model-driven: Python state and bindings are parsed into renderable element trees, pushed to the browser, and synchronized back through actions, callbacks, and websocket/context updates. The file upload worker and data accessors show that large or structured data is normalized before it reaches UI components.

10. `frontend/taipy` is a second React/TypeScript package focused on Taipy-specific operational views and diagrams, such as scenarios, jobs, data nodes, and properties editing. It uses diagramming/project-storm style components to visualize and manipulate core entities rather than rendering generic UI controls.

11. `taipy/rest` exposes the core domain over HTTP. It contains Flask application setup, resource handlers for cycles/data nodes/jobs/scenarios/sequences/tasks, schemas, middleware, and API documentation helpers. This layer is a separate service boundary around the same core models, suitable for integrations and automation.

12. `taipy/templates` provides cookiecutter-style project scaffolding. The templates generate starter applications for different Taipy patterns, including scenario management and default apps, and they embed sample pages, configuration, and requirements so new projects align with the platform’s architecture.

13. The repository’s build and release machinery is substantial and architecture-relevant. `tools/packages` defines per-package packaging scripts, `tools/release` manages versioning and release artifacts, and `.github/workflows` contains CI for tests, packaging, frontend builds, and release publication. This indicates the repo is designed as a coordinated multi-package distribution, not a single library.

14. The test tree mirrors the subsystem boundaries closely: separate suites exist for common, core, gui, rest, templates, and frontend packages. That usually means the public architecture is intentionally modular, with clear contracts between shared config, domain orchestration, UI runtime, HTTP API, and scaffold generation.

Main entry points: [`taipy/core`](https://github.com/avaiga/taipy/tree/develop/taipy/core) (Core domain), [`taipy`](https://github.com/avaiga/taipy/tree/develop/taipy) (taipy), [`taipy/gui`](https://github.com/avaiga/taipy/tree/develop/taipy/gui) (GUI backend), [`taipy/common`](https://github.com/avaiga/taipy/tree/develop/taipy/common) (Common)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_platform["Platform"]
  node_taipy_pkg["taipy<br/>umbrella package"]
  node_entrypoint["Entrypoint<br/>runtime bootstrap<br/>[_entrypoint.py]"]
  node_common["Common<br/>shared foundation"]
end

subgraph group_core["Core"]
  node_core_domain["Core domain<br/>workflow engine"]
  node_core_access["Access layer<br/>manager/repository layer"]
  node_core_storage["Storage adapters<br/>data backends"]
  node_core_orch["Orchestration<br/>job runner"]
  node_core_version["Versioning<br/>migration layer"]
  node_core_events["Events<br/>pub/sub"]
  node_core_config["Core config<br/>domain config"]
end

subgraph group_gui["GUI"]
  node_gui_python["GUI backend<br/>Python UI runtime"]
  node_gui_render["Renderers<br/>page compiler"]
  node_gui_state["State/data<br/>binding runtime"]
  node_gui_server["Server"]
  node_gui_frontend["GUI frontend<br/>React components"]
  node_ops_frontend["Ops frontend<br/>diagram UI"]
end

subgraph group_rest["REST"]
  node_rest_api["REST API<br/>HTTP service"]
end

subgraph group_templates["Templates"]
  node_templates_pkg["Templates<br/>scaffolding"]
end

subgraph group_build["Build"]
  node_build_release["Build & release<br/>distribution tooling"]
end

node_taipy_pkg -->|"bundles"| node_common
node_taipy_pkg -->|"bundles"| node_core_domain
node_taipy_pkg -->|"bundles"| node_gui_python
node_taipy_pkg -->|"bundles"| node_rest_api
node_taipy_pkg -->|"bundles"| node_templates_pkg
node_entrypoint -->|"uses"| node_common
node_core_config -->|"inherits"| node_common
node_core_domain -->|"coordinates"| node_core_access
node_core_access -->|"persists"| node_core_storage
node_core_domain -->|"submits"| node_core_orch
node_core_orch -->|"publishes"| node_core_events
node_core_domain -->|"migrates"| node_core_version
node_core_version -->|"wraps"| node_core_access
node_core_events -->|"adopts"| node_common
node_gui_python -->|"adopts"| node_common
node_gui_python -->|"compiles"| node_gui_render
node_gui_python -->|"binds"| node_gui_state
node_gui_python -->|"serves"| node_gui_server
node_gui_server -->|"syncs"| node_gui_frontend
node_gui_state -->|"feeds"| node_gui_frontend
node_ops_frontend -->|"visualizes"| node_core_domain
node_rest_api -->|"exposes"| node_core_domain
node_rest_api -->|"adopts"| node_common
node_templates_pkg -->|"scaffolds"| node_gui_python
node_templates_pkg -->|"scaffolds"| node_core_domain
node_build_release -->|"packages"| node_taipy_pkg
node_build_release -->|"builds"| node_gui_frontend
node_build_release -->|"publishes"| node_rest_api

click node_taipy_pkg "https://github.com/avaiga/taipy/tree/develop/taipy"
click node_entrypoint "https://github.com/avaiga/taipy/blob/develop/taipy/_entrypoint.py"
click node_common "https://github.com/avaiga/taipy/tree/develop/taipy/common"
click node_core_domain "https://github.com/avaiga/taipy/tree/develop/taipy/core"
click node_core_access "https://github.com/avaiga/taipy/tree/develop/taipy/core/_manager"
click node_core_storage "https://github.com/avaiga/taipy/tree/develop/taipy/core/data"
click node_core_orch "https://github.com/avaiga/taipy/tree/develop/taipy/core/_orchestrator"
click node_core_version "https://github.com/avaiga/taipy/tree/develop/taipy/core/_version"
click node_core_events "https://github.com/avaiga/taipy/tree/develop/taipy/core/notification"
click node_core_config "https://github.com/avaiga/taipy/tree/develop/taipy/core/config"
click node_gui_python "https://github.com/avaiga/taipy/tree/develop/taipy/gui"
click node_gui_render "https://github.com/avaiga/taipy/tree/develop/taipy/gui/_renderers"
click node_gui_state "https://github.com/avaiga/taipy/tree/develop/taipy/gui/data"
click node_gui_server "https://github.com/avaiga/taipy/tree/develop/taipy/gui/servers"
click node_gui_frontend "https://github.com/avaiga/taipy/tree/develop/frontend/taipy-gui"
click node_ops_frontend "https://github.com/avaiga/taipy/tree/develop/frontend/taipy"
click node_rest_api "https://github.com/avaiga/taipy/tree/develop/taipy/rest"
click node_templates_pkg "https://github.com/avaiga/taipy/tree/develop/taipy/templates"
click node_build_release "https://github.com/avaiga/taipy/tree/develop/tools/packages"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_taipy_pkg,node_entrypoint,node_common toneBlue
class node_core_domain,node_core_access,node_core_storage,node_core_orch,node_core_version,node_core_events,node_core_config toneAmber
class node_gui_python,node_gui_render,node_gui_state,node_gui_server,node_gui_frontend,node_ops_frontend toneMint
class node_rest_api toneRose
class node_templates_pkg toneIndigo
class node_build_release toneTeal
```

## Components

### Platform

Top-level Taipy distribution and shared runtime entry points.

- [taipy](https://github.com/avaiga/taipy/tree/develop/taipy): umbrella package · Top-level developer entry point that bundles the Taipy subpackages. · `taipy`
- [Entrypoint](https://github.com/avaiga/taipy/blob/develop/taipy/_entrypoint.py): runtime bootstrap · CLI/runtime launch wiring for the umbrella package. · `taipy/_entrypoint.py`
- [Common](https://github.com/avaiga/taipy/tree/develop/taipy/common): shared foundation · Shared CLI, config, serialization, logging, versioning, and validation conventions. · `taipy/common`

### Core

Domain engine, persistence, orchestration, versioning, and events.

- [Core domain](https://github.com/avaiga/taipy/tree/develop/taipy/core): workflow engine · Models scenarios, sequences, tasks, jobs, cycles, submissions, and data nodes. · `taipy/core`
- [Access layer](https://github.com/avaiga/taipy/tree/develop/taipy/core/_manager): manager/repository layer · Manager and repository abstractions that coordinate domain access and persistence. · `taipy/core/_manager`
- [Storage adapters](https://github.com/avaiga/taipy/tree/develop/taipy/core/data): data backends · Concrete data node implementations for file, in-memory, tabular, SQL, MongoDB, and S3-backed storage. · `taipy/core/data`
- [Orchestration](https://github.com/avaiga/taipy/tree/develop/taipy/core/_orchestrator): job runner · Dispatcher and orchestrator components that submit, route, and execute jobs. · `taipy/core/_orchestrator`
- [Versioning](https://github.com/avaiga/taipy/tree/develop/taipy/core/_version): migration layer · Versioned persistence, compatibility handling, and repository migration support. · `taipy/core/_version`
- [Events](https://github.com/avaiga/taipy/tree/develop/taipy/core/notification): pub/sub · Notification and topic system used to propagate domain state changes. · `taipy/core/notification`
- [Core config](https://github.com/avaiga/taipy/tree/develop/taipy/core/config): domain config · Configuration models and validation for core entities and runtime behavior. · `taipy/core/config`

### GUI

Python GUI runtime plus browser-facing components.

- [GUI backend](https://github.com/avaiga/taipy/tree/develop/taipy/gui): Python UI runtime · Page/model building, renderers, state, data access, and server integration on the Python side. · `taipy/gui`
- [Renderers](https://github.com/avaiga/taipy/tree/develop/taipy/gui/_renderers): page compiler · Markdown and HTML renderers plus builder utilities that turn user pages into renderable structures. · `taipy/gui/_renderers`
- [State/data](https://github.com/avaiga/taipy/tree/develop/taipy/gui/data): binding runtime · State handling, bindings, accessors, and normalization of Python-side data for UI synchronization. · `taipy/gui/data`
- [Server](https://github.com/avaiga/taipy/tree/develop/taipy/gui/servers): web server · Flask-based request handling and app exposure for the GUI runtime. · `taipy/gui/servers`
- [GUI frontend](https://github.com/avaiga/taipy/tree/develop/frontend/taipy-gui): React components · Browser component library for Taipy controls, pages, themes, context, and workers. · `frontend/taipy-gui`
- [Ops frontend](https://github.com/avaiga/taipy/tree/develop/frontend/taipy): diagram UI · React/TypeScript package for visualizing and editing core entities such as scenarios, jobs, and data nodes. · `frontend/taipy`

### REST

HTTP API layer over core domain models.

- [REST API](https://github.com/avaiga/taipy/tree/develop/taipy/rest): HTTP service · Flask resources, schemas, middleware, and docs exposing core models over HTTP. · `taipy/rest`

### Templates

Project scaffolding and starter app templates.

- [Templates](https://github.com/avaiga/taipy/tree/develop/taipy/templates): scaffolding · Cookiecutter-style starter projects and project generators. · `taipy/templates`

### Build

Packaging, release, and CI coordination.

- [Build & release](https://github.com/avaiga/taipy/tree/develop/tools/packages): distribution tooling · Package setup, release automation, frontend builds, and CI workflows. · `tools/packages`

## Connections

- taipy → Common: bundles · Umbrella distribution includes the shared foundation.
- taipy → Core domain: bundles · Umbrella distribution includes the core engine.
- taipy → GUI backend: bundles · Umbrella distribution includes the GUI runtime.
- taipy → REST API: bundles · Umbrella distribution includes the REST service layer.
- taipy → Templates: bundles · Umbrella distribution includes project templates.
- Entrypoint → Common: uses · Entry startup relies on shared CLI and config plumbing.
- Core config → Common: inherits · Core configuration builds on shared config conventions.
- Core domain → Access layer: coordinates · Domain entities are coordinated through managers and repositories.
- Access layer → Storage adapters: persists · Repository layer is backed by multiple storage adapters.
- Core domain → Orchestration: submits · Core workflow entities are executed through orchestration.
- Orchestration → Events: publishes · Job and state transitions are emitted as events.
- Core domain → Versioning: migrates · Persisted entities flow through versioned state and migration support.
- Versioning → Access layer: wraps · Versioned repositories sit around core persistence boundaries.
- Events → Common: adopts · Event models and utilities follow shared conventions.
- GUI backend → Common: adopts · GUI runtime uses shared CLI/config and common utilities.
- GUI backend → Renderers: compiles · Pages and controls are turned into renderable UI structures.
- GUI backend → State/data: binds · Python state and data bindings drive the UI model.
- GUI backend → Server: serves · Backend runtime exposes the application through a web server.
- Server → GUI frontend: syncs · Server exchanges state, actions, and websocket updates with the browser UI.
- State/data → GUI frontend: feeds · State and data accessors normalize content for front-end components.
- Ops frontend → Core domain: visualizes · Operational views render core scenarios, jobs, and data nodes.
- REST API → Core domain: exposes · HTTP resources expose the same core workflow models.
- REST API → Common: adopts · REST configuration and helpers build on shared conventions.
- Templates → GUI backend: scaffolds · Starter projects create GUI-oriented apps and pages.
- Templates → Core domain: scaffolds · Starter projects include core-oriented scenario and algorithm structure.
- Build & release → taipy: packages · Release tooling assembles the umbrella distribution.
- Build & release → GUI frontend: builds · Frontend assets are built as part of packaging and CI.
- Build & release → REST API: publishes · Release automation covers the REST package and service artifacts.
