# pydantic/fastui architecture

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

- Interactive diagram: https://gitdiagram.com/pydantic/fastui
- Repository: https://github.com/pydantic/fastui

## Overview

##### Main Components
- Backend Services:
- The Python “fastui” package (in src/python-fastui) contains the core Pydantic models, component definitions, and REST endpoints. This is used by FastAPI-based applications (as seen in the demo) to deliver UI components in response to HTTP requests.
- The demo folder provides an example FastAPI application that shows how the backend delivers UI by mapping endpoints to the UI components.
- Frontend Packages:
- The React-based components and libraries are provided in multiple npm packages located under src/npm-fastui, src/npm-fastui-bootstrap, and src/npm-fastui-prebuilt.
- “@pydantic/fastui” is the generic TypeScript package that corresponds to the Python interface models.
- “@pydantic/fastui-bootstrap” offers a Bootstrap-themed implementation of FastUI components.
- “@pydantic/fastui-prebuilt” supplies a compiled/prebuilt version of the frontend so that users can deploy the UI without having to build it themselves.
- Documentation & Build Infrastructure:
- The docs folder (with MkDocs configuration in mkdocs.yml) and associated scripts (like build-docs.sh, bump_npm.py) support documentation generation.
- Configuration files (e.g., for ESLint, Prettier, TypeScript, GitHub workflows) indicate that code quality, automated builds, and testing are integrated into the project.

##### Relationships and Data Flow
- The Backend (Python/FastAPI) exposes HTTP endpoints (such as /api/ and /api/user/{user_id}/) to return FastUI component definitions.
- The Frontend (React) requests these endpoints, receives a JSON representation conforming to the Pydantic models, and then renders the corresponding React components.
- There is a clear separation of concerns: the “backend” is solely responsible for defining the UI and business logic, while the “frontend” serves as a reusable rendering engine (utilizing the prebuilt or customizable npm packages).
- The project also ensures type safety and schema matching between the two sides via TypeScript interfaces, JSON Schema, and Pydantic.

##### Architectural Patterns and Design Principles
- Component-Based Architecture: Both frontend and backend are built around discrete, self-contained components. In the frontend, these are the React components (for instance, Table, Modal, Navbar, etc.). In the backend, corresponding component models are defined using Pydantic.
- RESTful Communication: The backend provides endpoints that return a series of UI components. This strategy decouples the UI definition from the actual rendering (the “puppet and hand” metaphor used in the README).
- Separation of Concerns: The design clearly splits responsibilities between UI definition (Python) and UI implementation (React/TypeScript).
- Type Safety: Extensive use of typing through Pydantic’s models and TypeScript’s interfaces/compilation safeguards alignment between frontend and backend.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Backend Layer
    subgraph "Backend (Python)"
        FastAPI["FastAPI Endpoints (/api/)"]:::backend
        Core["FastUI Core (Python/Pydantic)"]:::backend
        Demo["Demo Application (FastAPI Example)"]:::backend
    end

    %% Frontend Layer
    subgraph "Frontend (React/TypeScript)"
        CoreComponents["@pydantic/fastui (Core Components)"]:::frontend
        BootstrapComponents["@pydantic/fastui-bootstrap (Bootstrap UI)"]:::frontend
        Prebuilt["@pydantic/fastui-prebuilt (Prebuilt React App)"]:::frontend
    end

    %% Documentation & Build Infrastructure
    subgraph "Documentation & Build"
        Docs["Documentation (MkDocs)"]:::docs
        Config["Configuration & Scripts (ESLint, Prettier, etc)"]:::docs
        BuildDocs["build-docs.sh"]:::docs
        BumpNpm["bump_npm.py"]:::docs
    end

    %% Communication Flow: HTTP Requests/Responses
    Client["Client HTTP Requests"]:::client

    Client -->|"requests_JSON"| FastAPI
    FastAPI -->|"returns_JSON_with_UI_schema"| Client

    %% Internal Backend Relationships
    Core -->|"defines_UI_models"| FastAPI
    Demo -->|"integrates_with"| FastAPI
    Demo -->|"demonstrates_usage_of"| Core

    %% Frontend Rendering Relationships
    CoreComponents -->|"renders_UI"| Client
    BootstrapComponents -->|"renders_UI_with_Bootstrap"| Client
    Prebuilt -->|"serves_ready_UI"| Client

    %% Click Events for Component Mapping
    click Core "https://github.com/pydantic/fastui/tree/main/src/python-fastui/fastui"
    click Demo "https://github.com/pydantic/fastui/tree/main/demo"
    click CoreComponents "https://github.com/pydantic/fastui/tree/main/src/npm-fastui"
    click BootstrapComponents "https://github.com/pydantic/fastui/tree/main/src/npm-fastui-bootstrap"
    click Prebuilt "https://github.com/pydantic/fastui/tree/main/src/npm-fastui-prebuilt"
    click Docs "https://github.com/pydantic/fastui/tree/main/docs"
    click Config "https://github.com/pydantic/fastui/blob/main/mkdocs.yml"
    click BuildDocs "https://github.com/pydantic/fastui/blob/main/build-docs.sh"
    click BumpNpm "https://github.com/pydantic/fastui/blob/main/bump_npm.py"

    %% Styles
    classDef backend fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef frontend fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef docs fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef client fill:#FFA07A,stroke:#333,stroke-width:2px;
```
