# hgky95/milestone-maker architecture

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

- Interactive diagram: https://gitdiagram.com/hgky95/milestone-maker
- Repository: https://github.com/hgky95/milestone-maker

## Overview

##### Top-Level Components
- Frontend: Built with Next.js, React, and TypeScript. It includes components for user interactions such as connecting a wallet, displaying learning paths, and handling NFT achievements.
- AI Agent (Backend): A Python service that generates personalized learning paths using an AI agent (integrated with the Hive-Agent Kit), manages smart contract interactions, and handles off-chain data storage via IPFS.
- Smart Contracts: Developed in Solidity and managed using Foundry. These are responsible for blockchain-based progress tracking, milestone verification, and NFT minting.
- External Services/Dependencies:
– IPFS for content storage (with Pinata API integration)
– Blockchain network (local Anvil blockchain during development) and wallet integrations (e.g., MetaMask) for user authentication and transaction signing.

##### Analyzing the File Structure
- The project is organized in a “src” folder with three main subdirectories:
- src/ai-agent: Contains the Python backend, Dockerfile, configurations (hive_config.toml), and handlers for certificates, smart contracts, and IPFS.
- src/frontend: Contains the Next.js project including components, utility files, and UI assets.
- src/smartcontract: Contains Solidity source code, Foundry configuration files, and deployment scripts.
- Dockerfiles and docker-compose (compose.yaml at project root) indicate containerization for local development and deployment.

##### Diagramming the Architecture
a. Client/Browser:
- Represents the user interface where users connect their wallets (MetaMask) and interact with the platform.
b. Frontend Application:
- It communicates with the AI agent backend via API calls (as indicated by NEXT_PUBLIC_BACKEND_API).
c. AI Agent (Backend):
d. Blockchain / Smart Contracts:
e. External Services:
- IPFS: Mark an external service node for off-chain data storage. Indicate usage of Pinata APIs.
- Blockchain Network: Illustrate a blockchain node (local Anvil during development, general blockchain network in production) where the smart contracts are deployed and executed.

##### Relationships, Data Flows, and Architectural Patterns
- From the user’s browser to the Frontend (initiating actions like inputting learning goals and wallet connection).
- From Frontend to AI Agent (via a defined API endpoint).
- From AI Agent to the Smart Contract layer (for transactions such as updating progress or minting NFTs).
- From AI Agent to IPFS (to store generated learning paths) with the resulting IPFS hash sent back to the blockchain.
- Separation of concerns between UI (client-side operations), server-side AI processing, and immutable blockchain interactions.
- That a containerization pattern is used (with Docker and Compose) to package these components into isolated services.

##### Essential Architectural Elements
– Clearly divide the system into as many meaningful components as possible while mapping out the interactions, including setup steps like wallet connection, content generation, storage, and NFT minting.
- AI Integration using Hive-Agent Kit (for personalized learning path generation).
- Blockchain interactions via Web3.js (from the frontend) and Python libraries (from the AI agent).
- IPFS integration via Pinata (for decentralized content storage).

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Client Layer"
        User["User Browser (wallet connection)"]:::external
    end

    subgraph "Application Layer"
        FE["Frontend (Next.js + React)"]:::frontend
        AIA["AI Agent (Python)"]:::backend
        User -->|"initiates"| FE
        FE -->|"APICalls"| AIA
        AIA -->|"Response"| FE
    end

    subgraph "Blockchain & Storage Layer"
        SC["Smart Contracts (Solidity)"]:::blockchain
        IPFS["IPFS Storage (Pinata)"]:::external
        BN["Blockchain Network (Anvil/Production)"]:::blockchain
        AIA -->|"SmartContractInteraction"| SC
        AIA -->|"StoreData"| IPFS
        SC -->|"RecordsTransactions"| BN
    end

    subgraph "Containerization"
        DC["Docker Compose"]:::container
    end

    DC --> FE
    DC --> AIA
    DC --> SC

    click FE "https://github.com/hgky95/milestone-maker/tree/main/src/frontend"
    click AIA "https://github.com/hgky95/milestone-maker/tree/main/src/ai-agent"
    click SC "https://github.com/hgky95/milestone-maker/tree/main/src/smartcontract"
    click DC "https://github.com/hgky95/milestone-maker/blob/main/compose.yaml"

    classDef frontend fill:#aec7e8,stroke:#1f77b4,stroke-width:2px;
    classDef backend fill:#ffbb78,stroke:#ff7f0e,stroke-width:2px;
    classDef blockchain fill:#98df8a,stroke:#2ca02c,stroke-width:2px;
    classDef external fill:#c5b0d5,stroke:#9467bd,stroke-width:2px;
    classDef container fill:#ff9896,stroke:#d62728,stroke-width:2px;
```
