Przeglądaj źródła

docs: add CLAUDE.md guide for LLM navigation

take a look at this project, and generate a suitable "AGENTS.md" or "CLAUDE.md"-style file that would help guide a future LLM in navigating the repo. keep it relatively short, and don't be too specific, as almost everything about the project (architecture, structure, design choices, etc) is subject to change. output markdown code.

```git-revs
77ec857  (Base revision)
HEAD     Create CLAUDE.md guide for LLM navigation of the repository
```

codemcp-id: 1-docs-add-claude-md-guide-for-llm-navigation
Brandon Wong 2 miesięcy temu
rodzic
commit
f0e1069fbb
1 zmienionych plików z 75 dodań i 0 usunięć
  1. 75 0
      CLAUDE.md

+ 75 - 0
CLAUDE.md

@@ -0,0 +1,75 @@
+# 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**: Leiningen + shadow-cljs
+- **Dev server**: `lein 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:
+```clojure
+{"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/project.clj` - Leiningen config
+- `frontend/shadow-cljs.edn` - ClojureScript build config
+
+## Development Notes
+
+- 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 && lein 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`