Skip to content

Conversation

djwhitt
Copy link
Collaborator

@djwhitt djwhitt commented Aug 17, 2025

Summary

  • Add PlantUML diagrams documenting chunk retrieval architecture
  • Update CLAUDE.md to ensure diagrams are maintained as code changes

Details

Creates two new architecture diagrams in docs/diagrams/src/:

  • chunk-source-priority.puml - Shows the fallback order when retrieving chunks (Local Cache → AR.IO Peers → Arweave Network → Legacy S3)
  • chunk-component-architecture.puml - Shows component relationships and how the Composite Source uses configurable parallelism

These diagrams follow the existing pattern in the codebase and help developers understand the chunk retrieval system architecture.

Test plan

  • Verify PlantUML files render correctly
  • Confirm diagrams accurately represent the current implementation
  • Check that CLAUDE.md reminder is clear for future maintainers

🤖 Generated with Claude Code

Copy link

codecov bot commented Aug 17, 2025

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 71.16%. Comparing base (5247b4c) to head (123bfe9).
⚠️ Report is 1 commits behind head on develop.

Additional details and impacted files
@@           Coverage Diff            @@
##           develop     #474   +/-   ##
========================================
  Coverage    71.16%   71.16%           
========================================
  Files           62       62           
  Lines        17514    17514           
  Branches      1110     1110           
========================================
  Hits         12463    12463           
  Misses        5038     5038           
  Partials        13       13           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

djwhitt and others added 6 commits August 18, 2025 15:38
Add PlantUML diagrams documenting chunk retrieval architecture:
- chunk-source-priority.puml: Shows fallback order of chunk sources
- chunk-component-architecture.puml: Shows component relationships

Update CLAUDE.md to ensure diagrams are maintained as code changes.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>
- Double diagram size for better readability (DPI 400)
- Update component names for accuracy:
  - "SQLite DB" → "TX Offset Index"
  - "File Cache" → "Local Cache"
  - "AR.IO Peers" → "AR.IO Network"
  - "Arweave" → "Arweave Network"
- Add separate Browser and AR.IO Peer client components
- Update abbreviations for consistency (TOI, LC, ARIO, AR)
- Change "Lookup TX" to "Lookup offset" for clarity

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>
- Rename diagram file from chunk-source-priority to chunk-retrieval-cascade
- Update title to "Chunk Retrieval Cascade" for better clarity
- Set DPI to 300 for improved readability
- Clarify cache types: "in-memory & disk" instead of just "local disk"
- Distinguish AR.IO network (frequently used) from Arweave (complete set)
- Add rebroadcast flow from S3 back to Arweave network

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>
- Add new diagram showing contiguous data source hierarchy
- Shows 5-tier fallback system: Local Cache → Trusted Gateways → Chunk Reconstruction → TX Data → AR.IO Network
- Consistent with chunk retrieval cascade diagram naming and style
- Set to 200 DPI for optimal display size
- Based on actual data source configuration and retrieval flow

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>
…468)

- Add sequence diagram showing new efficient data retrieval flow
- Uses root parent offset to skip bundle hierarchy traversal
- Shows offset source can be local index or network-based
- Demonstrates direct chunk fetching using calculated offset + range
- Includes caching and streaming response flow
- Set to 200 DPI for consistent display sizing

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>
- Add alternative approach using on-demand ANS-104 header parsing
- Shows root ID source providing only transaction ID (no pre-calculated offsets)
- Demonstrates dynamic offset calculation by parsing bundle headers
- Trades performance for reduced storage requirements
- Maintains same chunk fetching and assembly flow as pre-calculated approach
- Set to 200 DPI for consistent display sizing

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>
@djwhitt djwhitt force-pushed the PE-8468-architecture-diagrams branch from 425352b to 123bfe9 Compare August 18, 2025 21:54
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.

1 participant