# subkash2206/flowmint architecture

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

- Interactive diagram: https://gitdiagram.com/subkash2206/flowmint
- Repository: https://github.com/subkash2206/flowmint

## Overview

##### Project Type and Purpose
- This is a full-stack Web3 application (“FlowMint MVP”) that lets creators tokenize future revenue as NFTs and investors buy fractions of that revenue.
- It consists of three main codebases:
- A Next.js/TypeScript/Tailwind CSS frontend ("flowmint-frontend")
- A FastAPI/Python backend with SQLAlchemy and SQLite ("flowmint-backend")
- A Solidity smart-contract layer with Hardhat/OpenZeppelin ("flowmint-contracts")

##### File-Structure Analysis
- Top-level folders:
- flowmint-frontend: Next.js “App Router,” React components, contexts, hooks, ABI JSONs for on-chain calls.
- flowmint-backend: main.py, database.py, models.py, route modules (users, projects), requirements.txt.
- flowmint-contracts: Hardhat config, contracts/, deploy & test scripts.
- Patterns:
- Frontend uses Context API for auth and notifications, Wagmi+Viem libraries for blockchain.
- Backend follows MVC-style: Pydantic models, SQLAlchemy ORM, FastAPI route modules.
- Smart contracts are modular, tested with Hardhat.

##### README Insights
- Frontend Tech: Next.js15, TypeScript, Tailwind, Wagmi, Viem.
- Backend Tech: FastAPI, SQLAlchemy, SQLite (PostgreSQL in prod), JWT, Pydantic.
- Smart Contracts: Solidity, OpenZeppelin, Hardhat, deployed on Polygon.
- External dependencies: MetaMask, CORS, demo data fixtures, CI/CD targets (Vercel, Heroku).

##### Main Components
a. Client Layer (Browser)
- Next.js React App
- MetaMask wallet extension
- Wagmi/Viem hooks for blockchain calls
b. API Layer
- FastAPI server
- JWT auth & CORS middleware
- Route modules: /api/users, /api/projects, /api/investments, /api/creator/dashboard, /api/investor/dashboard
c. Data Layer
- SQLite (dev) / PostgreSQL (prod)
- SQLAlchemy ORM & Pydantic models (Users, Projects, Investments)
d. Smart-Contract Layer
- Deployed Solidity contracts (RevenueDistributor, FlowMintNFT, IERC20) on Polygon testnet
- Hardhat scripts (deploy.js) and tests
e. External Services
- MetaMask/Ethereum RPC (e.g., Infura or Alchemy endpoint)
- Vercel/Netlify (frontend hosting)
- Railway/Heroku (backend hosting)

##### Component Relationships & Data Flow
- Browser ←HTTP→ FastAPI (user management, project data, dashboards)
- Browser ←Web3 RPC→ Polygon node via MetaMask (mint NFTs, invest, revenue distribution)
- FastAPI ←DB queries→ SQLite/PostgreSQL
- CI/CD pipelines push frontend to Vercel, backend to Railway, contracts via Hardhat to Polygon

