# seed-hypermedia/seed architecture

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

- Interactive diagram: https://gitdiagram.com/seed-hypermedia/seed
- Repository: https://github.com/seed-hypermedia/seed

## Overview

##### Project Type and Purpose
- Seed is a full-stack, decentralized knowledge collaboration platform.
- It comprises:
- A Go-based P2P “daemon” (node) exposing gRPC/HTTP APIs, CRDT-powered storage, and libp2p networking.
- An Electron-based Desktop client (React/TypeScript) that talks to the local daemon.
- A NodeJS/Next-style Web server (“site”) providing a read-only portal to the network.
- Shared TypeScript packages (editor, ui, shared) used across frontend apps.
- Site deployments orchestrated via Docker-Compose.

##### File Structure Analysis
- Top-level directories:
- backend/ — Go code for P2P node, storage (SQLite), CRDT core, GRPC definitions, CLI commands.
- frontend/apps/ — multiple frontends: desktop (Electron), web (Next-style), landing, explore, performance dashboards, emails.
- frontend/packages/ — reusable TypeScript libraries (editor, shared models/clients, UI components).
- proto/ — .proto definitions driving codegen for Go and JS.
- build/, scripts/, dev/, monitoring/ — build tooling (Bazel, Please), CI/CD, monitoring stacks.
- Key configuration: Bazel/Please BUILD files, Dockerfiles for CLI daemons and web server, Nix and Direnv for dev environment.

##### README Insights
- Highlights two primary consumers: Seed Desktop and Seed Hypermedia Web Server.
- Emphasizes Hypermedia Web Protocol (custom P2P protocol).
- Describes dev commands (./dev), desktop vs. site workflows, group site deployment via website_deployment.sh.

a. Main Components
- Desktop Client
- Electron Main Process & Renderer Processes (React UI)
- Shared JS packages (editor, shared, ui)
- IPC/RPC layer (gRPC-Web or native GRPC over IPC) to Daemon
- Local Daemon (Go)
- P2P Networking (libp2p, hmnet)
- CRDT Document Core
- Storage Layer (SQLite DB, migrations)
- gRPC Services (documents, activity, payments, entities, networking, daemon health)
- HTTP/HTTPS endpoints (for Web App & monitoring)
- Web Server (Next-style NodeJS)
- HTTP Frontend (SSR/CSR React) under frontend/apps/web
- Data loaders calling local or remote gRPC endpoints via shared JS gRPC client
- Site Deployment
- Docker-Compose → containers: Go Daemon + NodeJS Web + Traefik (reverse proxy)
- Public P2P port (56000) open to hypermedia network
- External Systems
- P2P peers (other Seed nodes)
- IPFS DHT for content discovery
- Prometheus + Grafana for metrics (monitoring/ folder)

b. Relationships & Data Flows
- Desktop UI ↔ IPC/HTTP/gRPC ↔ Local Daemon
- Local Daemon ↔ P2P Network ↔ Other Seed Nodes
- Local Daemon persists to SQLite → CRDT state
- Web Server ↔ gRPC ↔ Local Daemon (or remote Daemon if running as site)
- Docker-Compose front-ends route HTTP requests to Web Server; Traefik routes P2P to Daemon

c. Architectural Patterns & Principles
- Microservices-style separation: frontends isolated from daemon API
- CRDT and event sourcing for offline-first collaboration
- Shared code via monorepo packages for consistency
- Protocol-first design (proto definitions driving both Go and JS codegen)
- Infrastructure as code (Bazel/Please, Nix, Docker)

