How geobrowser/geogenesis works
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.