# tushar-agarwal7/shinolearn architecture

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

- Interactive diagram: https://gitdiagram.com/tushar-agarwal7/shinolearn
- Repository: https://github.com/tushar-agarwal7/shinolearn

## Overview

##### Project type and purpose
- ShinoLearn is a full-stack, Web3-powered language learning platform.
- Purpose: Allow users to connect a crypto wallet, stake USDC into language‐learning challenges, interact with AI tutors, track progress via Prisma/PostgreSQL, and earn blockchain‐based rewards via smart contracts.

##### File structure
- Top-level “app” directory: Next.js App Router pages + API routes (React server components, route.js files).
- “components/”: Reusable UI and feature components (auth, challenge, dashboard, learn, notifications, ui).
- “lib/”: Shared logic libraries:
- lib/auth (JWT generation and verification)
- lib/web3 (ethers.js hooks, providers, contract ABIs, staking logic)
- lib/learn (prompt helpers)
- lib/cron (daily progress job)
- “prisma/”: Schema + migration history for PostgreSQL.
- “shinobi-contracts/”: Hardhat project for Solidity smart contracts (staking, USDC mint, deployment scripts).
- Configs: next.config.mjs, tailwind.config.js, bun.lock, package.json, etc.

##### Key points from README
- Architecture overview already shows:
- User Devices → Frontend (Next.js, React, Tailwind, ethers.js)
- Backend (Next.js API Routes handling auth, AI, challenge management)
- Database (PostgreSQL + Prisma)
- Blockchain (Smart Contracts on Ethereum; Aave for yield)
- External AI service (bloomz, Deepseek)

