# geobrowser/geogenesis architecture

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

- Interactive diagram: https://gitdiagram.com/geobrowser/geogenesis
- Repository: https://github.com/geobrowser/geogenesis

## Overview

##### Project Type and Purpose
- Geo Genesis is a full-stack, web3-enabled dApp for adding to and querying a decentralized knowledge graph.
- It comprises a React/Next.js frontend, a GraphQL API backend, a blockchain-event processing pipeline (Substreams + sink), a Postgres database, on-chain smart contracts, and integrations with IPFS and Ethereum.

##### Top-Level Components
- Frontend (apps/web): Next.js app with UI pages, client-side data fetching, and serverless API routes for IPFS uploads, space deployment, telemetry, and metrics.
- API Server (packages/api): GraphQL server that directly reads from Postgres (via Zapatos) and exposes read models of spaces, entities, proposals, etc.
- Substream Processor (packages/substream): Rust & TypeScript modules running in the Substreams runtime. Listens to Ethereum events, decodes blocks, maps operations, and emits structured data.
- Substream Sink (packages/substream/sink): Takes Substreams output, writes normalized tables (blocks, entities, spaces, edits, proposals) into Postgres.
- Database (Postgres): Stores all read and write-side models (triples, versions, spaces, members, proposals).
- On-chain Smart Contracts: Deployed to Ethereum; govern Spaces, Entities, Proposals, Membership, and Governance logic.
- External Services: Ethereum Network (RPC), IPFS for file storage, optional Graph Node (via docker/Graph.Dockerfile) if leveraging The Graph.

##### Key Data Flows & Interactions
- User → Frontend UI: React components call client APIs and Web3 (via SDK) to read data and submit transactions.
- Frontend → GraphQL API: SSR/data-fetching uses the API server to query Postgres.
- Frontend → Serverless API Routes: Upload to IPFS, deploy new Space contracts, record telemetry/metrics.
- Frontend → Ethereum: On-chain write transactions via injected wallet (MetaMask/Smart Account).
- Ethereum → Substreams: Substream processor ingests new blocks/events from on-chain.
- Substreams → Sink → Postgres: Decoded events and operations written to normalized tables.
- API Server → Postgres: Read-side GraphQL queries resolve via direct SQL (Zapatos).

##### Architectural Patterns & Principles
- Microservices / Modular monorepo: Separate concerns into frontend, API, SDK, and blockchain pipeline packages.
- Event-streaming (Substreams): Decouple on-chain event ingestion from read models.
- CQRS-style split: Write-side (Ethereum & Substreams pipeline) vs Read-side (Postgres + GraphQL).
- Serverless functions (Next.js API routes) co-located with UI for IPFS, telemetry, bootstrap flows.
- Typed cross-service contracts: SDK, ABIs, and Proto definitions ensure consistency.

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Services
    Eth["Ethereum RPC\n(JSON-RPC)"]:::external
    IPFS["IPFS"]:::external

    %% Frontend Layer
    subgraph "Frontend Layer"
        UI["React/Next.js UI"]:::service
        APIRoutes["Serverless API Routes"]:::service
        SDKClient["SDK (ABIs & Helpers)"]:::library
    end

    %% API Server
    API["GraphQL API Server"]:::service

    %% Substreams Pipeline
    subgraph "Substreams Pipeline"
        Processor["Substream Processor"]:::service
        Sink["Substream Sink"]:::service
        Migrations["SQL & Migrations"]:::library
        Zapatos["Zapatos Schema"]:::library
    end

    %% Ontology Bootstrap
    Ontology["Ontology Bootstrap Scripts"]:::library

    %% Database
    DB["Postgres DB"]:::db

    %% CI / Docker Config
    CI["Docker & CI Config"]:::library

    %% Connections: Read Path
    UI -->|"GraphQL queries\nfetchSpacesById()"| API
    API -->|"SQL (Zapatos)"| DB

    %% Connections: Write Path
    UI -->|"Transactions\ndeploySpace()"| Eth
    Eth -->|"Substreams events\nhandleNewBlock()"| Processor
    Processor -->|"emit events"| Sink
    Sink -->|"writes normalized tables"| DB

    %% IPFS Upload
    APIRoutes -->|"IPFS Upload"| IPFS

    %% SDK Usage
    UI -->|"uses"| SDKClient
    Processor -->|"uses ABIs"| SDKClient

    %% Ontology Bootstrap Flow
    Ontology -->|"initial data"| DB

    %% CI Config pointing to Docker files
    CI --> API
    CI --> Processor

    %% Click Events
    click UI "https://github.com/geobrowser/geogenesis/tree/master/apps/web"
    click APIRoutes "https://github.com/geobrowser/geogenesis/tree/master/apps/web/app/api"
    click SDKClient "https://github.com/geobrowser/geogenesis/tree/master/packages/sdk"
    click API "https://github.com/geobrowser/geogenesis/tree/master/packages/api/src"
    click Processor "https://github.com/geobrowser/geogenesis/tree/master/packages/substream/src"
    click Processor "https://github.com/geobrowser/geogenesis/blob/master/packages/substream/index.ts"
    click Sink "https://github.com/geobrowser/geogenesis/tree/master/packages/substream/sink"
    click Migrations "https://github.com/geobrowser/geogenesis/tree/master/packages/substream/sink/sql"
    click Zapatos "https://github.com/geobrowser/geogenesis/tree/master/packages/substream/sink/zapatos"
    click SDKClient "https://github.com/geobrowser/geogenesis/tree/master/packages/sdk/src/abis"
    click Processor "https://github.com/geobrowser/geogenesis/tree/master/packages/substream/abis"
    click Ontology "https://github.com/geobrowser/geogenesis/tree/master/packages/ontology/src/bootstrap"
    click CI "https://github.com/geobrowser/geogenesis/blob/master/docker-compose.yml"

    %% Styles
    classDef service fill:#bbdefb,stroke:#1e88e5,stroke-width:2px;
    classDef external fill:#ffe0b2,stroke:#fb8c00,stroke-width:2px;
    classDef db fill:#c8e6c9,stroke:#43a047,stroke-width:2px;
    classDef library fill:#d1c4e9,stroke:#8e24aa,stroke-width:2px;
```
