# juan-lukeklopper/philanthropymatrix architecture

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

- Interactive diagram: https://gitdiagram.com/juan-lukeklopper/philanthropymatrix
- Repository: https://github.com/juan-lukeklopper/philanthropymatrix

## Overview

##### Project Type and Purpose
- This is a full-stack decentralized application (dApp) called PhilanthropyMatrix.
- It consists of three main moving parts:
- A SvelteKit frontend (frontend/) for user interaction.
- A Rust-based REST API backend (backend/) with PostgreSQL for data storage and business logic.
- A CosmWasm SNIP-721 smart contract (snip721/) deployed on the Secret Network to mint and manage NFTs.
- Purpose: enable users to propose and approve charitable donations, mint them as NFTs, and execute secure, privacy-preserving transactions on a blockchain.

##### File Structure Analysis
- frontend/
- SvelteKit app with component library, route definitions, and a single api.js service.
- Uses environment variables for backend URL and SNIP-721 contract details.
- backend/
- Rust project (Cargo.toml) structured by models/ (ORM), routes/ (Express-style handlers), and main.rs.
- Uses Shuttle.rs for deployment and PostgreSQL schema.sql.
- snip721/
- CosmWasm contract in Rust, following SNIP-721 NFT standard.
- Contains contract logic, messages, state, and unit/integration tests.
- Has its own build and CI pipeline (Makefile, .circleci, GitHub Actions).

##### Main Architectural Components
A. Frontend (SvelteKit SPA)
- Components: UI screens (login, register, groups, proposals, donations, NFT minting).
- Service Layer: api.js handles HTTP calls to the backend.
- Blockchain Integration: Keplr wallet injected into browser to sign transactions directly against the SNIP-721 contract on the Secret Network.
B. Backend API (Rust + PostgreSQL)
- API Endpoints: /auth, /groups, /group_members, /donations, /profile, /proposals.
- Data Layer: PostgreSQL (schema.sql) accessed via ORM models.
- Business Logic: user/group management, proposal approval workflows.
- Deployment: cargo shuttle for provisioning and running the service.
C. Smart Contract (CosmWasm SNIP-721)
- Contract Logic: instantiate, execute (mint, transfer), query NFT state, royalty logic.
- Deployed on Secret Network.
- Interactions: called by the frontend via wallet; contract code ID and hash stored in frontend .env.
D. External Services & Tools
- Secret Network full node(s) or RPC endpoint.
- Keplr wallet browser extension.
- Shuttle.rs platform for backend hosting and managed PostgreSQL instance.
- CI/CD pipelines (.circleci, GitHub Actions for contract and backend builds).

##### Relationships & Data Flows
- User → Frontend: UI interactions (login, proposing donations, viewing groups).
- Frontend ↔ Backend: REST over HTTPS (VITE_BACKEND_URL) for CRUD operations and authentication.
- Frontend + Keplr → Secret Network: submit transactions to the SNIP-721 contract (mint, query).
- Backend ↔ PostgreSQL: persistent storage of users, groups, proposals, approvals.
- Contract ↔ Blockchain State: NFT metadata and state kept on-chain.

##### Architectural Patterns & Design Principles
- Separation of Concerns: clearly split UI, server logic, and smart contract.
- MVC-like on the backend: models/, routes/, main.rs.
- Component-based UI with SvelteKit routes and reusable components.
- Hexagonal/Ports-and-Adapters feel: the blockchain and database are treated as external adapters.
- Secure, privacy-first design via Secret Network and SNIP-721 standard.

