# raul0ligma/obsidian architecture

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

- Interactive diagram: https://gitdiagram.com/raul0ligma/obsidian
- Repository: https://github.com/raul0ligma/obsidian

## Overview

##### Main Components
- Frontend – Built with Node.js and TypeScript (React/Vite stack) located in the frontend directory. This layer provides the user interface for interacting with the system.
- Server – A Rust-based backend (in the server directory) that exposes REST API endpoints, handles proof generation, and integrates with the zkVM.
- Program – The on-chain execution program that runs inside the SP1 zkVM (in the program directory). This component is responsible for verifying block data, executing Uniswap V2 swaps, and generating verifiable outputs.
- Library – The core shared functionality (in the lib directory) that contains modules for MPT verification, RLP decoding, swap execution, header processing, and state management.
- Contracts – Contains smart contracts and associated artifacts (in the contracts directory) that likely deploy on Ethereum, serving as an on-chain verification layer.
- Script – Contains additional Rust-based build and deployment scripts (in the script folder) for managing EVM or zkVM related tasks.

##### Relationships & Data Flow
- The Frontend communicates with the Server via REST API calls for actions such as proof generation or order submissions.
- The Server uses the functionalities exposed by the core Library to verify Ethereum state proofs and to interact with the Program.
- The Program runs within the SP1 zkVM environment where it verifies the provided MPT proofs, executes state transitions/swap logic, and generates zero-knowledge proofs.
- Smart Contracts serve as a bridge between on-chain data and off-chain computation; they may also be used for verifying the cryptographic proofs generated by the Program.
- Deployment/interaction flows can be assisted by the Scripts, which might handle the building, testing, and deploying of contracts or runtime artifacts.

##### Architectural Patterns & Technologies
- Modular layered architecture – Each main component (frontend, server, program, lib, contracts, script) is isolated by function.
- Microservices-ish separation – Even though all components are part of one repository, the separation between API logic, on-chain execution (program), and UI is clear.
- The use of smart contracts indicates blockchain integration, while the presence of a dedicated zkVM program means the system leverages trustless, zero-knowledge computation.
- Technologies: Rust for backend logic (server, lib, program, script), SP1 zkVM environment for zero-knowledge proof execution, and a modern JavaScript/TypeScript stack (Node.js with Vite/React) for the frontend. Additionally, Solidity (or similar) for the contracts library.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        FE["Frontend (React/Vite)"] 
    end

    %% Backend Layer
    subgraph "Backend Layer"
        SR["Server (Rust REST API)"]
        LB["Core Library (Rust: verifier,decoder,swapper, etc.)"]
    end

    %% Blockchain/zkVM Layer
    subgraph "Blockchain/zkVM Layer"
        PR["Program (SP1 zkVM Executor)"]
        CT["Smart Contracts (Ethereum)"]
    end

    %% Deployment Scripts
    subgraph "Deployment"
        SC["Build/Deployment Scripts"]
    end

    %% Data Flow
    FE -->|"REST_API"| SR
    SR -->|"Proof_Verification"| LB
    LB -->|"zkVM_Exec"| PR
    PR <-->|"On-chain_Verification"| CT
    SC -->|"Deploy"| PR
    SC -->|"Deploy"| CT

    %% Click Events
    click FE "https://github.com/raul0ligma/obsidian/tree/master/frontend/"
    click SR "https://github.com/raul0ligma/obsidian/tree/master/server/"
    click LB "https://github.com/raul0ligma/obsidian/tree/master/lib/"
    click PR "https://github.com/raul0ligma/obsidian/tree/master/program/"
    click CT "https://github.com/raul0ligma/obsidian/tree/master/contracts/"
    click SC "https://github.com/raul0ligma/obsidian/tree/master/script/"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef backend fill:#FFCC99,stroke:#000,stroke-width:2px;
    classDef library fill:#FFFF99,stroke:#000,stroke-width:2px;
    classDef program fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef contract fill:#F08080,stroke:#000,stroke-width:2px;
    classDef script fill:#D3D3D3,stroke:#000,stroke-width:2px;

    class FE frontend;
    class SR backend;
    class LB library;
    class PR program;
    class CT contract;
    class SC script;
```
