Clarity

Clarity is a browser-based editor for structured thinking diagrams. It is designed around Theory of Constraints style cause-and-effect work rather than generic whiteboarding.

Today the app supports:

• Current Reality Tree (CRT)
• Future Reality Tree (FRT)
• Goal Tree
• Prerequisite Tree (PRT)
• Success Tree
• Strategy & Tactics Tree (STT)
• Value Stream Map
• Causal Loop Diagram (CLD)
• AI-assisted diagram analysis and modification through a configurable OpenAI-compatible endpoint
• .json project save/load, plus in-session autosave
• Auto-layout, undo/redo, edge confidence, notes, and framework-specific tags

Why Clarity

Clarity's core model is intentionally narrow:

• Diagrams are directed graphs with framework-specific semantics
• Nodes share a common base shape and are enriched by tags, notes, and derived indicators
• The editor enforces DAG-style validity for current frameworks: no self-loops, no duplicate edges, no cycles

That constraint is a feature. It keeps the product focused on structured reasoning instead of drifting into a generic diagram tool.

Supported Frameworks

Current Reality Tree

Use CRT to trace undesirable effects back to root causes.

• Edge semantics: causes
• Tags: Undesirable Effect
• Derived indicators: Root Cause, Intermediate Effect

Future Reality Tree

Use FRT to test whether proposed injections lead to desirable effects.

• Edge semantics: leads to
• Tags: Injection, Desirable Effect
• Derived indicators: Foundation, Intermediate Effect

Success Tree

Use Success Tree to explain how multiple factors contributed to a positive outcome.

• Edge semantics: contributed to
• Tags: Success Factor, Achievement
• Derived indicators: Foundation, Contributor, Outcome

Goal Tree

Use Goal Tree to break a desired outcome into supporting conditions, sub-goals, and concrete actions.

• Edge semantics: supports
• Tags: Goal, Necessary Condition, Action
• Derived indicators: Foundation, Bridge, Target Goal

Value Stream Map

Use Value Stream Map to trace how work moves through a delivery flow, where it waits, and where waste or constraints appear.

• Edge semantics: flows to
• Tags: Process, Queue, Inspection, Handoff, Customer Value, Waste, Constraint
• Derived indicators: Start, Intermediate Step, End

Recommended Next Frameworks

The strongest near-term additions are frameworks that fit the current engine without turning Clarity into a generic diagrammer.

1. Evaporating Cloud (EC)
2. Transition Tree

Frameworks to defer for now:

• Generic Causal Loop Diagrams: require cycle support, which conflicts with the current validator
• General UML/ERD/sequence diagrams: different product category, weak fit with the current engine

Tech Stack

• React 19
• TypeScript
• Vite
• React Flow (@xyflow/react)
• Zustand
• ELK (elkjs) for primary auto-layout
• ELK variants and Graphology ForceAtlas2 available for layout benchmarking
• Tailwind CSS v4 plus project CSS

Local Development

npm install
npm run dev

Useful checks:

npm run build
npm run lint
npx tsc --noEmit
npx vitest run

Firebase Error Logging

Clarity can forward uncaught browser errors and React crash boundary failures to Firebase Analytics as exception events and persist them to Firestore with the current app version attached.

Add these Vite env vars before running the app:

VITE_FIREBASE_API_KEY=...
VITE_FIREBASE_AUTH_DOMAIN=...
VITE_FIREBASE_PROJECT_ID=...
VITE_FIREBASE_APP_ID=...
VITE_FIREBASE_STORAGE_BUCKET=...
VITE_FIREBASE_MESSAGING_SENDER_ID=...
VITE_FIREBASE_MEASUREMENT_ID=...

If the Firebase config is missing, the logger stays disabled and the app behaves normally.

Persistence Model

• Session autosave uses sessionStorage
• App settings such as API key, model, and base URL use localStorage
• Explicit project save/load uses .json files

AI Integration

Clarity can analyze and modify the current diagram through the side-panel chat.

• Configure API key, model, and endpoint from the toolbar settings popover
• OpenAI-compatible endpoints are supported
• The assistant can answer questions about the current diagram and apply batched node/edge edits

Project Status

The app is already beyond the original CRT-only concept. The next product question is not whether Clarity should support more diagram types in general, but which additional thinking frameworks deepen the existing workflow without breaking its constraints.