How seed-hypermedia/seed works
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