How fulcrologic/fulcro works
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