# blockchain-kami/lensview-beta architecture

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

- Interactive diagram: https://gitdiagram.com/blockchain-kami/lensview-beta
- Repository: https://github.com/blockchain-kami/lensview-beta

## Overview

##### Project Type & Purpose
- This is a full-stack Web3 application (“LensView”) that brings a decentralized comment layer to any webpage.
- It comprises three main pieces:
– A monolithic Node.js GraphQL backend (handles URL indexing, comment‐summaries, on-chain broadcasts, caching).
– A Svelte-based browser extension (popup UI for “in-page” commenting).
– A SvelteKit web application (full-page UI for search, profile, post threads).
- The entire system leverages the Lens Protocol GraphQL API, Polygon blockchain, IPFS for assets, AI services for summarization, and MongoDB for caching.

##### File-Structure–Driven Architecture
- Top-level folders:
– /backend: GraphQL server, controllers/services/utils, Dockerfile, MongoDB connection, jobs (puppeteer + IPFS + AI).
– /extension: Svelte popup UI, shared GraphQL fragments and queries, GraphQL codegen, browser manifest.
– /web-app: SvelteKit application, routes, components, GraphQL codegen, REST/axios services to “backend,” direct Lens GraphQL calls.
- Patterns & layers (backend):
– “src/controllers → src/services → src/utils” (MVC/clean-architecture).
– “src/graphql/schema + codegen.ts” drives GraphQL resolvers.
– “jobs” invocations for screenshot+IPFS.
– Environment/config modules for AI (Gemini, Ayfie), puppeteer, thirdweb clients.

##### Key Components
- Browser Extension (Svelte) – popup UI → GraphQL queries/mutations + REST calls to backend.
- Web Application (SvelteKit) – SPA pages → Lens Protocol GraphQL + backend REST for summarization, URL management.
- GraphQL Gateway – merges project schema (schema.graphql) with Lens Protocol GraphQL operations (via gql client).
- Controllers & Services – handle business logic (authenticate, create-post, comment, summary).
- Job Queue Modules – puppeteer screenshot, IPFS upload, AI summarization.
- Configuration modules – MongoDB connection, thirdweb client (signing), polygon-gas API.
- MongoDB – stores URL-metadata, comment summaries, publication records.
- Lens Protocol GraphQL API – on-chain social graph.
- Polygon Gas Price API.
- IPFS – storing images/screenshots.
- AI Summarization (Gemini, Ayfie).
- Puppeteer – headless browser for screenshot.
- ThirdWeb – wallet/sign-typed-data client.

1. User → Extension/Web-App UI: triggers login (challenge query) and obtains access token via Lens GraphQL.
2. UI → Lens Protocol: directly perform “authenticate,” “create-typed-data,” “broadcast” operations.
3. UI → Backend (REST or GraphQL):
– add-URL (URL indexing), request comment summaries, validate URL existence.
– subscribe to WebSocket (if implemented) or poll for summary/jobs status.
4. Backend → MongoDB: persist metadata and summary caches.
5. Backend → AI Services: request text-summary generation.
6. Backend → Puppeteer + IPFS: generate screenshot, upload to IPFS, return URI.
7. Backend → Lens Protocol: broadcast on-chain transactions for comments/posts via signed typed-data.
8. UI ← Lens Protocol / Backend: fetch published comments, publications, comment summaries.

##### Architectural Patterns & Principles
- Clean Separation of Concerns: controllers, services, and utils in backend.
- Shared GraphQL Fragments & Codegen: reduces duplication between extension & web-app.
- Monolithic Backend: single codebase handles all business, integration, and persistence.
- Event/Job-Driven Tasks: screenshot + IPFS + AI summarization offloaded to “jobs” layer.

