# tsheylock/modu architecture

> Architecture diagram of the GitHub repository tsheylock/modu, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tsheylock/modu
- Repository: https://github.com/tsheylock/modu

## Overview

##### Project type and purpose
- This is a decentralized application (dApp) combining:
– A React + TypeScript single-page frontend (built with Vite)
– Solidity smart contracts deployed via Hardhat onto the Saske blockchain
– AI/NLP modules for emotion analysis (text, audio, video)
– Decentralized storage (IPFS) for historical data
– Visualization libraries (Chart.js, vis-network) for graphs and trend analysis

##### File structure
- Top-level deployment & build artifacts:
– Dockerfile, docker-compose.yml, nginx.conf, deploy.sh
– .env, .env.example, tsconfig*.json, vite.config.ts
– Hardhat config (hardhat.config.ts), scripts/, test/
- Source code directories (implied by README):
– src/components: UI widgets
– src/contracts: Solidity smart contracts
– src/utils: helpers (Ethers.js, IPFS clients, NLP wrappers)
– src/pages or index.html: entry point
- Documentation covers installation, security, scaling, monitoring, optimization, and deployment.

##### README for additional insights
- Technology stack: React, TypeScript, Vite, Solidity, Hardhat, IPFS, Ethers.js/Web3.js, NLP libs, Chart.js, vis-network
- Workflow: “npm run dev” spins up the Vite server; “npm run compile/test/deploy” for contracts
- Environment configuration via .env (RPC URLs, private keys, API keys)

##### Main components & interactions
A. Frontend (User’s Browser)
– React SPA (Vite-bundle)
– Emotion input (text/audio/video) → NLP engine (client-side or external API)
– Chart.js & vis-network for in-browser rendering
– Ethers.js/Web3.js to call smart contracts
– IPFS client to upload/download emotional data blobs
B. Smart Contracts (Solidity on Saske)
– EmotionToken contract: mints NFTs, records metadata pointers
– Event logs for downstream indexing
C. Decentralized Storage (IPFS)
– Stores emotion payloads, history archives
– Pinning node or third-party pinning service
D. Blockchain Network (Saske mainnet/testnet)
– RPC endpoints (configured in .env)
– Etherscan or similar explorer for block & contract verification
E. Dev/CI Tools (local dev only)
– Hardhat local network for testing & deployment scripts (scripts/ folder)
F. Deployment Infrastructure
– Docker containers: Nginx serves the built SPA; optional Node.js SSR container if used
– docker-compose.yml orchestrates services (frontend, optionally a local IPFS node)
– CI/CD pipelines (deploy.sh, GitHub Actions or similar)

1. User → Browser UI → NLP analysis
2. Browser UI → IPFS API → data CID returned
3. Browser UI → Smart Contract via Ethers.js → mint NFT with metadata CID
4. Smart Contract → emits events → Browser listens (WebSocket/RPC polling)
5. Browser UI ← fetches historical CIDs from contract events → IPFS → displays trends

##### Architectural patterns & design principles
- dApp pattern: client-heavy, blockchain as backend
- Separation of concerns: UI / business logic / blockchain / storage
- Containerization: immutable builds, reproducible environments
- Environment-driven configuration (.env) for RPC URLs and API keys
- Modular frontend: components, utils, services
- Dev-prod parity: Hardhat local network mirrors Saske testnet/mainnet

