# whats-up-pro/learn-twin-chain architecture

> Architecture diagram of the GitHub repository whats-up-pro/learn-twin-chain, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/whats-up-pro/learn-twin-chain
- Repository: https://github.com/whats-up-pro/learn-twin-chain

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        StudentBrowser["Student Browser"]:::external
        StudentUI["Student Frontend (React)"]:::frontend
        SchoolBrowser["School Browser"]:::external
        SchoolUI["School Dashboard (React/MUI)"]:::frontend
    end

    StudentBrowser -->|Uses| StudentUI
    SchoolBrowser -->|Uses| SchoolUI
    StudentUI -->|API calls| FastAPI
    SchoolUI -->|API calls| FastAPI

    %% API & Service Layer
    subgraph "API & Service Layer"
        FastAPI["FastAPI Backend"]:::backend
        Router["API Layer (router.py)"]:::api
        DigitalTwinService["DigitalTwinService"]:::service
        BlockchainService["BlockchainService"]:::service
        IPFSService["IPFSService"]:::service
        ZKPService["ZKPService"]:::service
        LearningService["LearningService"]:::service
        AnalyticsService["AnalyticsService"]:::service
    end

    FastAPI --> Router
    Router --> DigitalTwinService
    Router --> BlockchainService
    Router --> IPFSService
    Router --> ZKPService
    Router --> LearningService
    Router --> AnalyticsService

    %% Core Domain
    subgraph "Core Domain"
        EventProcessor["EventProcessor"]:::core
        StateManager["StateManager"]:::core
        TwinModel["TwinModel"]:::core
        LearningTwin["LearningTwin"]:::core
    end

    DigitalTwinService --> StateManager
    StateManager --> TwinModel
    TwinModel --> LearningTwin
    EventProcessor --> BlockchainService

    AnalyticsService -->|invoke| externGemini

    %% Data Layer
    subgraph "Data Layer"
        UserStore["users.json"]:::data
        TwinFiles["digital_twins/*.json"]:::data
        IPFSStore["IPFS Metadata (Pinata)"]:::data
    end

    DigitalTwinService --> UserStore
    DigitalTwinService --> TwinFiles
    IPFSService --> IPFSStore

    %% Blockchain Network
    subgraph "Blockchain Network"
        Contracts["Smart Contracts (ERC-1155/721, Registry)"]:::blockchain
        Chain["Sepolia/Testnet"]:::external
    end

    BlockchainService --> Contracts
    Contracts --> Chain

    %% ZKP Pipeline
    subgraph "ZKP Pipeline"
        direction TB
        CIRCUIT["score_proof.circom"]:::zkp
        R1CS["score_proof.r1cs"]:::zkp
        PTAU["pot12_final.ptau"]:::zkp
        WASM["score_proof.wasm"]:::zkp
        WITNESS["generate_witness.js"]:::zkp
    end

    ZKPService --> CIRCUIT
    ZKPService --> R1CS
    ZKPService --> PTAU
    ZKPService --> WASM
    ZKPService --> WITNESS
    ZKPService --> BlockchainService

    %% External Services
    externInfura["Infura RPC"]:::external
    externGemini["Gemini AI"]:::external

    BlockchainService --> externInfura
    AnalyticsService --> externGemini

    %% Deployment & Orchestration
    DeployContracts["deploy_contracts.py"]:::script
    SetupZKP["deploy_and_test_zkp.py & setup_real_zkp.py"]:::script
    startSystem["start_system.py"]:::script

    startSystem --> FastAPI
    startSystem --> DeployContracts
    startSystem --> SetupZKP

    %% Tests & Configs
    Tests["test_blockchain_integration.py & Lock.js"]:::test
    Config[".env.example, hardhat.config.js, API_ENDPOINTS.md, DEPLOYMENT_GUIDE.md"]:::config

    %% Click Events
    click FastAPI "https://github.com/whats-up-pro/learn-twin-chain/blob/main/backend/digital_twin/main.py"
    click Router "https://github.com/whats-up-pro/learn-twin-chain/blob/main/backend/digital_twin/api/router.py"
    click BlockchainService "https://github.com/whats-up-pro/learn-twin-chain/blob/main/backend/digital_twin/services/blockchain_service.py"
    click DigitalTwinService "https://github.com/whats-up-pro/learn-twin-chain/blob/main/backend/digital_twin/services/digital_twin_service.py"
    click CIRCUIT "https://github.com/whats-up-pro/learn-twin-chain/blob/main/backend/zkp/score_proof.circom"
    click R1CS "https://github.com/whats-up-pro/learn-twin-chain/blob/main/backend/zkp/score_proof.r1cs"
    click PTAU "https://github.com/whats-up-pro/learn-twin-chain/blob/main/backend/zkp/pot12_final.ptau"
    click WASM "https://github.com/whats-up-pro/learn-twin-chain/blob/main/backend/zkp/score_proof_js/score_proof.wasm"
    click WITNESS "https://github.com/whats-up-pro/learn-twin-chain/blob/main/backend/zkp/score_proof_js/generate_witness.js"
    click IPFSService "https://github.com/whats-up-pro/learn-twin-chain/blob/main/backend/digital_twin/services/ipfs_service.py"
    click AnalyticsService "https://github.com/whats-up-pro/learn-twin-chain/blob/main/backend/digital_twin/services/analytics_service.py"
    click EventProcessor "https://github.com/whats-up-pro/learn-twin-chain/blob/main/backend/digital_twin/core/event_processor.py"
    click StateManager "https://github.com/whats-up-pro/learn-twin-chain/blob/main/backend/digital_twin/core/state_manager.py"
    click TwinModel "https://github.com/whats-up-pro/learn-twin-chain/blob/main/backend/digital_twin/core/twin_model.py"
    click LearningTwin "https://github.com/whats-up-pro/learn-twin-chain/blob/main/backend/digital_twin/core/learning_twin.py"
    click UserStore "https://github.com/whats-up-pro/learn-twin-chain/blob/main/backend/data/users/users.json"
    click TwinFiles "https://github.com/whats-up-pro/learn-twin-chain/tree/main/backend/data/digital_twins/"
    click DeployContracts "https://github.com/whats-up-pro/learn-twin-chain/blob/main/backend/deploy_contracts.py"
    click SetupZKP "https://github.com/whats-up-pro/learn-twin-chain/blob/main/backend/deploy_and_test_zkp.py"
    click SetupZKP "https://github.com/whats-up-pro/learn-twin-chain/blob/main/backend/setup_real_zkp.py"
    click startSystem "https://github.com/whats-up-pro/learn-twin-chain/blob/main/start_system.py"
    click Tests "https://github.com/whats-up-pro/learn-twin-chain/blob/main/backend/test/test_blockchain_integration.py"
    click Tests "https://github.com/whats-up-pro/learn-twin-chain/blob/main/backend/test/Lock.js"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef backend fill:#90EE90,stroke:#000
    classDef api fill:#98FB98,stroke:#000
    classDef service fill:#32CD32,stroke:#000
    classDef core fill:#FFFF99,stroke:#000
    classDef data fill:#FFD700,stroke:#000
    classDef blockchain fill:#DA70D6,stroke:#000
    classDef zkp fill:#FFC0CB,stroke:#000,stroke-dasharray:5 5
    classDef external fill:#D3D3D3,stroke:#000
    classDef script fill:#FFA500,stroke:#000
    classDef test fill:#F4A460,stroke:#000
    classDef config fill:#DCDCDC,stroke:#000
```
