microtables/CLAUDE.md

Microtables - LLM Navigation Guide

Project Overview

A lightweight spreadsheet application designed for quick calculations — positioned between a calculator and a full office suite. The goal is fast loading with support for common spreadsheet operations.

Architecture

Frontend (/frontend/)

• Language: ClojureScript (compiled via shadow-cljs)
• Framework: Reagent + re-frame (React wrapper)
• Build: shadow-cljs (via npm scripts)
• Dev server: npm run dev → localhost:8280

Server (/server/)

• Language: JavaScript (ES6+ with Babel)
• Framework: Express
• Status: Minimal implementation - currently the frontend is fully functional standalone
• Future: Will handle persistence and collaboration

Key Concepts

Data Structure

The spreadsheet data is a nested map: {column-letter {row-number {:value ...}}}

Example:

{"A" {1 {:value 78 :inbound [...]}
      3 {:value "=B2 * 4" :refs [...]}}
 "B" {2 {:value "=A1 + 3" :refs [...] :inbound [...]}}}

Formula System

• Formulae start with = and are evaluated using math.js library
• Range syntax supported: =sum(A1:A10)
• Cell references create a doubly-linked tree structure:
  • :refs - forward references (cells this formula depends on)
  • :inbound - back references (cells that depend on this cell)
  • :display - computed/evaluated value shown to user
  • :value - raw user input
  • :dirty - flag indicating re-evaluation needed

Evaluation Flow

1. When a cell changes, parse for references
2. Update forward (:refs) and back (:inbound) reference trees
3. Evaluate the cell
4. Recursively evaluate all cells in :inbound queue
5. Cycle detection prevents infinite loops

Important Files

Frontend Core Logic

• frontend/src/cljs/microtables_frontend/core.cljs - App initialization
• frontend/src/cljs/microtables_frontend/db.cljs - Data model definition
• frontend/src/cljs/microtables_frontend/events.cljs - State mutations (re-frame)
• frontend/src/cljs/microtables_frontend/subs.cljs - Data queries (re-frame)
• frontend/src/cljs/microtables_frontend/evaluation.cljs - Formula evaluation engine
• frontend/src/cljs/microtables_frontend/views/sheet.cljs - Grid rendering

Project Configuration

• frontend/shadow-cljs.edn - ClojureScript build config (source paths, deps, build targets)
• frontend/package.json - npm scripts and JS dependencies

Development Notes

• there is a todo.md file which contains some desired changes
• Almost everything is subject to change (architecture, structure, design)
• The frontend currently operates completely standalone
• Focus is on simplicity and performance for common use cases
• Data structures prioritize clarity over micro-optimization (small dataset assumption)

Common Tasks

Run frontend: cd frontend && npm run dev Install npm dependency: Add to shadow-cljs.edn, then restart Understand formula eval: Start in evaluation.cljs, trace through evaluate-from-cell Modify grid UI: Look in views/sheet.cljs