# saksham-tomer/solxpass architecture

> Architecture diagram of the GitHub repository saksham-tomer/solxpass, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/saksham-tomer/solxpass
- Repository: https://github.com/saksham-tomer/solxpass

## Overview

##### Project Overview
- This project is a full-stack decentralized identity and rewards platform built on the Solana blockchain.
- Its core purpose is to allow users to generate verifiable identity proofs (Proof of Person) across multiple categories, verify them on-chain using Zero-Knowledge Proofs and the Reclaim Protocol, and interact via a rewards and community system.
- The system also provides an SDK/npm package for dApp developers to integrate identity verification and rewards features.

##### Main Components
a. Frontend:
- The “app” directory houses the Next.js application with pages like dashboard, connect, explore, and feeds.
- UI components across directories (e.g., components/3D, components/Auth, components/Dashboard, etc.) indicate a rich user experience that includes 3D elements and interactive layouts.
- The navigation, authentication, and session management components found under components/Nav and lib contain logic for wallet connections (e.g., Phantom) and session providers.

b. Backend and API Layer:
- API routes under “app/api” implement endpoints for authentication, proof generation, balance checking, and updating user data.
- These endpoints serve as the glue between the frontend and the blockchain layer, handling interactions and business logic before triggering on-chain verification.

c. Blockchain Layer:
- The “blockchain” directory contains Rust projects and configurations (e.g., Cargo.toml, migrations, and programs under “programs/reclaim”).
- This part represents the on-chain smart contract (program) layer that handles identity proofs, validation, and rewards issuance on the Solana blockchain.
- The presence of a separate tests folder (blockchain/tests) shows dedicated testing of blockchain functionality.

d. Database & Data Management:
- The “prisma” directory indicates that the project uses Prisma ORM with defined migrations and schema for managing off-chain data (user records, proofs, reward tracking, etc.).
- This serves as the persistent layer for data not stored on-chain.

e. Configuration & Utility Libraries:
- The “config” and “lib” directories hold configuration files and utility functions (such as authentication, NFT minting, session management, and integration with Metaplex) that bridge components.
- These files indicate integration with external libraries/frameworks and centralize shared logic.

##### Relationships and Interactions
- Users interact with the frontend UI (Next.js app) which communicates with backend API endpoints for tasks such as submitting identity proofs, fetching reward data, and updating user profiles.
- The backend APIs process requests before:
- Interacting with the blockchain layer to submit and verify proofs through smart contracts.
- Accessing/storing additional user data via Prisma-managed databases.
- The blockchain smart contracts implement the core on-chain logic for decentralized verification, recording proofs, and rewards, all while interfacing with the Reclaim Protocol and Zero-Knowledge Proof systems.
- The SDK or npm package enables third-party dApp developers to hook into this flow.

##### Key Architectural Patterns and Design Principles
- Use of Next.js for routing and API endpoint creation (separation of frontend and backend concerns).
- Modular design with clear separation: UI components, API endpoints, blockchain programs, and data persistence.
- Integration of decentralized components (blockchain smart contracts) with traditional server-side resources (Prisma-backed database and REST-ish API endpoints) to achieve both on-chain security and off-chain performance.
- Emphasis on privacy and security via Zero-Knowledge Proofs and the Reclaim Protocol.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Actor
    User["User"]:::external

    %% Frontend Layer
    subgraph "Frontend Layer"
        FE["Frontend (Next.js App & UI Components)"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        API["Backend API Layer"]:::backend
        UTIL["Config & Utility Libraries"]:::utility
    end

    %% Blockchain Layer
    subgraph "Blockchain Layer"
        BC["Blockchain (Solana Smart Contracts & Tests)"]:::blockchain
    end

    %% Data Management Layer
    subgraph "Data Management"
        DB["Database (Prisma ORM)"]:::database
    end

    %% External Integration & SDK
    subgraph "External Integrations"
        ES["External Services (Reclaim Protocol,ZKProofs)"]:::external
        SDK["SDK/npm Package for dApp Integration"]:::sdk
    end

    %% Data Flow
    User -->|"access"| FE
    FE -->|"API_Request"| API
    API -->|"DB_Query/Update"| DB
    API -->|"On-Chain_Interaction"| BC
    BC -->|"Verification_Results"| API
    API -->|"Response_Data"| FE
    API -->|"dApp_Hook"| SDK
    FE ---|"Uses"| UTIL
    API ---|"Uses"| UTIL
    BC ---|"Util_Scripts"| UTIL
    API ---|"External_Calls"| ES
    BC ---|"External_Verification"| ES

    %% Click Events
    click FE "https://github.com/saksham-tomer/solxpass/tree/main/app"
    click FE "https://github.com/saksham-tomer/solxpass/tree/main/components"
    click API "https://github.com/saksham-tomer/solxpass/tree/main/app/api"
    click BC "https://github.com/saksham-tomer/solxpass/tree/main/blockchain"
    click DB "https://github.com/saksham-tomer/solxpass/tree/main/prisma"
    click UTIL "https://github.com/saksham-tomer/solxpass/tree/main/config"
    click UTIL "https://github.com/saksham-tomer/solxpass/tree/main/lib"

    %% Styles
    classDef frontend fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef backend fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef blockchain fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
    classDef database fill:#D7BDE2,stroke:#6C3483,stroke-width:2px;
    classDef utility fill:#AED6F1,stroke:#2980B9,stroke-width:2px;
    classDef external fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef sdk fill:#FDEBD0,stroke:#D35400,stroke-width:2px;
```
