# fulcrologic/fulcro architecture

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

- Interactive diagram: https://gitdiagram.com/fulcrologic/fulcro
- Repository: https://github.com/fulcrologic/fulcro

## Overview

##### Project Type & Purpose
- Fulcro is an open-source library for building data-driven full-stack apps in Clojure/ClojureScript, leveraging React on the client and optionally Clojure on the server.
- It ships core algorithms, networking, UI abstractions, offline support, Inspect tooling, plus documentation and demo apps.

##### File Structure
Top-level directories & files:
- src/main/com/fulcrologic/fulcro – the core library code (algorithms, components, networking, offline, routing, server middleware).
- src/test – unit and integration tests for core modules.
- src/todomvc & src/workspaces – example/demo applications showcasing usage.
- docs & resources/public – static site and assets for documentation and demos.
- build.clj, deps.edn, shadow-cljs.edn, package.json, pom.xml, Makefile – build/configuration pipelines for Clojure, ClojureScript, npm, docs generator, CI.

##### Key Insights from README
- Fulcro provides:
– Client-side state management and React integration
– Data‐fetching abstractions over HTTP or WebSocket
– Offline persistence strategies
– Server‐side API middleware for Clojure
– Dev tooling (Fulcro Inspect)
- It’s not a single application but a library plus demos and documentation.

##### Main Components & Their Relationships
A. Developer & Build Tooling
– CLI: deps.edn (Clojure), shadow-cljs (ClojureScript bundling), npm (JS deps), Make/CircleCI.
– Documentation pipeline: Asciidoctor/Jekyll site under docs/.

B. Fulcro Core Library
1. Algorithms Module
- Normalization/denormalization, scheduling, tempid, indexing, form-state, server-render.
2. UI/Component Module
- defsc, component queries, rendering strategies, React context/hooks/error boundaries.
3. Networking Module
- HTTP remote, WebSocket support, file-upload, mock and tenacious remotes.
4. Offline Module
- Durable EDN store, browser store, write-through mutations.
5. Routing Module
- Dynamic and legacy UI routers.
6. Server Module
- API middleware, config, Transit support.

C. DevTooling: Fulcro Inspect
– Websocket/Electron preload scripts and client API.
– Integrated via inspect.client.cljc, tools, transit.

D. Demo Apps & Workspaces
– TodoMVC (full-stack client + server + WS).
– Workspaces (cards showcasing features).

E. External Systems
– Browser/JS runtime (React)
– Clojure runtime (JVM/Node for server)
– HTTP / WebSocket backends
– Transitive deps: React, shadow-cljs, Figwheel, NPM packages

