# vidyutchakrabarti/tracex architecture

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

- Interactive diagram: https://gitdiagram.com/vidyutchakrabarti/tracex
- Repository: https://github.com/vidyutchakrabarti/tracex

## Overview

##### Project Type and Purpose
- Full-stack decentralized application (DApp) for evidence management in courts
- Next.js 13 “app” directory (React · server and client components)
- On-chain anchor of evidence hashes, off-chain metadata, Google/Firebase services

##### Main Architectural Components
- Frontend (Next.js React UI)
- Backend (Next.js Serverless API routes)
- Off-chain Database (MongoDB via utils/dbConnect.js or Firestore via utils/firebase.ts)
- Ethereum (Sepolia testnet) – smart contracts, const/contract-abi.ts
- Validation Service
– Python agents (tracex_agents) scrape events from Sepolia
– Sink to Google BigQuery
– Next.js /api/auditTrail routes query BigQuery to validate evidence hashes
- External Services
– Firebase Auth & Cloud Storage
– Google Maps & Earth Engine
– Gemini AI, Agents ADK, TTS, Translate
– BigQuery

##### Relationships & Data Flows
- User → Frontend UI → Backend API → DB / Blockchain
- Validation Request (/api/auditTrail) → BigQuery → Sepolia → compare → response
- Python Agent (cron/worker) → Sepolia → BigQuery (continuous ingestion)
- File uploads → Firebase Storage → metadata in DB → on-chain hash write via EthereumService

##### Important Architectural Patterns
- **Serverless API** (Next.js Route Handlers)
- **Cron/Agent-based ingestion** (Python)
- **Event sourcing** on blockchain + store & forward to BigQuery
- **Real-time & batch validation**: API queries BigQuery; Agent writes continuously

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% Subgraphs
  subgraph "Frontend (Next.js / React)"
    UI["Browser / Mobile UI"] 
  end

  subgraph "Backend (Next.js Serverless API)"
    API["/api/..."] 
    ETHSvc["EthereumService"] 
    DB["MongoDB / Firestore"] 
    FBAuth["Firebase Auth"] 
    FBStorage["Firebase Cloud Storage"] 
    BigQueryAPI["BigQuery Client"] 
  end

  subgraph "Blockchain Layer"
    Contracts["Smart Contracts"] 
    Sepolia["Sepolia Testnet"] 
  end

  subgraph "Validation Agents"
    PyAgent["Python Agent"] 
    BQIngest["BigQuery Ingestion"] 
  end

  subgraph "External Google Services"
    Maps["Google Maps"] 
    EarthEng["Earth Engine"] 
    Gemini["Gemini AI"] 
    ADK["Agents ADK"] 
    TTS["Text-to-Speech"] 
    Translate["Google Translate"] 
  end

  %% Flows
  UI -->|REST/GraphQL| API
  API -->|read/write| DB
  API -->|auth calls| FBAuth
  UI -->|file upload| FBStorage
  UI -->|map embed| Maps
  UI -->|earth data| EarthEng
  UI -->|AI chat| Gemini
  UI -->|voice commands| ADK
  UI -->|tts request| TTS
  UI -->|translate UI| Translate

  API -->|sign & send tx| ETHSvc
  ETHSvc -->|tx to| Contracts
  Contracts -->|events| Sepolia
  Sepolia -->|events polled| PyAgent

  PyAgent -->|write events| BQIngest
  BQIngest -->|ingest| BigQueryAPI
  API -->|query validation| BigQueryAPI
  BigQueryAPI -->|hash records| API
  API -->|compare & respond| UI

  %% Click Events
  click UI "https://github.com/vidyutchakrabarti/tracex/tree/latest/app/"
  click API "https://github.com/vidyutchakrabarti/tracex/tree/latest/app/api/"
  click ETHSvc "https://github.com/vidyutchakrabarti/tracex/blob/latest/utils/ethereumService.ts"
  click DB "https://github.com/vidyutchakrabarti/tracex/blob/latest/utils/dbConnect.js"
  click FBAuth "https://github.com/vidyutchakrabarti/tracex/blob/latest/utils/firebase.ts"
  click Contracts "https://github.com/vidyutchakrabarti/tracex/blob/latest/const/contract-abi.ts"
  click PyAgent "https://github.com/vidyutchakrabarti/tracex/blob/latest/tracex_agents/address_provider/agent.py"
  click BQIngest "https://github.com/vidyutchakrabarti/tracex/blob/latest/tracex_agents/api.py"
  click BigQueryAPI "https://github.com/vidyutchakrabarti/tracex/blob/latest/app/api/auditTrail/route.js"

  %% Styles
  classDef service fill:#E8F1FF,stroke:#4A90E2,stroke-width:2px;
  classDef data fill:#FFF5E6,stroke:#F5A623,stroke-width:2px;
  classDef external fill:#E7FFE8,stroke:#7ED321,stroke-width:2px;

  class API,ETHSvc,PyAgent,BQIngest,Contracts service;
  class DB,FBAuth,FBStorage,BigQueryAPI data;
  class UI,Sepolia,Maps,EarthEng,Gemini,ADK,TTS,Translate external;
```
