Skip to content

docs: add Architecture Overview Guide (Closes #137)#150

Merged
Abd-Standard merged 1 commit into
Core-Foundry:mainfrom
zeroknowledge0x:docs/issue-137-architecture-overview
Jun 22, 2026
Merged

docs: add Architecture Overview Guide (Closes #137)#150
Abd-Standard merged 1 commit into
Core-Foundry:mainfrom
zeroknowledge0x:docs/issue-137-architecture-overview

Conversation

@zeroknowledge0x

Copy link
Copy Markdown
Contributor

Summary

Adds a single high-level architecture guide at the repo root that gives
new contributors a unified mental model of NotifyChain before they dig
into the per-component docs.

Issue: #137 — Documentation > Create Architecture Overview Guide.

What's in this guide

  • Three-layer system overview — on-chain contracts, listener service, dashboard
  • Contract catalog (TaskBounty + AutoShare) with on-chain/off-chain boundary contract
  • Listener module map + scheduler subsystem with the atomic UPDATE ... WHERE status = 'PENDING' rationale
  • End-to-end data flow — from contract invocation through event emission, deduplication, dispatch, and dashboard render
  • Project structure tree and a first-day contributor checklist
  • Cross-references to every subsystem doc, runbook, and reference spec
  • Glossary of recurring terms (Soroban, cursor, dispatcher, DCO, GrantFox)

482 lines, well under the size that would warrant splitting.

Acceptance criteria mapping

Criterion Where it's covered
New contributors understand project structure §2 (system at a glance), §7 (project structure), §8 (where to start)
Documentation is easy to follow §1–§11 with consistent heading hierarchy; TL;DR diagram in §2
Diagrams are included §2, §4.1, §4.3, §6 (4 ASCII diagrams)
Document system components §3 (contracts), §4 (listener), §5 (dashboard)
Explain data flow §6 (end-to-end trace with 8 numbered steps)
Link related resources §9 (related resources, grouped by purpose)

Files changed

  • ARCHITECTURE_OVERVIEW.md — new (482 lines)
  • README.md — link from the existing Architecture Overview section + entry in the project structure tree

Test plan

This is a documentation-only PR. No code changes.

  • All internal links use repo-relative paths verified by grep
  • Heading hierarchy is consistent (h1h2h3)
  • No broken relative links (grep -oP '\]\([^)]+\)' returns 0 matches)
  • Reviewed against existing Documents/Task Bounty/ARCHITECTURE.md and listener/ARCHITECTURE-DIAGRAM.md to avoid contradictions

Closes #137

Signed-off-by: zeroknowledge0x

Adds a single high-level architecture guide at the repo root that gives
new contributors a unified mental model of NotifyChain before they dig
into the per-component docs.

Covers:
- Three-layer system overview (on-chain contracts, listener, dashboard)
- Contract catalog (TaskBounty + AutoShare) and event-emission pattern
- Listener module map and scheduler subsystem with atomicity rationale
- End-to-end data flow from contract invocation to dashboard render
- Project structure map and a first-day contributor checklist
- Links to every subsystem doc, runbook, and reference spec
- Glossary of recurring terms (Soroban, cursor, dispatcher, DCO, GrantFox)

Also wires the new guide into README.md:
- Top-level Architecture Overview section now links to this file
  before the existing contract-level ARCHITECTURE.md
- Project structure tree lists ARCHITECTURE_OVERVIEW.md at the root

Refs: Core-Foundry#137

Signed-off-by: zeroknowledge0x
Signed-off-by: zeroknowledge0x <zeroknowledge0x@users.noreply.github.com>
@Abd-Standard Abd-Standard merged commit da20435 into Core-Foundry:main Jun 22, 2026
2 checks passed
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.

[Documentation] Create Architecture Overview Guide

2 participants