How stateful-art/proof-of-peacemaking works
Project Type and Purpose
• Full-stack Web3 application combining:
• A static JavaScript/CSS/HTML frontend (in web/)
• A Go/Fiber HTTP API backend (in cmd/server & internal/)
• A MongoDB database for user & session data
• Cloudflare R2 & IPFS for media and metadata storage
• Ethereum smart contracts (Diamond Pattern) on Sepolia
File Structure to Expose Architectural Layers
• Frontend (web/)
• web/static/js, web/static/css, web/templates
• Ethers.js for blockchain calls, MetaMask for wallet auth
• Backend entrypoint (cmd/server/main.go)
• HTTP handlers & middleware (internal/handlers, internal/middleware)
• Core domain logic & services (internal/core/domain, services, ports)
• Repositories (internal/repositories/mongodb) implementing data access
• Configuration & storage clients (internal/config, internal/core/storage/r2.go)
• Smart contracts (contracts/) following EIP-2535 Diamond Pattern
• Scripts for contract deployment/testing (scripts/)
Main Components & Their Responsibilities
A. Client Layer (User Browser / MetaMask)
• Renders HTML templates
• Executes JavaScript (JS calls HTTP API & ethers.js)
• Uploads media to IPFS; receives hashes
B. API Layer (Go/Fiber Server)
• Routes defined in api/routes/routes.go
• Handlers enforce auth (middleware) and call core services
C. Core Layer (Hexagonal/Clean Architecture)
• Domain models (Expression, Acknowledgement, ProofNFT, User, etc.)
• Ports (interfaces for repositories & external services)
• Services (business logic: auth, feed, session, NFT minting logic)
D. Persistence Layer
• MongoDB collections accessed via mongodb repositories
• Cloudflare R2 storage for static assets & media
E. Blockchain Layer
• Ethereum node (RPC provider such as Infura/Alchemy)
• Diamond proxy contract + multiple facets (ExpressionFacet, AcknowledgementFacet, POPNFTFacet, etc.)
• IPFS for decentralized content (via scripts/utils)
F. Auxiliary Services & Tools
• scripts/deploy.js, Hardhat for contract compilation/deployment
• scripts/test for automated contract tests
• Environment & config (.env.example, internal/config)
Component Interactions & Data Flows
• User initiates “Create Expression” in browser →
1. Frontend JS uploads content to IPFS → returns hash
2. Frontend calls Go API: POST /expressions with IPFS hash →
3. Handler → Service (ExpressionService) → R2 store (metadata) → MongoDB (record) → returns success
4. Frontend invokes ethers.js → DiamondProxy.createExpression() → ExpressionFacet → emits event
• Acknowledgement & NFT minting follow analogous flows.
• Real-time feed: frontend polls or websockets (future) to GET /feed → Handler → FeedService → repos → JSON.
Architectural Patterns & Key Principles
• Hexagonal (Clean) Architecture: handlers → services → ports → repositories
• Repository pattern for data access (MongoDB)
• Dependency inversion: core services depend on interfaces, not implementations
• Diamond Pattern (EIP-2535) for upgradeable smart contracts
• Separation of concerns: UI, API, business logic, persistence, blockchain
Essential Elements
• Clear, self-explanatory labels for each component
• A zoom-in inset on the smart contract architecture showing proxy → facets