d. Key Technologies & Frameworks
- Go, gRPC, Protocol Buffers, libp2p, SQLite
- Electron, React, TypeScript, Vite, TailwindCSS
- Next-style server (Remix-inspired routes) for web app
- Bazel/Please build system, Nix/Direnv dev env
- Docker-Compose, Traefik, Prometheus, Grafana

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Desktop Client
    subgraph "Desktop Client"
        direction TB
        Main["Electron Main Process"]:::frontend
        Renderer["Renderer Processes (React UI)"]:::frontend
        subgraph "IPC/RPC Layer"
            direction TB
            AppGRPC["app-grpc.ts"]:::frontend
            AppIPC["app-ipc.tsx"]:::frontend
            GRPCClient["grpc-client.ts"]:::frontend
        end
    end

    %% Local Daemon
    subgraph "Local Daemon (Go P2P Node)"
        direction TB
        DaemonCmd["seed-daemon/main.go"]:::backend
        Core["Daemon Core (daemon.go)"]:::backend
        HTTP["HTTP Gateway (http.go)"]:::backend
        GRPC["gRPC Services (backend/api)"]:::backend
        CRDTCore["CRDT Core"]:::backend
        Storage["Storage Layer (SQLite)"]:::datastore
        Blob["Blob & Blockstore"]:::backend
        HMNET["P2P Networking (hmnet)"]:::network
        IPFSNode["IPFS DHT Integration"]:::network
        MetricsNode["Metrics (metrics.go)"]:::backend
    end

    %% Web Server
    subgraph "Web Server (NextJS)"
        direction TB
        WebApp["SSR/CSR React (frontend/apps/web/app)"]:::frontend
        DockerWeb["Dockerfile"]:::backend
        PublicAssets["Public Assets"]:::frontend
    end

    %% Shared Packages
    subgraph "Shared TS Packages"
        direction TB
        Editor["editor"]:::frontend
        SharedPkg["shared"]:::frontend
        UI["ui"]:::frontend
    end

    %% Protobuf & Codegen
    subgraph "Protobuf Definitions"
        direction TB
        ProtoDefs[".proto Files"]:::network
        GenProto["Go Generated Stubs"]:::backend
    end

    %% Dev & Build Tooling
    subgraph "Dev & Build Tooling"
        direction TB
        Bazel1["BUILD.bazel"]:::backend
        Bazel2["BUILD.plz"]:::backend
        BuildRules["build/rules"]:::backend
        NixEnv["shell.nix"]:::backend
        Direnv[".envrc"]:::backend
        DevCmd["dev/"]:::backend
    end

    %% Group Site Deployment
    subgraph "Group Site Deployment"
        direction TB
        Compose["docker-compose.yml"]:::backend
        DeployScript["website_deployment.sh"]:::backend
        Traefik["Traefik Proxy"]:::network
    end

    %% Monitoring & Observability
    subgraph "Monitoring & Observability"
        direction TB
        MonCompose["monitoring/docker-compose.yaml"]:::backend
        PromConfig["prometheus.yaml"]:::backend
        Grafana["Grafana Dashboards"]:::backend
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        Peers["Other Seed Nodes"]:::external
        IPFSDHT["IPFS DHT"]:::external
    end

    %% Relationships
    Main -->|launches| AppGRPC
    Main -->|launches| AppIPC
    Renderer -->|uses| AppIPC
    AppIPC -->|IPC/gRPC| DaemonCmd
    AppGRPC -->|gRPC| DaemonCmd

    DaemonCmd -->|calls| Core
    Core --> CRDTCore
    CRDTCore --> Storage
    Core --> Blob
    Core --> HMNET
    Core --> IPFSNode
    Core --> HTTP
    Core --> MetricsNode
    Core --> GRPC

    WebApp -->|HTTP| HTTP
    WebApp -->|gRPC| GRPC
    DockerWeb --> WebApp
    PublicAssets --> WebApp

    Compose --> Traefik
    Compose --> DaemonCmd
    Compose --> WebApp
    Traefik -->|routes P2P| DaemonCmd
    Traefik -->|routes HTTP| WebApp

    PromConfig -->|configures| MonCompose
    Grafana -->|provisions| MonCompose
    MonCompose -->|deploys| PromConfig
    MonCompose -->|deploys| Grafana
    MonCompose -->|monitors| DaemonCmd

    Peers -->|P2P Mesh| HMNET
    IPFSDHT -->|DHT Lookup| IPFSNode

    Editor --> Renderer
    SharedPkg --> Main
    SharedPkg --> WebApp
    UI --> Renderer
    UI --> WebApp

    ProtoDefs -->|codegen| GenProto
    GenProto --> Core
    GenProto --> GRPC
    GenProto --> GRPC

    Bazel1 -->|build rules| Core
    Bazel2 -->|build rules| Core
    BuildRules -->|bazelrc| Bazel1
    NixEnv -->|env| DevCmd
    Direnv -->|env| DevCmd
    DevCmd -->|dev workflow| Main
    DevCmd -->|dev workflow| WebApp

    %% Click Events
    click Main "https://github.com/seed-hypermedia/seed/blob/main/frontend/apps/desktop/src/main.ts"
    click Renderer "https://github.com/seed-hypermedia/seed/tree/main/frontend/apps/desktop/src/pages"
    click AppGRPC "https://github.com/seed-hypermedia/seed/blob/main/frontend/apps/desktop/src/app-grpc.ts"
    click AppIPC "https://github.com/seed-hypermedia/seed/blob/main/frontend/apps/desktop/src/app-ipc.tsx"
    click GRPCClient "https://github.com/seed-hypermedia/seed/blob/main/frontend/apps/desktop/src/grpc-client.ts"
    click DaemonCmd "https://github.com/seed-hypermedia/seed/blob/main/backend/cmd/seed-daemon/main.go"
    click Core "https://github.com/seed-hypermedia/seed/blob/main/backend/daemon/daemon.go"
    click HTTP "https://github.com/seed-hypermedia/seed/blob/main/backend/daemon/http.go"
    click MetricsNode "https://github.com/seed-hypermedia/seed/blob/main/backend/daemon/metrics.go"
    click GRPC "https://github.com/seed-hypermedia/seed/tree/main/backend/api"
    click HMNET "https://github.com/seed-hypermedia/seed/tree/main/backend/hmnet"
    click IPFSNode "https://github.com/seed-hypermedia/seed/tree/main/backend/ipfs"
    click CRDTCore "https://github.com/seed-hypermedia/seed/tree/main/backend/crdt"
    click Storage "https://github.com/seed-hypermedia/seed/tree/main/backend/storage"
    click Blob "https://github.com/seed-hypermedia/seed/tree/main/backend/blob"
    click WebApp "https://github.com/seed-hypermedia/seed/tree/main/frontend/apps/web/app"
    click DockerWeb "https://github.com/seed-hypermedia/seed/tree/main/frontend/apps/web/Dockerfile"
    click PublicAssets "https://github.com/seed-hypermedia/seed/tree/main/frontend/apps/web/public"
    click Editor "https://github.com/seed-hypermedia/seed/tree/main/frontend/packages/editor"
    click SharedPkg "https://github.com/seed-hypermedia/seed/tree/main/frontend/packages/shared"
    click UI "https://github.com/seed-hypermedia/seed/tree/main/frontend/packages/ui"
    click ProtoDefs "https://github.com/seed-hypermedia/seed/tree/main/proto"
    click GenProto "https://github.com/seed-hypermedia/seed/tree/main/backend/genproto"
    click Bazel1 "https://github.com/seed-hypermedia/seed/blob/main/BUILD.bazel"
    click Bazel2 "https://github.com/seed-hypermedia/seed/blob/main/BUILD.plz"
    click BuildRules "https://github.com/seed-hypermedia/seed/tree/main/build/rules"
    click NixEnv "https://github.com/seed-hypermedia/seed/blob/main/shell.nix"
    click Direnv "https://github.com/seed-hypermedia/seed/blob/main/.envrc"
    click DevCmd "https://github.com/seed-hypermedia/seed/tree/main/dev/"
    click Compose "https://github.com/seed-hypermedia/seed/blob/main/docker-compose.yml"
    click DeployScript "https://github.com/seed-hypermedia/seed/blob/main/website_deployment.sh"
    click MonCompose "https://github.com/seed-hypermedia/seed/blob/main/monitoring/docker-compose.yaml"
    click PromConfig "https://github.com/seed-hypermedia/seed/blob/main/monitoring/prometheus/prometheus.yaml"
    click Grafana "https://github.com/seed-hypermedia/seed/tree/main/monitoring/grafana"

    %% Styles
    classDef frontend fill:#AEDFF7,stroke:#0366d6,color:#000;
    classDef backend fill:#D9F5D9,stroke:#028A02,color:#000;
    classDef datastore fill:#FEE4B6,stroke:#E27A00,color:#000;
    classDef network fill:#F8D7DA,stroke:#A50E2B,color:#000;
    classDef external fill:#E2E3E5,stroke:#6C757D,color:#000;
```
