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

Work on sessions (save/load)

Sessions: persistence and serialization

Debugging playbook

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)

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.

  • Persistence: the .cellucid-session bundle format, what is saved/restored, and dataset mismatch behavior.

  • 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 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.