# totaljs/flow architecture

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

- Interactive diagram: https://gitdiagram.com/totaljs/flow
- Repository: https://github.com/totaljs/flow

## Overview

##### Main Components
- Core Server: The entry point is index.js. This is where the application is started and where the central routing/control is initiated.
- Controllers: These (found in the “controllers” directory) handle incoming HTTP requests – for example, api.js and default.js.
- Definitions & Schemas: Directories “definitions” and “schemas” contain logic, authentication rules, UI definitions, and data structure definitions crucial to the business logic.
- Plugins & Bundles: The “plugins” directory (with examples such as bookmarks) and “bundles” directories represent the extensibility layer. They provide additional functionalities that can be dynamically loaded.
- Modules: Contains utility or service-like components (e.g., cdn.js, openplatform.js) that could be used across the application.
- Public Assets: The “public” and “views” directories are the frontend elements (HTML, CSS, JavaScript, images) that serve the UI for the end-user.
- Resources: Contains multi-language resources (“resources” folder) to support internationalization.

##### Relationships and Interactions
- The Client (browser) communicates with the server via HTTP. Requests are routed through “controllers”, which call the appropriate “definitions” or “modules”.
- The server uses the “views” for rendered pages or serves static content from “public.”
- Plugins and Bundles act as plug-and-play modules that extend functionality; their public parts might also serve assets, and their schemas define extra data types.
- Configuration elements (Dockerfile, docker-compose.yaml, and GitHub workflows) indicate that the application can be containerized and integrated into a CI/CD pipeline.

##### Architectural Patterns and Design Principles
- Modularity: Notice the clear separation between controllers, definitions, modules, plugins, and bundles. This separation is indicative of a highly modular design to allow for extensibility.
- Full-Stack Integration: There is a clear delineation between the frontend (public assets, views) and backend (server code, controllers) components.
- Plugin Architecture: The presence of a dedicated plugins directory with its own public assets and schemas suggests a design that supports plugins to add or modify functionality.
- Docker & CI/CD: Containerization files and GitHub workflows indicate modern development/deployment practices.

##### Relevant Technology Layers
- Node.js: The core application runs on Node.js, as indicated by index.js and package.json.
- Web Technologies: HTML, CSS, JS assets located under public and views.
- Docker: Both Dockerfile and docker-compose show how the application can be containerized.
- GitHub/CICD: The GitHub workflows signal an automated build/deployment process.

- A section for static and dynamic client-side content (Public Assets and Views).
- Infrastructure layers: Docker configuration and CI/CD integration.
- The flow of HTTP requests from the client to controllers.
- How controllers interact with definitions, modules, and plugins.
- Data flow from definitions/schemas to database layers (if applicable), or back to the views.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client-Side Components
    subgraph "Client-Side"
        Client("Client (Browser)"):::clientStyle
        PublicAssets("Public Assets (public/)"):::viewStyle
        Views("Views (views/)"):::viewStyle
        Resources("Resources (resources/)"):::viewStyle
    end

    %% Server-Side Components
    subgraph "Server-Side"
        CoreServer("Core Server / Index (index.js)"):::serverStyle
        subgraph "Controllers"
            ControllerAPI("Controller: API (controllers/api.js)"):::serverStyle
            ControllerDefault("Controller: Default (controllers/default.js)"):::serverStyle
        end
        Definitions("Definitions (definitions/)"):::serverStyle
        Schemas("Schemas (schemas/)"):::serverStyle
        Modules("Modules (modules/)"):::serverStyle
        subgraph "Plugin Extensions"
            Plugins("Plugins (plugins/)"):::pluginStyle
            Bundles("Bundles (bundles/)"):::pluginStyle
        end
    end

    %% Infrastructure Layer
    subgraph "Infrastructure"
        Infra("Docker & CI/CD Config (Dockerfile, docker-compose.yaml, .github/workflows/)"):::layerStyle
    end

    %% Connections
    Client -->|"HTTP_request"| CoreServer
    CoreServer -->|"routes_to"| ControllerAPI
    CoreServer -->|"routes_to"| ControllerDefault
    ControllerAPI -->|"calls_definitions"| Definitions
    ControllerAPI -->|"calls_modules"| Modules
    ControllerDefault -->|"calls_schemas"| Schemas
    Definitions -->|"supports"| Schemas
    Modules -->|"utilizes"| Schemas
    CoreServer -->|"integrates_plugin"| Plugins
    CoreServer -->|"integrates_bundle"| Bundles
    CoreServer -->|"renders"| Views
    CoreServer -->|"serves_static"| PublicAssets
    CoreServer -->|"provides_i18n"| Resources
    Infra -->|"deploys"| CoreServer
    Views -->|"delivers_HTML_to"| Client
    PublicAssets -->|"serves_assets_to"| Client

    %% Click Events
    click CoreServer "https://github.com/totaljs/flow/blob/master/index.js"
    click ControllerAPI "https://github.com/totaljs/flow/blob/master/controllers/api.js"
    click ControllerDefault "https://github.com/totaljs/flow/blob/master/controllers/default.js"
    click Definitions "https://github.com/totaljs/flow/tree/master/definitions/"
    click Schemas "https://github.com/totaljs/flow/tree/master/schemas/"
    click Modules "https://github.com/totaljs/flow/tree/master/modules/"
    click Plugins "https://github.com/totaljs/flow/tree/master/plugins/"
    click Bundles "https://github.com/totaljs/flow/tree/master/bundles/"
    click PublicAssets "https://github.com/totaljs/flow/tree/master/public/"
    click Views "https://github.com/totaljs/flow/tree/master/views/"
    click Resources "https://github.com/totaljs/flow/tree/master/resources/"
    click Infra "https://github.com/totaljs/flow/tree/master/Dockerfile"

    %% Styles
    classDef clientStyle fill:#ccffcc,stroke:#008000,stroke-width:2px;
    classDef viewStyle fill:#f0e68c,stroke:#daa520,stroke-width:2px;
    classDef serverStyle fill:#cce5ff,stroke:#0056b3,stroke-width:2px;
    classDef pluginStyle fill:#ffcc99,stroke:#cc6600,stroke-width:2px;
    classDef layerStyle fill:#e6e6e6,stroke:#7a7a7a,stroke-width:2px;

    class Client clientStyle;
    class PublicAssets,Views,Resources viewStyle;
    class CoreServer,ControllerAPI,ControllerDefault,Definitions,Schemas,Modules serverStyle;
    class Plugins,Bundles pluginStyle;
    class Infra layerStyle;
```