##### Essential Elements
- Clear demarcation: UI layer, API layer, persistence & jobs layer, external blockchain & services.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontends"
        direction TB
        subgraph "Browser Extension" 
            direction TB
            ExtUI["Popup UI (Svelte)"]:::frontend
            ExtCodegen["GraphQL Codegen"]:::frontend
            ExtGQL["GraphQL Fragments"]:::frontend
            ExtManifest["Manifest & Config"]:::frontend
        end
        subgraph "Web Application" 
            direction TB
            WebPages["SvelteKit Pages"]:::frontend
            WebComponents["Components Library"]:::frontend
            WebCodegen["GraphQL Codegen"]:::frontend
            WebGQL["GraphQL Fragments"]:::frontend
            WebServices["REST/Axios Services"]:::frontend
        end
    end

    %% Backend API Server
    subgraph "Backend API Server" 
        direction TB
        GraphQLGateway["GraphQL Gateway\n(Node.js/Express)"]:::backend
        ControllersServices["Controllers & Services"]:::backend
        JobQueue["Job Queue Modules\n(puppeteer, IPFS, AI)"]:::backend
        ConfigModules["Config Modules"]:::backend
        Connections["Connections\n(ThirdWeb, Mongo)"]:::backend
        ABIs["Contract ABIs"]:::backend
    end

    %% Database
    subgraph "Persistence & Cache"
        direction TB
        MongoDB["MongoDB"]:::database
    end

    %% External Services
    subgraph "External Services"
        direction TB
        LensAPI["Lens Protocol GraphQL API"]:::external
        PolygonGas["Polygon Gas Price API"]:::external
        IPFS["IPFS"]:::external
        AIService["AI Summarization\n(Gemini, Ayfie)"]:::external
        Puppeteer["Puppeteer"]:::external
        ThirdWeb["ThirdWeb Client"]:::external
    end

    %% User
    User["User"]:::external

    %% Interactions & Data Flow
    User -->|1. interact/login| ExtUI
    User -->|1. interact/login| WebPages

    ExtUI -->|2. authenticate/createTypedData/broadcast| LensAPI
    WebPages -->|2. authenticate/createTypedData/broadcast| LensAPI

    ExtUI -->|3. add-URL/request summary| GraphQLGateway
    WebPages -->|3. add-URL/request summary| GraphQLGateway

    GraphQLGateway -->|invoke business logic| ControllersServices
    ControllersServices -->|4. persist metadata & cache| MongoDB
    ControllersServices -->|5. request summarization| AIService
    ControllersServices -->|6. enqueue screenshot job| JobQueue
    ControllersServices -->|7. broadcast on-chain| LensAPI
    ControllersServices -->|get gas price| PolygonGas

    JobQueue -->|use headless browser| Puppeteer
    Puppeteer -->|upload screenshot| IPFS
    JobQueue -->|store job metadata| MongoDB

    GraphQLGateway -->|load config| ConfigModules
    GraphQLGateway -->|init modules| Connections
    Connections -->|load ABIs| ABIs

    %% Responses
    LensAPI -->|8. return published data| ExtUI
    LensAPI -->|8. return published data| WebPages
    MongoDB -->|8. return cached summaries| GraphQLGateway

    %% Click Events
    click ExtUI "https://github.com/blockchain-kami/lensview-beta/blob/master/extension/src/popup/Popup.svelte"
    click ExtCodegen "https://github.com/blockchain-kami/lensview-beta/blob/master/extension/codegen.ts"
    click ExtGQL "https://github.com/blockchain-kami/lensview-beta/tree/master/extension/src/gql"
    click ExtManifest "https://github.com/blockchain-kami/lensview-beta/blob/master/extension/manifest.config.ts"
    click WebPages "https://github.com/blockchain-kami/lensview-beta/blob/master/web-app/src/routes/+page.svelte"
    click WebRoutes "https://github.com/blockchain-kami/lensview-beta/tree/master/web-app/src/routes/"
    click WebComponents "https://github.com/blockchain-kami/lensview-beta/tree/master/web-app/src/components/"
    click WebCodegen "https://github.com/blockchain-kami/lensview-beta/blob/master/web-app/codegen.ts"
    click WebGQL "https://github.com/blockchain-kami/lensview-beta/tree/master/web-app/src/gql"
    click WebServices "https://github.com/blockchain-kami/lensview-beta/tree/master/web-app/src/services/app/"
    click BackendApp "https://github.com/blockchain-kami/lensview-beta/blob/master/backend/src/app.ts"
    click BackendSchema "https://github.com/blockchain-kami/lensview-beta/blob/master/backend/schema.graphql"
    click BackendSchemaCodegen "https://github.com/blockchain-kami/lensview-beta/blob/master/backend/codegen.ts"
    click BackendControllers "https://github.com/blockchain-kami/lensview-beta/tree/master/backend/src/controllers/"
    click BackendServices "https://github.com/blockchain-kami/lensview-beta/tree/master/backend/src/services/"
    click BackendUtils "https://github.com/blockchain-kami/lensview-beta/tree/master/backend/src/utils/"
    click BackendJobs "https://github.com/blockchain-kami/lensview-beta/tree/master/backend/src/jobs/"
    click BackendUtilsJobs "https://github.com/blockchain-kami/lensview-beta/tree/master/backend/src/utils/jobs/"
    click BackendConfig "https://github.com/blockchain-kami/lensview-beta/tree/master/backend/src/config/"
    click BackendConnections "https://github.com/blockchain-kami/lensview-beta/tree/master/backend/src/connections/"
    click MongoConn "https://github.com/blockchain-kami/lensview-beta/blob/master/backend/src/connections/mongo-db.connection.ts"
    click MongoModel "https://github.com/blockchain-kami/lensview-beta/blob/master/backend/src/models/db/publication.db.model.ts"
    click BackendAbis "https://github.com/blockchain-kami/lensview-beta/blob/master/backend/src/abis/lens-hub-contract.abi.json"

    %% Styles
    classDef frontend fill:#BBDEFB,stroke:#1E88E5,stroke-width:1px
    classDef backend fill:#C8E6C9,stroke:#388E3C,stroke-width:1px
    classDef database fill:#FFE0B2,stroke:#FB8C00,stroke-width:1px
    classDef external fill:#CFD8DC,stroke:#607D8B,stroke-width:1px
```
