How hgky95/milestone-maker works
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).