How juan-lukeklopper/philanthropymatrix works
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.