##### Essential Elements
- Clear component labels (e.g., “Donations API”, “MintNFT Component”).
- Callouts for key tech: SvelteKit, Rust, PostgreSQL, CosmWasm SNIP-721, Shuttle.rs, Keplr.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Off-Chain Layer"
        subgraph "Frontend (SvelteKit UI)"
            UI["SvelteKit UI"]:::frontend
            Components["UI Components"]:::frontend
            Routes["Route Definitions"]:::frontend
            Service["api.js Service Layer"]:::frontend
            Env[".env Configuration"]:::frontend
        end
        subgraph "Backend API (Rust Shuttle REST API)"
            API["Rust Shuttle REST API"]:::backend
            Auth["Auth Route (/auth)"]:::backend
            Groups["Groups Route (/groups)"]:::backend
            Members["Group Members Route (/group_members)"]:::backend
            Donations["Donations Route (/donations)"]:::backend
            Profile["Profile Route (/profile)"]:::backend
            Models["ORM Models"]:::backend
            Schema["Database Schema (schema.sql)"]:::backend
            Main["Entry Point (main.rs)"]:::backend
            Cargo["Cargo Configuration"]:::backend
        end
    end

    DB["PostgreSQL"]:::db

    subgraph "On-Chain Layer"
        RPC["Secret Network RPC"]:::onchain
        subgraph "Smart Contract (CosmWasm SNIP-721)"
            ContractEntry["contract.rs"]:::onchain
            Msg["msg.rs"]:::onchain
            State["state.rs"]:::onchain
            Royalties["royalties.rs"]:::onchain
            Token["token.rs"]:::onchain
            Inventory["inventory.rs"]:::onchain
            Expiration["expiration.rs"]:::onchain
            Receiver["receiver.rs"]:::onchain
            TestsInt["integration tests"]:::onchain
            TestsUnit["unit tests"]:::onchain
            SchemaDef["schema definitions"]:::onchain
        end
    end

    Keplr["Keplr Wallet"]:::external
    Shuttle["Shuttle.rs"]:::external
    CIContract["CircleCI & GH Actions (Contract)"]:::external
    CIBackend["CI/CD (Backend)"]:::external

    UI -->|"uses"| Components
    UI -->|"renders"| Routes
    UI -->|"calls"| Service
    UI -->|"HTTP REST"| API
    Service -->|"HTTP REST"| API
    API -->|"SQL"| DB
    API -->|"deployed via"| Shuttle
    Shuttle --> DB
    API -->|"CI/CD"| CIBackend

    UI -->|"signed Txn (CW-WASM)"| RPC
    Keplr -->|"signs Txn"| RPC
    RPC -->|"query responses"| UI

    RPC -->|"invokes"| ContractEntry
    ContractEntry --> Msg
    ContractEntry --> State
    ContractEntry --> Royalties
    ContractEntry --> Token
    ContractEntry --> Inventory
    ContractEntry --> Expiration
    ContractEntry --> Receiver
    ContractEntry --> TestsInt
    ContractEntry --> TestsUnit
    ContractEntry --> SchemaDef
    CIContract -.-> ContractEntry

    click UI "https://github.com/juan-lukeklopper/philanthropymatrix/tree/main/frontend/src"
    click Components "https://github.com/juan-lukeklopper/philanthropymatrix/tree/main/frontend/src/lib/components"
    click Routes "https://github.com/juan-lukeklopper/philanthropymatrix/tree/main/frontend/src/routes"
    click Service "https://github.com/juan-lukeklopper/philanthropymatrix/blob/main/frontend/src/lib/services/api.js"
    click Env "https://github.com/juan-lukeklopper/philanthropymatrix/blob/main/frontend/.env-example"
    click API "https://github.com/juan-lukeklopper/philanthropymatrix/tree/main/backend/src"
    click Main "https://github.com/juan-lukeklopper/philanthropymatrix/blob/main/backend/src/main.rs"
    click Models "https://github.com/juan-lukeklopper/philanthropymatrix/tree/main/backend/src/models"
    click Auth "https://github.com/juan-lukeklopper/philanthropymatrix/blob/main/backend/src/routes/auth.rs"
    click Groups "https://github.com/juan-lukeklopper/philanthropymatrix/blob/main/backend/src/routes/groups.rs"
    click Members "https://github.com/juan-lukeklopper/philanthropymatrix/blob/main/backend/src/routes/group_members.rs"
    click Donations "https://github.com/juan-lukeklopper/philanthropymatrix/blob/main/backend/src/routes/donations.rs"
    click Profile "https://github.com/juan-lukeklopper/philanthropymatrix/blob/main/backend/src/routes/profile.rs"
    click Schema "https://github.com/juan-lukeklopper/philanthropymatrix/blob/main/backend/schema.sql"
    click Cargo "https://github.com/juan-lukeklopper/philanthropymatrix/blob/main/backend/Cargo.toml"
    click ContractEntry "https://github.com/juan-lukeklopper/philanthropymatrix/blob/main/snip721/src/contract.rs"
    click Msg "https://github.com/juan-lukeklopper/philanthropymatrix/blob/main/snip721/src/msg.rs"
    click State "https://github.com/juan-lukeklopper/philanthropymatrix/blob/main/snip721/src/state.rs"
    click Royalties "https://github.com/juan-lukeklopper/philanthropymatrix/blob/main/snip721/src/royalties.rs"
    click Token "https://github.com/juan-lukeklopper/philanthropymatrix/blob/main/snip721/src/token.rs"
    click Inventory "https://github.com/juan-lukeklopper/philanthropymatrix/blob/main/snip721/src/inventory.rs"
    click Expiration "https://github.com/juan-lukeklopper/philanthropymatrix/blob/main/snip721/src/expiration.rs"
    click Receiver "https://github.com/juan-lukeklopper/philanthropymatrix/blob/main/snip721/src/receiver.rs"
    click TestsInt "https://github.com/juan-lukeklopper/philanthropymatrix/blob/main/snip721/tests/integration.rs"
    click TestsUnit "https://github.com/juan-lukeklopper/philanthropymatrix/blob/main/snip721/src/unittest_*.rs"
    click SchemaDef "https://github.com/juan-lukeklopper/philanthropymatrix/tree/main/snip721/schema"
    click CIContract "https://github.com/juan-lukeklopper/philanthropymatrix/tree/main/snip721/Makefile"
    classDef frontend fill:#AED6F1,stroke:#21618C,color:#1B2631
    classDef backend fill:#D6EAF8,stroke:#1B4F72,color:#1B2631
    classDef db fill:#A9DFBF,stroke:#196F3D,color:#1B2631
    classDef onchain fill:#ABEBC6,stroke:#1D8348,color:#1B2631
    classDef external fill:#D5D8DC,stroke:#566573,color:#1B2631
```