##### Summary
- Distinct “shinobi-contracts” project as a separate deployment artifact.
- Connection is labeled (e.g., “POST /api/challenges/join”, “ethers.js → Stake()”).
- Detail any middleware (JWT verify, Web3 signature) between API and DB.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Devices
    subgraph "User Devices"
        direction TB
        User["Web Browser / Mobile App"]:::user
    end

    %% Frontend Layer
    subgraph "Next.js Frontend" 
        direction TB
        Layout["app/layout.js"]:::frontend
        Home["app/page.js"]:::frontend
        DashboardPages["app/dashboard/**"]:::frontend
        SignIn["app/auth/signin/page.jsx"]:::frontend
        Styles["Tailwind & Global CSS"]:::frontend
    end

    %% React UI Components
    subgraph "React UI Components" 
        direction TB
        Components["components/**"]:::ui
    end

    %% API Layer
    subgraph "API Layer" 
        direction TB
        subgraph "Auth Service"
            direction TB
            AuthWallet["app/api/auth/wallet/route.js"]:::api
            AuthLogout["app/api/auth/logout/route.js"]:::api
            JWT["lib/auth/jwt.js"]:::api
            Verify["lib/auth/verify.js"]:::api
        end
        subgraph "AI Conversation Service"
            direction TB
            AssistantChat["app/api/assistant-chat/route.js"]:::api
            ConvEvaluate["app/api/conversation/evaluate/route.js"]:::api
            Conversation["app/api/conversation/route.js"]:::api
            Inference["app/api/inference/route.js"]:::api
            PromptHelper["lib/learn/promt-helper.js"]:::api
        end
        subgraph "Challenge Management Service"
            direction TB
            Challenges["app/api/challenges/**"]:::api
        end
        subgraph "Notifications Service"
            direction TB
            Notifications["app/api/notifications/**"]:::api
        end
        subgraph "Learning Modules"
            direction TB
            LearnGrammar["app/api/learn/grammar/**"]:::api
            LearnQuick["app/api/learn/quick-learn/**"]:::api
            LearnSpeaking["app/api/learn/speaking/start-call/route.js"]:::api
            LearnVocab["app/api/learn/vocabulary/**"]:::api
        end
    end

    %% Database
    subgraph "PostgreSQL (Prisma)"
        direction TB
        PrismaSchema["prisma/schema.prisma"]:::db
        Migrations["prisma/migrations/**"]:::db
    end

    %% Web3 Integration & Cron
    subgraph "Web3 & Cron"
        direction TB
        Providers["lib/web3/providers.js"]:::web3
        StakingLib["lib/web3/staking.js"]:::web3
        StakingABI["lib/web3/abis/stakingABI.json"]:::web3
        USDCABI["lib/web3/abis/usdcABI.json"]:::web3
        UseContract["lib/web3/hooks/useContract.js"]:::web3
        UseStaking["lib/web3/hooks/useStaking.js"]:::web3
        UseYield["lib/web3/hooks/useYield.js"]:::web3
        CronJob["lib/cron/dailyCheck.js"]:::cron
    end

    %% Smart Contracts
    subgraph "Solidity Smart Contracts"
        direction TB
        ContractsDir["shinobi-contracts/contracts/**"]:::contracts
        DeployScript["shinobi-contracts/scripts/deploy.js"]:::contracts
        MintUSDC["shinobi-contracts/scripts/mint-usdc.js"]:::contracts
        Tests["shinobi-contracts/test/Lock.js"]:::contracts
        HardhatConfig["shinobi-contracts/hardhat.config.js"]:::contracts
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Bloomz["Bloomz-560m AI"]:::external
        Aave["Aave Protocol"]:::external
    end

    %% Connections
    User -->|"HTTP/HTTPS"| Layout
    Layout -->|"renders"| Components
    Layout -->|"uses styles"| Styles
    Layout -->|"fetches API"| AuthWallet
    SignIn -->|"fetches API"| AuthWallet

    Components -->|"interacts via ethers.js"| Providers
    Providers -->|"provides"| UseContract
    UseContract -->|"calls"| StakingLib
    StakingLib -->|"ABI"| StakingABI
    StakingLib -->|"ABI"| USDCABI
    StakingLib -->|"fetches yield"| UseYield
    UseStaking -->|"hooks"| StakingLib

    AuthWallet -->|"JWT check"| JWT
    AuthWallet -->|"verify signature"| Verify
    AuthLogout -->|"invalidate session"| JWT

    AssistantChat -->|"calls"| Bloomz
    Inference -->|"calls"| Bloomz
    ConvEvaluate -->|"uses"| PromptHelper

    Challenges -->|"CRUD"| PrismaSchema
    Challenges -->|"updates staking"| StakingLib

    Notifications -->|"CRUD"| PrismaSchema

    LearnGrammar -->|"CRUD"| PrismaSchema
    LearnQuick -->|"CRUD"| PrismaSchema
    LearnSpeaking -->|"calls audio service"| PrismaSchema
    LearnVocab -->|"CRUD"| PrismaSchema

    CronJob -->|"runs daily"| Challenges
    CronJob -->|"runs daily"| PrismaSchema
    CronJob -->|"can call"| StakingLib

    ContractsDir -->|"deployed via"| DeployScript
    DeployScript -->|"interacts"| Ethereum["Ethereum Network"]:::blockchain
    MintUSDC -->|"mints tokens"| Ethereum
    Tests -->|"unit tests"| ContractsDir

    StakingLib -->|"stake() on"| Ethereum
    Ethereum -->|"yield via"| Aave

    %% Database connection
    AuthWallet -->|"reads/writes"| PrismaSchema
    JWT -->|"stores sessions"| PrismaSchema

    %% Click Events
    click Layout "https://github.com/tushar-agarwal7/shinolearn/blob/main/app/layout.js"
    click Home "https://github.com/tushar-agarwal7/shinolearn/blob/main/app/page.js"
    click DashboardPages "https://github.com/tushar-agarwal7/shinolearn/tree/main/app/dashboard/"
    click SignIn "https://github.com/tushar-agarwal7/shinolearn/blob/main/app/auth/signin/page.jsx"
    click Components "https://github.com/tushar-agarwal7/shinolearn/tree/main/components/"
    click Styles "https://github.com/tushar-agarwal7/shinolearn/blob/main/tailwind.config.js"
    click Styles "https://github.com/tushar-agarwal7/shinolearn/blob/main/postcss.config.mjs"
    click Styles "https://github.com/tushar-agarwal7/shinolearn/blob/main/app/globals.css"
    click AuthWallet "https://github.com/tushar-agarwal7/shinolearn/blob/main/app/api/auth/wallet/route.js"
    click AuthLogout "https://github.com/tushar-agarwal7/shinolearn/blob/main/app/api/auth/logout/route.js"
    click JWT "https://github.com/tushar-agarwal7/shinolearn/blob/main/lib/auth/jwt.js"
    click Verify "https://github.com/tushar-agarwal7/shinolearn/blob/main/lib/auth/verify.js"
    click AssistantChat "https://github.com/tushar-agarwal7/shinolearn/blob/main/app/api/assistant-chat/route.js"
    click ConvEvaluate "https://github.com/tushar-agarwal7/shinolearn/blob/main/app/api/conversation/evaluate/route.js"
    click Conversation "https://github.com/tushar-agarwal7/shinolearn/blob/main/app/api/conversation/route.js"
    click Inference "https://github.com/tushar-agarwal7/shinolearn/blob/main/app/api/inference/route.js"
    click PromptHelper "https://github.com/tushar-agarwal7/shinolearn/blob/main/lib/learn/promt-helper.js"
    click Challenges "https://github.com/tushar-agarwal7/shinolearn/tree/main/app/api/challenges/"
    click Notifications "https://github.com/tushar-agarwal7/shinolearn/tree/main/app/api/notifications/"
    click LearnGrammar "https://github.com/tushar-agarwal7/shinolearn/tree/main/app/api/learn/grammar/"
    click LearnQuick "https://github.com/tushar-agarwal7/shinolearn/tree/main/app/api/learn/quick-learn/"
    click LearnSpeaking "https://github.com/tushar-agarwal7/shinolearn/blob/main/app/api/learn/speaking/start-call/route.js"
    click LearnVocab "https://github.com/tushar-agarwal7/shinolearn/tree/main/app/api/learn/vocabulary/"
    click PrismaSchema "https://github.com/tushar-agarwal7/shinolearn/blob/main/prisma/schema.prisma"
    click Migrations "https://github.com/tushar-agarwal7/shinolearn/tree/main/prisma/migrations/"
    click Providers "https://github.com/tushar-agarwal7/shinolearn/blob/main/lib/web3/providers.js"
    click StakingLib "https://github.com/tushar-agarwal7/shinolearn/blob/main/lib/web3/staking.js"
    click StakingABI "https://github.com/tushar-agarwal7/shinolearn/blob/main/lib/web3/abis/stakingABI.json"
    click USDCABI "https://github.com/tushar-agarwal7/shinolearn/blob/main/lib/web3/abis/usdcABI.json"
    click UseContract "https://github.com/tushar-agarwal7/shinolearn/blob/main/lib/web3/hooks/useContract.js"
    click UseStaking "https://github.com/tushar-agarwal7/shinolearn/blob/main/lib/web3/hooks/useStaking.js"
    click UseYield "https://github.com/tushar-agarwal7/shinolearn/blob/main/lib/web3/hooks/useYield.js"
    click CronJob "https://github.com/tushar-agarwal7/shinolearn/blob/main/lib/cron/dailyCheck.js"
    click ContractsDir "https://github.com/tushar-agarwal7/shinolearn/tree/main/shinobi-contracts/contracts/"
    click DeployScript "https://github.com/tushar-agarwal7/shinolearn/blob/main/shinobi-contracts/scripts/deploy.js"
    click MintUSDC "https://github.com/tushar-agarwal7/shinolearn/blob/main/shinobi-contracts/scripts/mint-usdc.js"
    click Tests "https://github.com/tushar-agarwal7/shinolearn/blob/main/shinobi-contracts/test/Lock.js"
    click HardhatConfig "https://github.com/tushar-agarwal7/shinolearn/blob/main/shinobi-contracts/hardhat.config.js"

    %% Styles
    classDef user fill:#BBDEFB,stroke:#0D47A1,color:#0D47A1;
    classDef frontend fill:#E3F2FD,stroke:#1E88E5,color:#1E88E5;
    classDef ui fill:#FCE4EC,stroke:#D81B60,color:#D81B60;
    classDef api fill:#E8F5E9,stroke:#43A047,color:#43A047;
    classDef db fill:#FFF3E0,stroke:#FB8C00,color:#E65100;
    classDef web3 fill:#E1F5FE,stroke:#039BE5,color:#0277BD;
    classDef cron fill:#F3E5F5,stroke:#8E24AA,color:#6A1B9A;
    classDef contracts fill:#FBE9E7,stroke:#FF5722,color:#BF360C;
    classDef external fill:#E0F2F1,stroke:#00796B,color:#004D40;
    classDef blockchain fill:#ECEFF1,stroke:#607D8B,color:#455A64;
```