##### Architectural Patterns & Design Principles
- Clear separation of concerns: UI vs. business logic vs. persistence vs. blockchain
- Layered architecture: Presentation → API → Data
- Component-based UI, RESTful API, ORM abstraction
- Contract abstraction with ABIs, Dev/Prod environment parity via Hardhat/Infura

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        NextApp["Next.js React App"]:::ui
        ReactComps["React UI Components"]:::ui
        AuthCtx["AuthContext"]:::ui
        NotifCtx["NotificationContext"]:::ui
        Providers["Blockchain Hooks & Providers"]:::ui
        subgraph "ABI Definitions"
            direction TB
            ABIFlowMint["FlowMintNFT.json"]:::ui
            ABIIERC20["IERC20.json"]:::ui
            ABIRevDist["RevenueDistributor.json"]:::ui
        end
    end

    %% Server Layer
    subgraph "Server Layer"
        direction TB
        FastAPI["FastAPI Server"]:::svc
        Middleware["CORS & JWT Middleware"]:::svc
        UsersRoute["/api/users"]:::svc
        ProjectsRoute["/api/projects"]:::svc
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        DB["SQLite (dev) / PostgreSQL (prod)"]:::db
        ORM["SQLAlchemy ORM & Pydantic Models"]:::db
    end

    %% Blockchain Layer
    subgraph "Blockchain Layer"
        direction TB
        HardhatConfig["Hardhat Config"]:::chain
        ContractsDir["Solidity Contracts"]:::chain
        DeployScript["Deployment Script"]:::chain
        Tests["Smart Contract Tests"]:::chain
        DeployedContracts["Deployed Contracts on Polygon"]:::chain
    end

    %% External Services
    subgraph "External Services"
        direction TB
        MetaMask["MetaMask Wallet"]:::ext
        ETHRPC["Ethereum RPC (Infura/Alchemy)"]:::ext
        Vercel["Vercel/Netlify"]:::ext
        Railway["Railway/Heroku"]:::ext
    end

    %% Connections
    NextApp -->|HTTPS: JSON| FastAPI
    NextApp -->|JSON-RPC via MetaMask| MetaMask
    MetaMask -->|RPC| ETHRPC
    FastAPI -->|SQLAlchemy ORM| DB
    FastAPI -->|uses| ORM
    FastAPI -->|routes| UsersRoute
    FastAPI -->|routes| ProjectsRoute
    NextApp -->|imports ABI| ABIFlowMint
    NextApp -->|imports ABI| ABIIERC20
    NextApp -->|imports ABI| ABIRevDist
    NextApp -->|uses| ReactComps
    NextApp -->|uses| AuthCtx
    NextApp -->|uses| NotifCtx
    NextApp -->|uses| Providers

    HardhatConfig --> ContractsDir
    ContractsDir --> DeployScript
    ContractsDir --> Tests
    DeployScript --> DeployedContracts
    ETHRPC --> DeployedContracts

    %% CI/CD
    NextApp -.->|Deploy| Vercel
    FastAPI -.->|Deploy| Railway
    DeployScript -.->|Deploy Contracts| DeployedContracts

    %% Click Events
    click NextApp "https://github.com/subkash2206/flowmint/tree/main/flowmint-frontend/src/app"
    click ReactComps "https://github.com/subkash2206/flowmint/tree/main/flowmint-frontend/src/components"
    click AuthCtx "https://github.com/subkash2206/flowmint/blob/main/flowmint-frontend/src/contexts/AuthContext.jsx"
    click NotifCtx "https://github.com/subkash2206/flowmint/blob/main/flowmint-frontend/src/contexts/NotificationContext.jsx"
    click Providers "https://github.com/subkash2206/flowmint/blob/main/flowmint-frontend/src/components/providers.tsx"
    click ABIFlowMint "https://github.com/subkash2206/flowmint/blob/main/flowmint-frontend/src/lib/abi/FlowMintNFT.json"
    click ABIIERC20 "https://github.com/subkash2206/flowmint/blob/main/flowmint-frontend/src/lib/abi/IERC20.json"
    click ABIRevDist "https://github.com/subkash2206/flowmint/blob/main/flowmint-frontend/src/lib/abi/RevenueDistributor.json"
    click FastAPI "https://github.com/subkash2206/flowmint/blob/main/flowmint-backend/main.py"
    click UsersRoute "https://github.com/subkash2206/flowmint/blob/main/flowmint-backend/routes/users.py"
    click ProjectsRoute "https://github.com/subkash2206/flowmint/blob/main/flowmint-backend/routes/projects.py"
    click DB "https://github.com/subkash2206/flowmint/blob/main/flowmint-backend/database.py"
    click ORM "https://github.com/subkash2206/flowmint/blob/main/flowmint-backend/models.py"
    click HardhatConfig "https://github.com/subkash2206/flowmint/blob/main/flowmint-contracts/hardhat.config.js"
    click ContractsDir "https://github.com/subkash2206/flowmint/tree/main/flowmint-contracts/contracts/"
    click DeployScript "https://github.com/subkash2206/flowmint/blob/main/flowmint-contracts/scripts/deploy.js"
    click Tests "https://github.com/subkash2206/flowmint/blob/main/flowmint-contracts/test/Lock.js"

    %% Styles
    classDef ui fill:#E3F2FD,stroke:#0D47A1
    classDef svc fill:#E8F5E9,stroke:#1B5E20
    classDef db fill:#FFF3E0,stroke:#E65100
    classDef chain fill:#F3E5F5,stroke:#6A1B9A
    classDef ext fill:#ECEFF1,stroke:#37474F
```
