# zero-abd/authlens architecture

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

- Interactive diagram: https://gitdiagram.com/zero-abd/authlens
- Repository: https://github.com/zero-abd/authlens

## Overview

##### Project Type and Purpose
- Full-stack blockchain-powered video authentication platform (“dApp”).
- React frontend (AuthLens-Frontend) for user interactions.
- Python FastAPI backend (backend/) for video chunk processing, hashing, blockchain calls and metadata storage.
- Solidity smart contract (contracts/VideoAuth.sol) deployed to Ethereum Sepolia via Hardhat/ignition.
- Purpose: split videos into 1-minute chunks, compute cryptographic hashes, store/check them on chain for tamper-proof verification and timestamping.

##### File Structure
- Top-level directories:
- AuthLens-Frontend/: React/TypeScript code, UI components, service layer.
- backend/: Python code (main.py, test_client.py), requirements.txt, local contract ABI (VideoAuth.json).
- contracts/: VideoAuth.sol.
- ignition/: TypeScript deployment modules using Hardhat-Ignition.
- db/: JSON files (ledger.json, remote_cameras.json) simulating/persisting chunk metadata.
- Config & scripts:
- hardhat.config.ts, package.json/tsconfig.json for Node/TypeScript build & deployment.
- FLOW_DIAGRAM.md hints at end-to-end flow.
- Test assets: test_videos/README.md.

##### Extract README Insights
- AuthLens uses Alchemy/Infura as RPC providers.
- MetaMask on frontend for transaction signing.
- FastAPI exposes three main endpoints: process-chunk, verify, range.
- Deployment via `npx hardhat ignition deploy … --network sepolia`.
- Local JSON DB used for quick range queries.

##### Main Components
a. User Layer
- Browser + MetaMask plugin (Sepolia wallet).
b. Presentation Layer
- React App (AuthLens-Frontend).
c. API Layer
- FastAPI Server (backend/main.py).
d. On-Chain Layer
- Ethereum Sepolia Network
- VideoAuth smart contract
e. Infrastructure & Tools
- Hardhat/Ignition (deployment)
- Alchemy/Infura RPC node
f. Data Storage
- Local JSON “DB” (db/ledger.json & db/remote_cameras.json)

##### Relationships and Data Flow
- User → React UI: video selection, “upload chunk”, “verify”, “fetch range”.
- React → FastAPI (HTTP/REST endpoints):
- POST /api/video/process-chunk: sends file + timestamps.
- POST /api/video/verify: sends file for on-chain check.
- GET /api/video/range: requests chunk metadata.
- FastAPI → Local JSON DB: read/write chunk metadata.
- FastAPI → Ethereum RPC (JSON-RPC via Web3/Ethers):
- sendTransaction(storeHash) with chunk hash.
- call verifyHash for existence check.
- Ethereum Node → Smart Contract: transactions and calls.
- Hardhat/Ignition (offline): deploys contract, produces ABI & deployed_addresses.json.

