From 5e0ac7b565897fa09e1e44cced83218b9f749475 Mon Sep 17 00:00:00 2001 From: Delightech28 Date: Sat, 20 Jun 2026 02:45:40 +0100 Subject: [PATCH] docs: add system architecture overview with diagrams --- wiki/README.md | 7 +- wiki/architecture.md | 216 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 220 insertions(+), 3 deletions(-) create mode 100644 wiki/architecture.md diff --git a/wiki/README.md b/wiki/README.md index b995a60..9ae8eba 100644 --- a/wiki/README.md +++ b/wiki/README.md @@ -6,6 +6,7 @@ This folder is a GitHub Wiki-style set of documents that live in the repo so the ## Contents -- [Soroban Contract State Machine](./contract-state-machine.md) -- [Indexer ↔ Database Sync Flow](./indexer-sync-flow.md) -- [Frontend “Standard Library” Patterns](./frontend-patterns.md) +- [System Architecture Overview](./architecture.md) – High-level component diagram and data flows +- [Soroban Contract State Machine](./contract-state-machine.md) – Loan lifecycle and smart contract states +- [Indexer ↔ Database Sync Flow](./indexer-sync-flow.md) – Event polling and real-time synchronization +- [Frontend "Standard Library" Patterns](./frontend-patterns.md) – React component conventions diff --git a/wiki/architecture.md b/wiki/architecture.md new file mode 100644 index 0000000..3b9db0e --- /dev/null +++ b/wiki/architecture.md @@ -0,0 +1,216 @@ +# System Architecture Overview + +RemitLend is a DeFi gamification platform built on Stellar's Soroban smart contracts. This document provides a high-level overview of how all components interact to deliver loan management and credit scoring functionality. + +## Architecture Diagram + +```mermaid +graph TB + User[("👤 User
(Browser)")] + + subgraph Frontend["🎮 Frontend Layer"] + NextJS["Next.js App
(React)"] + RedisCache["Redis Cache
(Session & Queries)"] + end + + subgraph Backend["🔧 Backend Layer"] + API["REST API
(Node.js)"] + AuthService["Auth Service
(JWT)"] + EventIndexer["Event Indexer
(Polling)"] + end + + subgraph Data["💾 Data Layer"] + PostgreSQL["PostgreSQL
(User, Scores,
Loan Events)"] + end + + subgraph Blockchain["⛓️ Blockchain Layer"] + Contracts["Soroban Contracts
(LoanManager,
RemittanceNFT)"] + StellarRPC["Stellar RPC Node
(Event Stream)"] + end + + subgraph External["🌐 External Services"] + Sentry["Sentry
(Error Tracking)"] + end + + User -->|1. Interact| NextJS + NextJS -->|2. API Calls| API + API -->|3. Read/Write| PostgreSQL + API -->|4. Check Cache| RedisCache + RedisCache -->|5. Response| API + API -->|6. Auth Check| AuthService + + NextJS -->|Display Data| User + + User -->|8. Submit Loan Request| API + API -->|9. Invoke| Contracts + Contracts -->|10. Emit Events| StellarRPC + + EventIndexer -->|11. Poll Events| StellarRPC + EventIndexer -->|12. Decode & Process| EventIndexer + EventIndexer -->|13. Update State| PostgreSQL + EventIndexer -->|14. Notify Backend| API + PostgreSQL -->|15. Query Results| NextJS + + API -->|Error Logs| Sentry + EventIndexer -->|Error Logs| Sentry + NextJS -->|Error Logs| Sentry +``` + +## Component Descriptions + +### Frontend Layer + +- **Next.js App**: React-based UI that displays loan status, credit scores, quest progress, and kingdom tier information +- **Redis Cache**: Temporary storage for session data and frequently-queried results to reduce database load + +### Backend Layer + +- **REST API**: Node.js server handling user requests, authentication, loan operations, and real-time data queries +- **Auth Service**: JWT-based authentication for secure API access +- **Event Indexer**: Background service that continuously polls Stellar RPC for on-chain events and synchronizes them with the database + +### Data Layer + +- **PostgreSQL**: Primary database storing user profiles, credit scores, loan history, and indexed events + +### Blockchain Layer + +- **Soroban Contracts**: Smart contracts on Stellar that manage loan lifecycle (`LoanManager`) and user credit tracking (`RemittanceNFT`) +- **Stellar RPC Node**: Provides access to contract events and allows transaction submission + +### External Services + +- **Sentry**: Error tracking and monitoring for all layers + +## Data Flow Diagrams + +### Request Flow (User Action → Contract) + +```mermaid +sequenceDiagram + participant User as 👤 User + participant Frontend as 🎮 Next.js + participant Backend as 🔧 Backend API + participant Contract as ⛓️ Soroban Contract + participant DB as 💾 PostgreSQL + + User->>Frontend: Click "Request Loan" + Frontend->>Backend: POST /loans/request (amount, borrower) + Backend->>Backend: Validate request + Backend->>Contract: invoke request_loan() + Contract->>Contract: Check eligibility, create loan + Contract-->>Backend: ✓ Transaction ID + Backend->>DB: Record loan request + DB-->>Backend: ✓ Stored + Backend-->>Frontend: { status: "pending", txId: "..." } + Frontend-->>User: Show "Loan requested, awaiting approval" +``` + +### Event Processing Flow (On-Chain → Database) + +```mermaid +sequenceDiagram + participant Contract as ⛓️ Soroban Contract + participant RPC as 🔌 Stellar RPC + participant Indexer as 📡 Event Indexer + participant DB as 💾 PostgreSQL + participant Cache as 🔴 Redis + + Contract->>RPC: Emit LoanApproved event + + loop Every 30 seconds + Indexer->>RPC: getEvents(startLedger, contractId) + RPC-->>Indexer: [LoanApproved, ...] + Indexer->>Indexer: Decode event XDR + Indexer->>DB: UPDATE scores (+points) + DB-->>Indexer: ✓ Updated + Indexer->>Cache: Invalidate user score + Cache-->>Indexer: ✓ Cleared + end + + note over Indexer,DB: Real-time credit score updates +``` + +### User Dashboard Load (Frontend → Database) + +```mermaid +sequenceDiagram + participant User as 👤 User + participant Frontend as 🎮 Next.js + participant Backend as 🔧 Backend API + participant Cache as 🔴 Redis + participant DB as 💾 PostgreSQL + + User->>Frontend: Visit dashboard + Frontend->>Backend: GET /dashboard + + Backend->>Cache: Check cached data + alt Cache hit + Cache-->>Backend: { score: 850, loans: [...] } + Backend-->>Frontend: ✓ (fast) + else Cache miss + Backend->>DB: Query user scores, loans + DB-->>Backend: [Data] + Backend->>Cache: Store for 5 min + Backend-->>Frontend: [Data] + end + + Frontend-->>User: Render dashboard with real-time data +``` + +## Trust Boundaries + +```mermaid +graph LR + Internet["🌐 Internet
(Untrusted)"] + FrontendUser["🎮 Frontend +
User Browser
(Semi-Trusted)"] + Backend["🔧 Backend
(Trusted)"] + Contracts["⛓️ Soroban
Contracts
(Immutable)"] + + Internet -->|HTTPS| FrontendUser + FrontendUser -->|JWT Token| Backend + Backend -->|Invoke only
after checks| Contracts + + note over Internet,FrontendUser: Trust Boundary #1
Validated by HTTPS & JWT + note over Backend,Contracts: Trust Boundary #2
Soroban is source of truth +``` + +### Trust Boundaries Explained + +1. **Internet ↔ Frontend**: SSL/TLS encryption; all API calls authenticated with JWT +2. **Frontend ↔ Backend**: JWT validation; backend enforces permissions before querying DB or contracts +3. **Backend ↔ Contracts**: Contracts are immutable source of truth; backend reads events, never overwrites contract state + +## External Dependencies + +| Dependency | Purpose | Risk | +| ----------------------- | ---------------------------------------- | ------------------------------------------------------ | +| **Stellar RPC Node** | Access to contract events and state | High availability required; fallback nodes recommended | +| **PostgreSQL Database** | Persistent storage of scores and history | Data consistency critical; backups required | +| **Redis** | Session cache and query result caching | Performance optimization; loss is recoverable | +| **Sentry** | Error tracking and monitoring | Optional but recommended for production | + +## Key Files & Documentation + +- **[Contract State Machine](./contract-state-machine.md)** – Loan lifecycle and contract state transitions +- **[Indexer Sync Flow](./indexer-sync-flow.md)** – Detailed explanation of event polling and database synchronization +- **[Frontend Patterns](./frontend-patterns.md)** – React component conventions and reusable UI patterns +- **[DESIGN.md](../DESIGN.md)** – Product vision, UI/UX decisions, and visual design language + +## Running the System Locally + +Typically: + +1. Start PostgreSQL (or connect to remote instance) +2. Start Stellar RPC (or use testnet/mainnet) +3. Deploy Soroban contracts to testnet +4. Start backend: `npm start` (runs API + indexer) +5. Start frontend: `npm run dev` (runs Next.js) + +See each service's README for specific setup instructions. + +## See Also + +- [Soroban Documentation](https://developers.stellar.org/docs/learn/storing-data) +- [Stellar RPC API](https://developers.stellar.org/docs/data/rpc/api-reference) +- [RemitLend Wiki](./README.md)