##### Diagramming recommendations
- Use clear, concise labels for each node (e.g., “React SPA”, “EmotionToken Contract”, “IPFS Pinning”)
– Frontend (blue rectangles)
- Important technologies next to each component

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Client (Browser)"
        React["React SPA"]:::frontend
        NLP["Emotion Input → NLP Engine"]:::frontend
        Chart["Chart.js & vis-network Rendering"]:::frontend
        EthersClient["Ethers.js / Web3.js"]:::frontend
        IPFSClient["IPFS Client"]:::frontend
    end

    subgraph "Blockchain"
        EmotionToken["EmotionToken Contract"]:::blockchain
        Saske["Saske Network"]:::blockchain
        HardhatLocal["Hardhat Local Network (Dev)"]:::infra
    end

    subgraph "Storage & Services"
        IPFSNode["IPFS (Decentralized Storage)"]:::storage
        Pinning["IPFS Pinning Service"]:::storage
        NLPAPI["AI/NLP External API"]:::storage
    end

    subgraph "Deployment & CI/CD"
        Docker["Docker (Nginx + SPA)"]:::infra
        Compose["docker-compose"]:::infra
        DeploySh["deploy.sh"]:::infra
        Setup["setup.ps1"]:::infra
        Env["Environment Config (.env)"]:::infra
        TSConfig["TypeScript Configuration"]:::infra
        Lint["Linting & Formatting"]:::infra
        PackageLock["package-lock.json"]:::infra
        Tailwind["tailwind.config.js"]:::infra
        PostCSS["postcss.config.js"]:::infra
        Workspace["project.code-workspace"]:::infra
    end

    subgraph "Documentation"
        README["README.md"]:::infra
        DEPLOYMENT["DEPLOYMENT.md"]:::infra
        MONITORING["MONITORING.md"]:::infra
        SCALING["SCALING.md"]:::infra
        SECURITY["SECURITY.md"]:::infra
        OPTIMIZATION["OPTIMIZATION.md"]:::infra
        INSTALL["INSTALL.md"]:::infra
        BACKUP["BACKUP.md"]:::infra
    end

    React -->|"analyzes"| NLP
    NLP -->|"calls"| NLPAPI
    React -->|"renders"| Chart
    React -->|"interacts"| EthersClient
    EthersClient -->|"invokes"| EmotionToken
    EmotionToken -->|"deployed on"| Saske
    HardhatLocal -->|"deploys"| EmotionToken
    React -->|"uploads data"| IPFSClient
    IPFSClient -->|"stores"| IPFSNode
    IPFSNode -->|"pin via"| Pinning
    EmotionToken -->|"emits events"| React
    Saske -->|"events & RPC"| React
    Compose --> Docker
    Docker --> React

    %% Click events
    click React "https://github.com/tsheylock/modu/blob/main/index.html"
    click React "https://github.com/tsheylock/modu/blob/main/vite.config.ts"
    click React "https://github.com/tsheylock/modu/blob/main/package.json"
    click HardhatLocal "https://github.com/tsheylock/modu/blob/main/hardhat.config.ts"
    click Env "https://github.com/tsheylock/modu/blob/main/.env"
    click Env "https://github.com/tsheylock/modu/blob/main/.env.example"
    click Docker "https://github.com/tsheylock/modu/tree/main/Dockerfile"
    click Docker "https://github.com/tsheylock/modu/blob/main/nginx.conf"
    click Compose "https://github.com/tsheylock/modu/blob/main/docker-compose.yml"
    click DeploySh "https://github.com/tsheylock/modu/blob/main/deploy.sh"
    click Setup "https://github.com/tsheylock/modu/blob/main/setup.ps1"
    click TSConfig "https://github.com/tsheylock/modu/blob/main/tsconfig.json"
    click TSConfig "https://github.com/tsheylock/modu/blob/main/tsconfig.app.json"
    click TSConfig "https://github.com/tsheylock/modu/blob/main/tsconfig.node.json"
    click Lint "https://github.com/tsheylock/modu/blob/main/.eslintrc.json"
    click Lint "https://github.com/tsheylock/modu/blob/main/eslint.config.js"
    click Lint "https://github.com/tsheylock/modu/blob/main/.prettierrc"
    click PackageLock "https://github.com/tsheylock/modu/blob/main/package-lock.json"
    click Tailwind "https://github.com/tsheylock/modu/blob/main/tailwind.config.js"
    click PostCSS "https://github.com/tsheylock/modu/blob/main/postcss.config.js"
    click Workspace "https://github.com/tsheylock/modu/blob/main/project.code-workspace"
    click README "https://github.com/tsheylock/modu/blob/main/README.md"
    click DEPLOYMENT "https://github.com/tsheylock/modu/blob/main/DEPLOYMENT.md"
    click MONITORING "https://github.com/tsheylock/modu/blob/main/MONITORING.md"
    click SCALING "https://github.com/tsheylock/modu/blob/main/SCALING.md"
    click SECURITY "https://github.com/tsheylock/modu/blob/main/SECURITY.md"
    click OPTIMIZATION "https://github.com/tsheylock/modu/blob/main/OPTIMIZATION.md"
    click INSTALL "https://github.com/tsheylock/modu/blob/main/INSTALL.md"
    click BACKUP "https://github.com/tsheylock/modu/blob/main/BACKUP.md"

    classDef frontend fill:#D0E8FF,stroke:#0366D6;
    classDef blockchain fill:#E2F0D9,stroke:#228B22;
    classDef storage fill:#FDEBD0,stroke:#FF8C00;
    classDef infra fill:#E0E0E0,stroke:#A9A9A9;
```