##### Architectural Patterns & Principles
- Data normalization and single source of truth in client state
- Declarative component queries driving data fetching
- Pluggable networking backends (HTTP/WebSocket)
- Offline first with durable caches
- React-centric rendering pipelines with optimized re-render strategies
- Server middleware layered over Ring for Clojure integration

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Developer / Build Tools
    subgraph "Developer & Build Tools"
        direction TB
        BuildCLJ["build.clj"]:::tools
        DepsEDN["deps.edn"]:::tools
        ShadowCLJS["shadow-cljs.edn"]:::tools
        PackageJSON["package.json"]:::tools
        MakefileNode["Makefile"]:::tools
        CircleCI[".circleci/config.yml"]:::tools
        Docs["docs/"]:::tools
    end

    %% Fulcro Core Library
    subgraph "Fulcro Core Library"
        direction TB
        subgraph "Algorithms Module" 
            direction TB
            AlgDir["algorithms/"]:::library
        end
        subgraph "UI/Component Module"
            direction TB
            UIComp["components.cljc"]:::library
            UIRaw["raw/"]:::library
            UIReact["react/"]:::library
            UIRend["rendering/"]:::library
        end
        subgraph "Networking Module"
            direction TB
            NetDir["networking/"]:::library
        end
        subgraph "Offline Module"
            direction TB
            OfflineDir["offline/"]:::library
        end
        subgraph "Routing Module"
            direction TB
            RoutingDir["routing/"]:::library
        end
        subgraph "Server Module"
            direction TB
            ServerDir["server/"]:::library
        end
    end

    %% DevTooling: Fulcro Inspect
    subgraph "DevTooling (Fulcro Inspect)"
        direction TB
        InspectDir["inspect/"]:::devtools
    end

    %% Demo Apps & Workspaces
    subgraph "Demo Apps & Workspaces"
        direction TB
        TodoMVC["TodoMVC App"]:::demo
        Workspaces["Workspaces"]:::demo
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        Browser["Browser / React"]:::external
        ClojureRuntime["Clojure / JVM / Node"]:::external
        HTTPServices["HTTP / WebSocket Services"]:::external
        DB["External DB"]:::external
        BrowserStore["Browser Storage"]:::external
    end

    %% Connections
    BuildCLJ -->|"build & deps"| AlgDir
    DepsEDN -->|"build & deps"| UIComp
    ShadowCLJS -->|"bundling"| UIRaw
    PackageJSON -->|"js deps"| UIReact
    MakefileNode -->|"CI tasks"| Docs
    CircleCI -->|"CI pipeline"| Docs

    %% Build to Core & Tools & Demos
    BuildCLJ -->|"builds"| AlgDir
    BuildCLJ -->|"builds"| InspectDir
    BuildCLJ -->|"builds"| TodoMVC
    BuildCLJ -->|"builds"| Workspaces

    %% Core Library internal flows
    UIComp -->|"renders"| Browser
    UIRaw -->|"hooks|contexts"| Browser
    UIRend -->|"render strategies"| Browser
    AlgDir -->|"normalization"| UIComp
    UIComp -->|"queries|mutations"| NetDir
    NetDir -->|"fetch"| HTTPServices
    NetDir -->|"ws"| HTTPServices
    OfflineDir -->|"cache"| BrowserStore
    RoutingDir -->|"routes"| UIComp
    ServerDir -->|"middleware"| ClojureRuntime
    ServerDir -->|"db ops"| DB

    %% Fulcro Inspect integration
    InspectDir -->|"ws debug"| Browser
    InspectDir -->|"api"| UIComp

    %% Demos consume Core
    TodoMVC -->|"uses"| UIComp
    TodoMVC -->|"uses"| NetDir
    Workspaces -->|"showcases"| UIComp

    %% Classes
    classDef library fill:#bbdefb,stroke:#1e88e5,color:#0d47a1
    classDef tools fill:#eeeeee,stroke:#9e9e9e,color:#424242
    classDef external fill:#c8e6c9,stroke:#43a047,color:#1b5e20
    classDef demo fill:#ffe0b2,stroke:#fb8c00,color:#e65100
    classDef devtools fill:#e1bee7,stroke:#8e24aa,color:#4a148c

    %% Click Events
    click BuildCLJ "https://github.com/fulcrologic/fulcro/blob/main/build.clj"
    click DepsEDN "https://github.com/fulcrologic/fulcro/blob/main/deps.edn"
    click ShadowCLJS "https://github.com/fulcrologic/fulcro/blob/main/shadow-cljs.edn"
    click PackageJSON "https://github.com/fulcrologic/fulcro/blob/main/package.json"
    click MakefileNode "https://github.com/fulcrologic/fulcro/tree/main/Makefile"
    click CircleCI "https://github.com/fulcrologic/fulcro/blob/main/.circleci/config.yml"
    click Docs "https://github.com/fulcrologic/fulcro/tree/main/docs/"
    click AlgDir "https://github.com/fulcrologic/fulcro/tree/main/src/main/com/fulcrologic/fulcro/algorithms/"
    click UIComp "https://github.com/fulcrologic/fulcro/blob/main/src/main/com/fulcrologic/fulcro/components.cljc"
    click UIRaw "https://github.com/fulcrologic/fulcro/tree/main/src/main/com/fulcrologic/fulcro/raw/"
    click UIReact "https://github.com/fulcrologic/fulcro/tree/main/src/main/com/fulcrologic/fulcro/react/"
    click UIRend "https://github.com/fulcrologic/fulcro/tree/main/src/main/com/fulcrologic/fulcro/rendering/"
    click NetDir "https://github.com/fulcrologic/fulcro/tree/main/src/main/com/fulcrologic/fulcro/networking/"
    click OfflineDir "https://github.com/fulcrologic/fulcro/tree/main/src/main/com/fulcrologic/fulcro/offline/"
    click RoutingDir "https://github.com/fulcrologic/fulcro/tree/main/src/main/com/fulcrologic/fulcro/routing/"
    click ServerDir "https://github.com/fulcrologic/fulcro/tree/main/src/main/com/fulcrologic/fulcro/server/"
    click InspectDir "https://github.com/fulcrologic/fulcro/tree/main/src/main/com/fulcrologic/fulcro/inspect/"
    click TodoMVC "https://github.com/fulcrologic/fulcro/tree/main/src/todomvc/fulcro_todomvc/"
    click Workspaces "https://github.com/fulcrologic/fulcro/tree/main/src/workspaces/com/fulcrologic/fulcro/cards/"
```
