docs: architecture overview, README refresh, delete V0 cruft#139
Merged
Conversation
paddymul
force-pushed
the
docs/architecture-overview
branch
from
9687afc to
53d9263
Compare
New docs/architecture.md: top-level subsystem map (core/xorq/companion/mcp/cli/frontend), the on-disk catalog layout, core domain concepts, the main data-flow paths, and a currency-annotated index of every existing doc/ADR/plan. README intro now points to it. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Refresh the README to current reality: React SPA served from packages/app/dist (not Jinja), correct /{project}/api/* routes and SSE kinds, global ~/.tallyman-notebooks/buckaroo_sessions.json, stable build-dir expansion, tallyman pack handoff.
Drop references to the orphaned packages/embed bundle from the README and installing.md — the live SPA mounts BuckarooServerView from buckaroo-js-core directly; removal of the package is tracked in a follow-up issue.
Delete plan.md, TICKETS.md, and demo/script.md as stale V0 cruft (predate the SPA migration, result.parquet removal, and JSONL catalog format); architecture.md supersedes them.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
plan.md was deleted in this branch; repoint the three docstrings that cited it (main.py pack, summary_stats.py, io.py) to docs/architecture.md or drop the citation. The io.py docstring also described portability as not-yet-implemented; corrected to reflect the shipped ${TALLYMAN_PROJECT_ROOT} rewriting + tallyman pack.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
… doc Define Server-Sent Events at first use and add a 'Live updates over SSE' concept covering the single EventSource stream, the event kinds the SPA listens for, and the monotonic version counter that drives refetches in place of polling. Grounded in packages/app/src/SSEContext.tsx. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Document every tool Claude Code drives over the tallyman MCP server: all 30 @mcp.tool() endpoints plus the ds_modeling_workflow @mcp.prompt(), grouped by family, each with signature, parameters, return shape, and side effects (checkpoint / SSE notify / auto-recalc). Adds a launch + cross-cutting-behavior section (opt-out checkpointing, _tag_project, best-effort notify, sticky active project) and an at-a-glance side-effect matrix. Surfaces one quirk the audit turned up: catalog_list_display_klasses is missing from _NO_CHECKPOINT, so it commits an empty git revision (checkpoint_catalog uses --allow-empty) on every call. Link the new doc from architecture.md (mcp subsystem pointer, docs index, gaps note). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…d_csv Rewrite the Result digest concept: it is now snapshot_file_digest (SHA-256 of the baked snapshot parquet, ordered by original_row_order) — a row multiset, recorded for worthy entries only; cheap entries record none. Replaces the per-row repr()+sha256 description. Index the three docs PR #137 added: the canonical-ordering ADR (under ADRs) and the two digest-investigation findings (datafusion scan order, result_digest vs xorq staleness). Note tallyman_read_csv as the fourth in-code data-sourcing helper in the MCP authoring section. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
paddymul
force-pushed
the
docs/architecture-overview
branch
from
53d9263 to
46698ee
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds a top-level architecture doc, refreshes the README to current reality, and clears out stale V0 cruft.
New:
docs/architecture.mdThe map a newcomer reads first:
README refresh
Brought to current reality:
packages/app/dist(there are no Jinja templates)./{project}/api/*routes and SSE event kinds; dropped the non-existent/lineageroutes.~/.tallyman-notebooks/buckaroo_sessions.json(not per-catalog),~/.tallyman-notebooks/home.tallyman packhandoff; fixed test pointer.Dropped the orphaned embed
Removed
packages/embed/buckaroo-embed.jsreferences from the README anddocs/installing.md— the live SPA mountsBuckarooServerViewfrombuckaroo-js-coredirectly.installing.mdstep 3 now buildspackages/app(the SPA that's actually served) instead of the embed. Removing the package itself is tracked in #138.Deleted stale cruft
plan.md,TICKETS.md,demo/script.md— they predate the SPA migration, theresult.parquetremoval, and the JSONL catalog format.docs/architecture.mdsupersedes them.Notes
Docs-only change. No code touched; net −1051 lines.
🤖 Generated with Claude Code