docs: improve README project architecture section (#45)

README.md

@@ -24,41 +24,50 @@ The project enables developers to build reactive decentralized applications with
 
 ## Architecture Overview
 
-NotifyChain consists of two main components:
+NotifyChain is built from three cooperating layers. On-chain contracts emit
+events, an off-chain listener turns those events into notifications and a
+queryable feed, and a dashboard renders that feed for humans. Each layer can be
+run and developed independently.
 
-1. **On-chain Smart Contracts**: Deployed on the Stellar blockchain using Soroban, these contracts emit events for all important actions
-2. **Off-chain Listener Service**: (Future implementation) Watches the blockchain for events and triggers notifications
+| Component | Location | Tech | Responsibility |
+|-----------|----------|------|----------------|
+| **Smart Contracts** | `contract/`, `Documents/Task Bounty/` | Soroban / Rust | Execute business logic and emit a structured event for every important state change |
+| **Listener Service** | `listener/` | Node.js / TypeScript | Poll the Stellar network for contract events, deduplicate them, push notifications, and expose an HTTP events API |
+| **Dashboard** | `dashboard/` | React + Vite | Fetch the listener's events API and display real-time contract activity |
 
-### High-Level Architecture Diagram
+### How the Components Interact
 
 ```
-                    +----------------------+
-                    |   Smart Contract     |
-                    |----------------------|
-                    | Emits Events         |
-                    +----------+-----------+
-                               |
-                               |
-                      Blockchain Network
-                               |
-                               ▼
-                    +----------------------+
-                    |  NotifyChain Helper  |
-                    |  (Off-chain Worker)  |
-                    +----------+-----------+
-                               |
-                +--------------+--------------+
-                |                             |
-                ▼                             ▼
-        Notification Service          External Webhooks
-                |                             |
-                ▼                             ▼
-         Email / SMS / Push         APIs / Bots / Dashboards
+        On-chain                         Off-chain
+ ┌────────────────────┐         ┌──────────────────────────────┐
+ │  Soroban Contracts │         │        Listener Service       │
+ │  (TaskBounty,      │  emit   │  ┌────────────────────────┐   │
+ │   AutoShare)       │ ──────► │  │ EventSubscriber (poll) │   │
+ │                    │ events  │  └───────────┬────────────┘   │
+ └────────────────────┘         │              ▼                │
+            ▲                    │  ┌────────────────────────┐  │
+            │ invoke             │  │ Deduplicator + Registry │ │
+            │                    │  └───────────┬────────────┘  │
+ ┌────────────────────┐         │      ┌────────┴────────┐      │
+ │   Users / dApps    │         │      ▼                 ▼      │
+ └────────────────────┘         │  Discord         /api/events  │
+                                │  webhook          HTTP API     │
+                                └──────────────────────┬─────────┘
+                                                       │ fetch
+                                                       ▼
+                                            ┌────────────────────┐
+                                            │  React Dashboard   │
+                                            └────────────────────┘
 ```
 
-### Smart Contract Architecture
+> A more detailed, contract-level architecture write-up lives in
+> [`Documents/Task Bounty/ARCHITECTURE.md`](Documents/Task%20Bounty/ARCHITECTURE.md).
 
-There are two example smart contracts in this repository:
+### Contract Responsibilities
+
+The on-chain layer is the source of truth. Each contract owns its own state and
+emits typed events (see [Event Flow](#event-flow)) that the off-chain layer
+consumes. Two example contracts ship with the project:
 
 #### 1. TaskBounty Contract (`Documents/Task Bounty/`)
 
@@ -126,6 +135,18 @@ Notify-Chain/
 │   │       └── build_log.txt
 │   ├── Cargo.toml                    # Workspace configuration
 │   └── README.md
+├── listener/                         # Off-chain listener service (Node + TS)
+│   └── src/
+│       ├── api/                      # Events HTTP API (/api/events, /health)
+│       ├── services/                 # Subscriber, deduplicator, Discord notifier
+│       ├── store/                    # In-memory event registry
+│       ├── utils/                    # Logging, formatting, helpers
+│       └── index.ts                  # Service entry point
+├── dashboard/                        # Real-time event dashboard (React + Vite)
+│   └── src/
+│       ├── components/               # Event list / card / filter UI
+│       ├── services/                 # Events API client
+│       └── store/                    # Client-side event store (Zustand)
 ├── Documents/
 │   ├── Task Bounty/                  # TaskBounty contract and docs
 │   │   ├── src/
@@ -158,6 +179,39 @@ Notify-Chain/
 
 ## Event Flow
 
+### End-to-End Notification Flow
+
+This is how a single on-chain action becomes a delivered notification:
+
+```
+1. A user invokes a contract function (e.g. create_task)
+   ↓
+2. The contract updates state and emits a typed event
+   ↓
+3. The listener's EventSubscriber polls the Stellar RPC and picks up the event
+   ↓
+4. The event is validated, parsed, and recorded in the in-memory event registry
+   ↓
+5. The deduplicator drops events already seen (by contract + event id)
+   ↓
+6. A Discord notification is sent (if a webhook is configured)
+   ↓
+7. The dashboard fetches GET /api/events and renders the new activity
+```
+
+Key pieces of the off-chain pipeline:
+
+- **`EventSubscriber`** (`listener/src/services/event-subscriber.ts`) polls the
+  configured contracts on an interval and reconnects on failure.
+- **`NotificationDeduplicator`** (`listener/src/services/notification-deduplicator.ts`)
+  prevents the same event from being notified twice.
+- **`DiscordNotificationService`** (`listener/src/services/discord-notification.ts`)
+  formats and delivers notifications.
+- **Events API** (`listener/src/api/events-server.ts`) exposes `GET /api/events`
+  for the dashboard and `GET /health` for monitoring.
+
+The contract events that drive this flow are listed below.
+
 ### 1. TaskBounty Contract Events
 
 | Event | Trigger | Data Included |
@@ -346,7 +400,7 @@ Add this to `.vscode/settings.json`:
 
 * 📡 Real-time blockchain event monitoring
 * 🔗 Smart contract event emission
-* ⚡ Off-chain listener service (coming soon)
+* ⚡ Off-chain listener service
 * 🔔 Custom notification triggers
 * 🌐 Webhook support for external integrations
 * 📝 Event logging and processing
@@ -377,20 +431,17 @@ Add this to `.vscode/settings.json`:
 * **Soroban** (Stellar smart contracts)
 * **Rust**
 
-### Backend (Future)
+### Off-chain Services
 
 * Node.js
 * TypeScript
 * Stellar SDK
+* React + Vite (dashboard)
 
-### Notification Providers (Future)
+### Notification Providers
 
-* Email
-* Discord
-* Telegram
-* Slack
-* Webhooks
-* Push Notifications
+* Discord (implemented)
+* Email, Telegram, Slack, Webhooks, Push Notifications (planned)
 
 ---
 

contract/contracts/hello-world/src/tests/version_test.rs

@@ -1,5 +1,5 @@
-use soroban_sdk::Env;
 use crate::{AutoShareContract, AutoShareContractClient};
+use soroban_sdk::Env;
 
 #[test]
 fn test_version() {