##### Architectural Patterns & Principles
- Clear separation of concerns: UI / API / blockchain storage.
- Stateless frontend; stateful backend with minimal local persistence.
- Eventual consistency: on-chain writes + off-chain metadata storage.
- Modular deployment: ignition modules isolate contract deployment logic.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Layer
    User["User (Browser + MetaMask)"]:::frontend

    %% Presentation Layer
    subgraph "Presentation Layer"
        React["React App"]:::frontend
    end

    %% API Layer
    subgraph "API Layer"
        FastAPI["FastAPI Server"]:::backend
        Requirements["requirements.txt"]:::backend
        TestClient["test_client.py"]:::backend
        TestParse["test_parse.py"]:::backend
    end

    %% Data Storage
    subgraph "Data Storage"
        Ledger["ledger.json"]:::db
        Cameras["remote_cameras.json"]:::db
    end

    %% RPC Provider
    RPC["RPC Provider (Alchemy/Infura)"]:::cloud

    %% On-Chain Layer
    subgraph "On-Chain Layer"
        Ethereum["Ethereum Sepolia Network"]:::blockchain
        Contract["VideoAuth Contract"]:::blockchain
        ContractABI["VideoAuth.json"]:::blockchain
    end

    %% Infrastructure & Tools
    subgraph "Infrastructure & Tools"
        Hardhat["hardhat.config.ts"]:::infra
        subgraph Ignition
            DeployMod["Deploy.ts"]:::infra
            DeployedAddrs["deployed_addresses.json"]:::infra
            Artifact["VideoAuthModule#VideoAuth.json"]:::infra
        end
        FlowDoc["FLOW_DIAGRAM.md"]:::infra
        PackageJson["package.json"]:::infra
        TsConfig["tsconfig.json"]:::infra
        LockFile["package-lock.json"]:::infra
    end

    %% Relationships
    User -->|"Interact"| React
    React -->|"POST JSON /api/video/process-chunk"| FastAPI
    React -->|"POST JSON /api/video/verify"| FastAPI
    React -->|"GET JSON /api/video/range"| FastAPI

    FastAPI -->|"read/write"| Ledger
    FastAPI -->|"read/write"| Cameras

    FastAPI -->|"sendTransaction"| RPC
    FastAPI -->|"call verifyHash"| RPC

    RPC -->|"tx & calls"| Contract
    Ethereum --> Contract

    Hardhat -->|"deploy"| Ethereum
    DeployMod -->|"deploy"| Ethereum
    Ethereum -->|"produce ABI & addresses"| DeployedAddrs
    Ethereum --> Artifact
    DeployedAddrs --> FastAPI
    Artifact --> FastAPI

    %% Click Events
    click React "https://github.com/zero-abd/authlens/tree/main/AuthLens-Frontend/"
    click FastAPI "https://github.com/zero-abd/authlens/blob/main/backend/main.py"
    click Requirements "https://github.com/zero-abd/authlens/blob/main/backend/requirements.txt"
    click TestClient "https://github.com/zero-abd/authlens/blob/main/backend/test_client.py"
    click TestParse "https://github.com/zero-abd/authlens/blob/main/backend/test_parse.py"
    click Contract "https://github.com/zero-abd/authlens/blob/main/contracts/VideoAuth.sol"
    click ContractABI "https://github.com/zero-abd/authlens/blob/main/backend/VideoAuth.json"
    click Ledger "https://github.com/zero-abd/authlens/blob/main/db/ledger.json"
    click Cameras "https://github.com/zero-abd/authlens/blob/main/db/remote_cameras.json"
    click Hardhat "https://github.com/zero-abd/authlens/blob/main/hardhat.config.ts"
    click DeployMod "https://github.com/zero-abd/authlens/blob/main/ignition/modules/Deploy.ts"
    click DeployedAddrs "https://github.com/zero-abd/authlens/blob/main/ignition/deployments/chain-11155111/deployed_addresses.json"
    click Artifact "https://github.com/zero-abd/authlens/blob/main/ignition/deployments/chain-11155111/artifacts/VideoAuthModule#VideoAuth.json"
    click FlowDoc "https://github.com/zero-abd/authlens/blob/main/FLOW_DIAGRAM.md"
    click PackageJson "https://github.com/zero-abd/authlens/blob/main/package.json"
    click TsConfig "https://github.com/zero-abd/authlens/blob/main/tsconfig.json"
    click LockFile "https://github.com/zero-abd/authlens/blob/main/package-lock.json"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#3399ff,stroke-width:1px
    classDef backend fill:#d4edda,stroke:#28a745,stroke-width:1px
    classDef db fill:#e2f0d9,stroke:#6aa84f,stroke-width:1px
    classDef cloud fill:#f0f0f0,stroke:#999999,stroke-width:1px,stroke-dasharray: 5 5
    classDef blockchain fill:#ffe6cc,stroke:#ff9933,stroke-width:1px
    classDef infra fill:#e5ccff,stroke:#9933ff,stroke-width:1px
```
