Skip to content

docs: enrich README and introduction with architecture overview from DeepWiki#833

Merged
sorpaas merged 1 commit into
jarchain:masterfrom
monsieurbulb:docs/deepwiki-architecture
May 20, 2026
Merged

docs: enrich README and introduction with architecture overview from DeepWiki#833
sorpaas merged 1 commit into
jarchain:masterfrom
monsieurbulb:docs/deepwiki-architecture

Conversation

@monsieurbulb
Copy link
Copy Markdown
Contributor

What this does

Updates README.md and docs/introduction.md with richer architecture documentation sourced from DeepWiki.

README.md changes

  • Added Architecture section describing the dual-track spec + Rust node design
  • Expanded Repository Structure table to include javm/ and tools/ directories
  • Added Key Components section covering Grey, JAVM, and Formal Specification
  • Added Data Flow pipeline (Join → Accumulate → Refine)
  • Expanded Quick Start with prerequisites and local testnet modes
  • Added Further Reading section linking to DeepWiki

docs/introduction.md changes

  • Added Core Concepts with timeslot/epoch/core table
  • Added Join-Accumulate-Refine Pipeline breakdown
  • Added State and Services with Greek letter notation table
  • Added Coinless Design explanation
  • Added Consensus and Finality (Safrole + Data Availability)
  • Added Key Differences from Gray Paper section
  • Added Further Reading links

No code changes — documentation only.

@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented May 6, 2026

Genesis Review

Comparison targets:

How to review

Post a comment with the following format (rank from best to worst):

/review
difficulty: <commit1>, <commit2>, ..., <commitN>, currentPR
novelty: <commit1>, <commit2>, ..., <commitN>, currentPR
design: <commit1>, <commit2>, ..., <commitN>, currentPR
verdict: merge

Use the short commit hashes above and currentPR for this PR.
Each line ranks all comparison targets + this PR from best to worst.

To meta-review another reviewer's comment, react with 👍 or 👎.

@johandroid
Copy link
Copy Markdown
Contributor

/review
difficulty: 97d8b6b, 1045647, 91878cf, bf816b6, e23cfed, currentPR, 6b4d0f4, a35553d
novelty: e23cfed, 97d8b6b, 1045647, bf816b6, 91878cf, currentPR, 6b4d0f4, a35553d
design: 97d8b6b, 1045647, 91878cf, e23cfed, bf816b6, currentPR, 6b4d0f4, a35553d
verdict: merge

Expands the top-level README and introduction into a clearer architectural entry point, with useful links and current component framing. This is valuable project-facing documentation, but it ranks below the Genesis/scoring, dependency-security, runtime debug, test, and store-refactor targets because it is mostly explanatory rather than structural. Merge is reasonable for docs-only onboarding improvement.

@github-actions
Copy link
Copy Markdown
Contributor

JAR Bot: Review recorded from @johandroid (1 reviews, 0 meta-reviews).
Merge weight: 0/37665 (need >50%).

Expand README.md and docs/introduction.md to give a fuller picture
of the codebase architecture: dual-track formal spec + minimum-
kernel v3 architecture, the rust/ workspace crate map (javm-cap,
javm-exec, javm, nub, jar-kernel), the rationale for the KVM-
microkernel direction, and an up-to-date bench table covering both
the general PVM workload suite and the new STARK-shaped suite.

Content sourced from docs/spec/ (the authoritative architecture
spec) and the current javm-bench numbers, replacing the earlier
DeepWiki-derived draft (which predated the grey/ → rust/
restructure and the v3 kernel direction).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@sorpaas sorpaas force-pushed the docs/deepwiki-architecture branch from 5735e2e to edc5859 Compare May 20, 2026 04:02
@sorpaas
Copy link
Copy Markdown
Contributor

sorpaas commented May 20, 2026

/review
difficulty: 97d8b6b, 1045647, 91878cf, bf816b6, e23cfed, currentPR, 6b4d0f4, a35553d
novelty: e23cfed, 97d8b6b, 1045647, bf816b6, 91878cf, currentPR, 6b4d0f4, a35553d
design: 97d8b6b, 91878cf, 1045647, e23cfed, bf816b6, currentPR, 6b4d0f4, a35553d
verdict: merge

Docs-only update to README + introduction. The PR body still says "from DeepWiki," but the current head goes well beyond that: it has been re-curated to describe the minimum-kernel v3 architecture, surface the nub KVM-microkernel rationale, link into the new docs/spec/ tree (from #845), and pin the up-to-date STARK benchmark numbers (from #843). The Quick Start expansion picks the right things to call out (Rust + Lean toolchains, KVM-only paths, the right cargo bench invocations), and the introduction adds a useful state-σ Greek-letter table and the coinless-design rationale.

Ranked mid-pack across all three axes — same broad shape as @johandroid's review, with a small design-ordering swap. Docs work that synthesises an existing-but-scattered architecture story has real value but isn't structural engineering: it sits above pure formatting (6b4d0f45) and the 1-line lockfile bump (a35553d4), below substantive code/test/refactor work. On design specifically I put 91878cf0 (clean table_count/find_in_kvs helper extraction) above 1045647e (libp2p bump, valuable as a security action but mostly Cargo.lock churn) — when the axis is design quality, the helper extraction is the stronger contribution; @johandroid had them in the opposite order.

Verdict merge: docs accurately reflect current architecture, internal links resolve, CI green (lint / SBOM / test / security all pass; the genesis check on the current SHA was still running at review time but the same content has been carrying CI cleanly).

@github-actions
Copy link
Copy Markdown
Contributor

JAR Bot: Quorum reached — triggering merge.
Reviews: 2, meta-reviews: 0.
Merge weight: 34350/37796 (>50%).

@sorpaas sorpaas merged commit 4dccb7c into jarchain:master May 20, 2026
9 checks passed
@sorpaas
Copy link
Copy Markdown
Contributor

sorpaas commented May 20, 2026

JAR Bot: Merged (quorum reached).
Score: {"designQuality":28,"difficulty":28,"novelty":28}
Weight delta: 28

github-actions Bot pushed a commit that referenced this pull request May 20, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants