# stateful-art/proof-of-peacemaking architecture

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

- Interactive diagram: https://gitdiagram.com/stateful-art/proof-of-peacemaking
- Repository: https://github.com/stateful-art/proof-of-peacemaking

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        Browser["User Browser + MetaMask"]:::frontend
        JS["web/static/js"]:::frontend
        CSS["web/static/css"]:::frontend
        Templates["web/templates/*.html"]:::frontend
    end

    %% API Layer
    subgraph "API Layer (Go/Fiber Server)"
        direction TB
        Main["cmd/server/main.go"]:::backend
        Routes["api/routes/routes.go"]:::backend
        Handlers["internal/handlers"]:::backend
        Middleware["internal/middleware/auth.go"]:::backend
    end

    %% Core Domain & Services
    subgraph "Core Domain & Services"
        direction TB
        Models["internal/core/domain"]:::core
        Ports["internal/core/ports"]:::core
        Services["internal/core/services"]:::core
        StorageClient["internal/core/storage/r2.go"]:::persistence
        Config["internal/config/r2_config.go"]:::persistence
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        direction TB
        Mongo["MongoDB (internal/repositories/mongodb)"]:::persistence
        R2Store["Cloudflare R2"]:::persistence
    end

    %% Blockchain Layer
    subgraph "Blockchain Layer"
        direction TB
        RPC["Ethereum RPC Provider"]:::blockchain
        IPFS["IPFS Network"]:::blockchain
        Contracts["Smart Contracts (contracts/)"]:::blockchain
    end

    %% Auxiliary Tools
    subgraph "Deployment & Testing Scripts"
        direction TB
        Scripts["scripts/"]:::aux
    end

    %% Data Flows
    Browser -->|"loads assets"| JS
    Browser --> JS
    Browser --> CSS
    Browser --> Templates
    JS -->|"HTTP (REST/HTTP)"| Routes
    Routes -->|"invokes"| Handlers
    Handlers -->|"auth check"| Middleware
    Handlers -->|"calls"| Services
    Services -->|"R2 SDK"| StorageClient
    Services -->|"MongoDB driver"| Mongo
    JS -->|"IPFS HTTP API"| IPFS
    JS -->|"RPC (ethers.js)"| RPC
    RPC -->|"calls proxy"| Contracts
    Services -->|"deploy/test"| Scripts

    %% Click Events
    click JS "https://github.com/stateful-art/proof-of-peacemaking/tree/main/web/static/js"
    click CSS "https://github.com/stateful-art/proof-of-peacemaking/tree/main/web/static/css"
    click Templates "https://github.com/stateful-art/proof-of-peacemaking/blob/main/web/templates/*.html"
    click Main "https://github.com/stateful-art/proof-of-peacemaking/blob/main/cmd/server/main.go"
    click Routes "https://github.com/stateful-art/proof-of-peacemaking/blob/main/api/routes/routes.go"
    click Handlers "https://github.com/stateful-art/proof-of-peacemaking/blob/main/internal/handlers/*.go"
    click Middleware "https://github.com/stateful-art/proof-of-peacemaking/blob/main/internal/middleware/auth.go"
    click Models "https://github.com/stateful-art/proof-of-peacemaking/blob/main/internal/core/domain/*.go"
    click Ports "https://github.com/stateful-art/proof-of-peacemaking/blob/main/internal/core/ports/repositories.go"
    click Ports "https://github.com/stateful-art/proof-of-peacemaking/blob/main/internal/core/ports/services.go"
    click Ports "https://github.com/stateful-art/proof-of-peacemaking/blob/main/internal/core/ports/proofnft.go"
    click Services "https://github.com/stateful-art/proof-of-peacemaking/blob/main/internal/core/services/*.go"
    click StorageClient "https://github.com/stateful-art/proof-of-peacemaking/blob/main/internal/core/storage/r2.go"
    click Config "https://github.com/stateful-art/proof-of-peacemaking/blob/main/internal/config/r2_config.go"
    click Mongo "https://github.com/stateful-art/proof-of-peacemaking/blob/main/internal/repositories/mongodb/*.go"
    click Contracts "https://github.com/stateful-art/proof-of-peacemaking/tree/main/contracts/"
    click Scripts "https://github.com/stateful-art/proof-of-peacemaking/tree/main/scripts/"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366D6,color:#0366D6
    classDef backend fill:#E6FFED,stroke:#28A745,color:#28A745
    classDef core fill:#FFF5BA,stroke:#D4A017,color:#8B5E00
    classDef persistence fill:#FFD8B8,stroke:#E36209,color:#E36209
    classDef blockchain fill:#F3E8FF,stroke:#6f42c1,color:#6f42c1
    classDef aux fill:#F0F0F0,stroke:#6A737D,color:#6A737D
```
