Skip to content

docs: improve README project architecture section (#45) - #61

Merged
Abd-Standard merged 2 commits into
Core-Foundry:mainfrom
Itodo-S:docs/improve-readme-architecture-45
Jun 19, 2026
Merged

docs: improve README project architecture section (#45)#61
Abd-Standard merged 2 commits into
Core-Foundry:mainfrom
Itodo-S:docs/improve-readme-architecture-45

Conversation

@Itodo-S

@Itodo-S Itodo-S commented Jun 18, 2026

Copy link
Copy Markdown
Contributor

Summary

Closes #45.

The README explained NotifyChain at a high level but did not describe how the smart contracts and off-chain services actually interact — and it still labelled the listener as a "future" component even though it is now implemented. This PR brings the architecture documentation in line with the current codebase.

Changes

  • Architecture overview: added a three-layer overview (smart contracts, listener service, dashboard) with a component/responsibility table.
  • Component interaction: added an ASCII diagram showing how on-chain events flow into the listener and out to Discord, the events API, and the dashboard, plus a reference to the detailed Documents/Task Bounty/ARCHITECTURE.md.
  • Contract responsibilities: clarified that the on-chain layer is the source of truth and emits the typed events the off-chain layer consumes.
  • Notification flow: added an end-to-end walkthrough (invoke → emit → poll → validate/register → deduplicate → notify → dashboard) and listed the key off-chain modules (EventSubscriber, NotificationDeduplicator, DiscordNotificationService, events API).
  • Project structure: documented the previously-undocumented listener/ and dashboard/ directories.
  • Features / tech stack: removed stale "coming soon / future" markers now that the listener service and Discord notifications exist.

Acceptance criteria

  • README provides a clear system overview
  • New contributors can understand component interactions
  • Documentation remains concise and easy to follow

Documentation-only change; no code paths affected.

@Abd-Standard

Copy link
Copy Markdown
Collaborator

please fix CI

Itodo-S added 2 commits June 18, 2026 23:24
- Add a three-layer architecture overview (contracts, listener, dashboard)
  with a component responsibility table
- Add a component-interaction diagram and reference the detailed
  ARCHITECTURE.md write-up
- Describe contract responsibilities and the end-to-end notification flow
- Document the listener and dashboard directories in project structure
- Update features and tech stack to reflect the now-implemented off-chain
  listener service and Discord notifications
- Regenerate dashboard/package-lock.json; the committed lockfile was
  corrupted (invalid JSON), which broke the Frontend job at the Setup Node
  cache step and 'npm ci'
- Add the '@testing-library/jest-dom' side-effect import to
  EventFiltersBar.test.tsx so 'toBeInTheDocument' is typed during the
  TypeScript build (tsc --noEmit)
- Run cargo fmt on version_test.rs to satisfy the Rust 'fmt check' job

Verified locally: dashboard lint/build/test pass and 'npm ci' succeeds;
contract 'cargo fmt --all -- --check' is clean and all 86 tests pass.
@Itodo-S
Itodo-S force-pushed the docs/improve-readme-architecture-45 branch from 337391e to 7f80781 Compare June 18, 2026 22:43
@Itodo-S

Itodo-S commented Jun 18, 2026

Copy link
Copy Markdown
Contributor Author

Thanks for the review! I've rebased onto the latest main and pushed fixes for the failing CI. The failures were pre-existing on main, not from the README change:

Frontend (lint, typecheck, test)

  • dashboard/package-lock.json was corrupted (invalid JSON in several places), which broke the Setup Node cache step and npm ci. Regenerated a valid lockfile.
  • Added the @testing-library/jest-dom side-effect import to EventFiltersBar.test.tsx so toBeInTheDocument is typed during tsc --noEmit (the build step).

Rust (fmt check, tests)

  • Ran cargo fmt on version_test.rs (import ordering) to satisfy the Check formatting step.

Verified locally:

  • dashboard: npm ci ✅, npm run lint ✅, npm run build ✅, npm test ✅ (7 tests)
  • contract: cargo fmt --all -- --check ✅ clean, cargo test --workspace --all-features ✅ (86 tests)

The new CI run is currently in action_required (awaiting maintainer approval to run workflows on a fork PR) — could you approve it when you get a chance? 🙏 @Abd-Standard

@Abd-Standard
Abd-Standard merged commit cf27a40 into Core-Foundry:main Jun 19, 2026
1 of 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.

[Docs] Improve README Project Architecture Section

2 participants