Developer Documentation (Web App Architecture)#

This section is a developer-facing map of how the Cellucid web app works: where the important code lives, how state flows through the system, and how to debug/extend features without breaking performance.

It lives in the cellucid-python docs because most developers arrive from the Python side, but the frontend code is in the cellucid/ repo.

Important

If you are a wet-lab user or a general “how do I use the UI?” reader, this section is not the right starting point. Start with the web app user guide landing page: Web App Guide.

Fast Path (Pick Your Goal)#

You want to…	Start here	Then read
Run the app locally and reproduce a bug	Local development setup	Debugging playbook
Understand the big-picture architecture	App architecture overview	State (DataState) and events → Rendering pipeline (WebGL) and performance notes
Learn where the code lives (file map + entry points)	Codebase map and entry points	UI modules map
Add a new sidebar feature/module	Extension point: add a UI module	Extension points overview
Add/extend analysis (plots, compute, UI modes)	Analysis architecture	Extension point: add an analysis mode
Add or change an action, a piece of state, undo/redo or the history	Action layer, state domains and history	Sessions: persistence and serialization → Extension point: add a UI module
Work on sessions (share/load)	Sessions: persistence and serialization	Action layer, state domains and history → Debugging playbook
Work on agents (chat bar, permissions, data guard, the relay, `cellucid mcp`)	Agents in the tab: chat bar, permissions, data guard and relay	Local agent connection (cellucid mcp) → Action reference
Work on figure export	Figure export architecture	Extension point: add an export renderer
Understand loading sources (local/remote/GitHub/Jupyter)	Data loading pipeline and caching	Data Loading in the Web App (All Paths) (user-facing view)
Change how data is read, priced, kept or drawn (bytes, link, share, gene sample)	Read path architecture	Subsampling specification → Data loading pipeline and caching
Find out why a subsystem is built the way it is (decisions, measurements, what was reverted)	the decision records Decision record: decoders and codecs … Decision record: rendering layers, the gene-sample look and levels of detail	Read path architecture

What This Section Covers#

Codebase map: how cellucid/index.html boots the app and which folders correspond to state, UI, rendering, and data loading.
State model: DataState, events, per-view contexts, multi-page highlights, caches, and batch updates.
Rendering pipeline: the WebGL viewer, buffers, LOD, overlays (smoke + velocity), and performance footguns.
Actions, state domains and the history: the one action catalogue every control, agent and Python or R host dispatches, the fifteen state domains, the history’s trackers, undo, branches and autosave, and how the catalogue reaches Python, R and agents.
Persistence: the one current .cellucid-session format (session format 4: the history in one file, or the state only, or the steps only), its all-or-nothing load beside the person’s trackers, starting views, dataset-identity rejection, and My datasets’ .cellucid-library file.
Agents: one tool call for the chat bar, Claude and ChatGPT through the relay, and local apps through cellucid mcp; the person’s permissions and confirm cards; what agents are sent of the data; the generated action reference.
Debugging: how to capture minimal repro steps + the exact logs that help fix issues quickly.
Extension points: the safe, repeatable steps for adding a UI module, an action, a piece of state, an analysis mode, or an export renderer.

Note

Privacy/security and telemetry live in a separate user-facing section: Accessibility, Privacy, and Security. This developer section links to it, but does not replace it.

Two things there that contributors get wrong often enough to flag here: the app does ship Google Analytics, gated on three production hostnames and inert everywhere else; and two of the browser caches persist dataset-derived content, not preferences. If you add persistence or egress, that page has to change in the same commit.

Important

This section has no screenshots, on purpose. Every page here documents code structure, data flow and invariants — things a picture of the interface cannot show and that a picture would misdate on the next CSS change. Where structure is genuinely hard to hold in the head, these pages use ASCII diagrams instead: they live in the same file as the prose they explain, they diff, and they cannot drift from the text around them. If you find a page here where a real screenshot would help, it probably belongs in the user guide rather than in this section.