How whats-up-pro/learn-twin-chain works
Project Type and Purpose
• This is a full-stack Digital Twin system (“LearnTwinChain”) for education, integrating:
• FastAPI backend (Python)
• Two React/Vite frontends (Student UI and School Dashboard)
• Blockchain (Solidity ERC-1155 & ERC-721 contracts)
• IPFS (Pinata) for metadata storage
• Zero-Knowledge Proof (ZKP) certificate generation
• JSON file-based data store (pluggable to SQL)
File Structure
• Top-level directories:
• backend/ – FastAPI code, smart-contract ABIs, ZKP circuits, deploy & test scripts
• frontend-dgt/ – School Dashboard React/MUI app
• pages/, components/, contexts/, services/ – Student UI React/TS app
• zkp/ under backend – circom circuit, proving keys, witness generation
• contracts/ – compiled ABIs for ERC-1155, ERC-721, registry
• data/ under backend – users.json, per-student digital twin JSON files
• Notable config files:
• backend/.env.example, hardhat.config.js
• vite.config.ts/js, tsconfig.json, pyproject.toml
• Deployment scripts: deploy_contracts.py, start_system.py
Insights from README
• Two frontends on ports 5173 (Student) and 5180 (School)
• Backend API on port 8000 with FastAPI + Uvicorn
• Workflow: user registers → digital twin JSON created → module completion triggers ERC-1155 mint → achievements trigger ERC-721 mint → ZKP certificate generation for employer verification
• External dependencies: Blockchain RPC (Infura), Pinata API, AI (Gemini) for analytics
Main Components & Their Relationships
a. Presentation Layer
• Student Browser → Student Frontend (React + TS)
• School Browser → School Dashboard (React + MUI)
b. API Layer
• Nginx (optional) or direct CORS → FastAPI gateway endpoints
c. Service Layer (backend/digital_twin/services)
• DigitalTwinService (load/store JSON files)
• BlockchainService (wrap Web3 interactions: mint, query)
• ZKPService (invoke circom/witness/prover/js)
• IPFSService (Pinata uploads)
• LearningService, AnalyticsService, GeminiAPI
d. Core Domain (backend/digital_twin/core + models)
• EventProcessor, StateManager, TwinModel, LearningTwin
e. Data Layer
• JSON data store: users.json, dt_did_learntwin_*.json
• IPFS metadata URIs
f. Blockchain Network
• Smart Contracts: ModuleProgressNFT (ERC-1155), LearningAchievementNFT (ERC-721), DigitalTwinRegistry
• Deployed on Sepolia/testnet, addresses in deployment_addresses.json
g. ZKP Pipeline
• Circom circuit (score_proof.circom), ptau, zkey → generate proof, public input
h. External Services
• Infura (RPC URL)
• Pinata Cloud (IPFS gateway)
• Gemini API (AI analytics)
Architectural Patterns & Design Principles
• Layered architecture: clear separation of presentation, API, service, core, data
• Plugin-style services: each external integration (blockchain, IPFS, ZKP, AI) is encapsulated
• Stateless frontends, stateful backend managed via JSON files
• Micro-service style within backend modules (services/core/api directories)
• Event-driven updates (EventProcessor triggers blockchain calls on state change)
• Blue rectangles: Frontend apps (Student, School Dashboard)
• Green rectangle: FastAPI Backend (API Gateway + Service Layer)
• Yellow rectangles: Core Domain components (EventProcessor, StateManager, etc.)
• Orange parallelogram: External AI (Gemini)
• Browsers → Frontends → Backend API
• Backend Service → JSON store reads/writes
• Service calls → Blockchain node (mint, query)
• Service uploads/downloads → IPFS (Pinata)
• ZKPService → Circom/WASM modules → Proof → BlockchainService
• AnalyticsService ↔ Gemini API
Detail
• Don’t collapse too much: show individual backend services (BlockchainService, IPFSService, etc.)
• Both frontends separately
• ZKP pipeline steps (compile circuit, generate witness, prove, verify)
• Contract deployment script as a one-time operational flow