# naman22a/solguardian architecture

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

- Interactive diagram: https://gitdiagram.com/naman22a/solguardian
- Repository: https://github.com/naman22a/solguardian

## Overview

##### Project type and purpose
- This is a full-stack web application called **SolGuardian**, whose purpose is to provide AI-powered, context-aware auditing of Solidity smart contracts.
- It offers a React/Next.js frontend, an Express backend that orchestrates static analysis + LLM reasoning (CodeLlama via Ollama/​LangChain), and a separate worker process for heavy analysis tasks.

##### File structure
- Top-level split:
· **client/** – Next.js 15 (App Router) TypeScript frontend, TailwindCSS, Shadcn UI, Zustand, socket.io-client, react-dropzone.
· **server/** – Express 5 TypeScript API, Multer file uploads, socket.io for real-time, BullMQ queue, Redis, LangChain + CodeLlama integration, worker.ts for background processing.
· **data/** – static datasets (vulnerabilities.json, CSV versions, training dataset) used by static analysis routines.
- Deployment / infra config: docker-compose.yml (spins up Redis), .env examples for config, tsconfig.json, build & run scripts in package.json.

##### README for additional insights
- Tech stack confirms components: Redis as cache/message broker, BullMQ queue, CodeLlama & LangChain modules, Ollama as local LLM host.
- There is no traditional RDBMS; intermediate data lives in Redis, local filesystem (uploads), and static JSON.

a. Main components:
1. Frontend (Next.js)
2. Backend API (Express server)
3. Redis (cache & BullMQ broker)
4. Worker process (BullMQ consumer)
5. AI Engine (Ollama-hosted CodeLlama accessed via LangChain)
6. Static Data Store (data/vulnerabilities.json, dataset CSVs)
7. File Storage (server/uploads)
8. External tools (Docker-Compose, environment config)
b. Relationships & interactions:
- User → Frontend: HTTP/HTTPS form upload and dashboard.
- Frontend → Backend:
- HTTP POST for file upload (/upload via Multer)
- socket.io for push-based processing status & final results
- Backend → Redis/BullMQ: enqueue audit job
- Worker → Redis/BullMQ: dequeue job
- Worker → AI Engine: send code snippets to CodeLlama through LangChain API calls
- Worker → Static Data: consult vulnerabilities.json and scoring heuristics
- Worker → Backend: push results back (e.g., via Redis events or direct socket.io emit)
- Backend → Frontend: deliver structured JSON report via socket.io or REST fetch
c. Architectural patterns & principles:
- Separation of concerns: UI vs API vs background processing
- Queue-based asynchronous processing (BullMQ + Redis)
- Pub/Sub for real-time updates (socket.io backed by Redis adapter if scaled)
- Local LLM invocation (Ollama) with thin API wrapper (LangChain)
- Static assets and configs managed alongside code
d. Key technologies highlighted:
- Next.js 15 + Turbopack, Zustand, Shadcn UI, TailwindCSS
- Express 5 (TS), Multer, Zod, Socket.io, BullMQ, ioredis
- LangChain (Community, Core, Ollama modules), CodeLlama, Ollama CLI
- Docker-Compose for Redis, pnpm monorepo tooling

- Rounded rectangles for services (Client, API, Worker).
- UI (blue), Backend (green), Processing (orange), Data (gray), External (purple).

##### Detail without overthinking
- Every data flow: from user file upload → job enqueue → LLM call → result deliver.
- Environment/config (Docker-Compose, .env) and static dataset sit on the side as supporting resources.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Layers and components
    subgraph "Client Layer"
        direction TB
        FC["Frontend (Next.js)"]:::frontend
    end

    subgraph "Backend Layer"
        direction TB
        API["API Server (Express)"]:::backend
    end

    subgraph "Processing Layer"
        direction TB
        Worker["Worker Process (BullMQ)"]:::processing
    end

    subgraph "Data Layer"
        direction TB
        Redis["Redis Cache & Queue"]:::data
        StaticData["Static Data Store"]:::data
        UploadFS["File Storage (Uploads)"]:::data
    end

    subgraph "External Services"
        direction TB
        AIEngine(["AI Engine\n(Ollama + CodeLlama)"]):::external
    end

    subgraph "Config & Deployment"
        direction TB
        EnvClient["client/.env.example"]:::config
        EnvServer["server/.env.example"]:::config
        DockerServer["server/docker-compose.yml"]:::config
        DockerRoot["docker-compose.yml"]:::config
    end

    %% User interaction
    User["User"]:::external
    User -->|Uses UI| FC
    FC -->|HTTP POST /upload| API
    FC -.->|WebSocket events| API

    %% Backend to data/queue
    API -->|enqueue job| Redis
    Redis -.->|queue job| Worker

    %% Worker processing flows
    Worker -->|dequeue job| Redis
    Worker -->|call LLM| AIEngine
    Worker -->|read static data| StaticData
    Worker -->|read uploads| UploadFS
    Worker -->|push results| API

    %% Backend to frontend updates
    API -->|REST/WS response| FC

    %% Click events
    click FC "https://github.com/naman22a/solguardian/tree/master/client/"
    click API "https://github.com/naman22a/solguardian/blob/master/server/src/app.ts"
    click Redis "https://github.com/naman22a/solguardian/blob/master/server/src/redis.ts"
    click Worker "https://github.com/naman22a/solguardian/blob/master/server/src/worker.ts"
    click AIEngine "https://github.com/naman22a/solguardian/blob/master/server/src/utils/index.ts"
    click StaticData "https://github.com/naman22a/solguardian/tree/master/data/"
    click UploadFS "https://github.com/naman22a/solguardian/tree/master/server/uploads/"
    click EnvClient "https://github.com/naman22a/solguardian/blob/master/client/.env.example"
    click EnvServer "https://github.com/naman22a/solguardian/blob/master/server/.env.example"
    click DockerServer "https://github.com/naman22a/solguardian/blob/master/server/docker-compose.yml"
    click DockerRoot "https://github.com/naman22a/solguardian/blob/master/docker-compose.yml"

    %% Styles
    classDef frontend fill:#e0f2ff,stroke:#0066cc,stroke-width:1px;
    classDef backend fill:#e6ffed,stroke:#009900,stroke-width:1px;
    classDef processing fill:#fff4e6,stroke:#ff6600,stroke-width:1px;
    classDef data fill:#f0f0f0,stroke:#666666,stroke-width:1px;
    classDef external fill:#f3e6ff,stroke:#9900cc,stroke-width:1px;
    classDef config fill:#fff7cc,stroke:#cccc00,stroke-width:1px;
```
