Sofia

Transform your browsing into certified knowledge on the blockchain.

Sofia is a full-stack knowledge graph product on the Intuition protocol. A Chrome extension captures your browsing, an explorer surfaces your on-chain reputation and circles, a gated group-join backend powers membership, and shared packages keep the taxonomy, quests, and GraphQL client in sync across every surface.

This repository is a bun workspaces monorepo containing all surfaces: extension, explorer, landing, OG image generator, docs/blog, plus the backend services (group-join API, OG proxy, AI workflows) and shared packages.

Repository layout

core/
├── apps/
│   ├── explorer/         Vite + React 18 — on-chain reputation, circles & discovery
│   ├── extension/        Plasmo Chrome extension (MV3) — browsing certification
│   ├── landing/          Vite + React 19 — marketing landing page
│   ├── og/               Next.js 14 — OG image generator for shared certifications
│   ├── doc/              Vite + React + MDX — documentation site
│   └── blog/             Vite + React + MDX — project blog / logbook
├── packages/
│   ├── graphql/          @0xsofia/graphql — shared GraphQL client + codegen (Intuition indexer)
│   ├── design-system/    @0xsofia/design-system — shared components, hooks, theme tokens, styles
│   ├── taxonomy/         @0xsofia/taxonomy — topics, categories, niches + on-chain atom registry
│   └── quests/           @0xsofia/quests — quest catalogue + XP rewards (minted by ext, read by explorer)
└── services/
    ├── group-api/        Hono + Bun + Prisma/Postgres — gated group-join backend
    ├── og-proxy/         Hono + Bun — OG image proxy
    └── mastra/           Mastra — AI workflows (theme/predicate classification, recommendations)

Stack per surface

Requirements

• Node.js >= 22.13.0
• Bun >= 1.3.0 — curl -fsSL https://bun.sh/install | bash
• git, and a wallet (MetaMask / Rabby) to test the extension
• PostgreSQL (or a Neon connection string) for services/group-api

Setup

git clone [email protected]:intuition-box/Sofia.git
cd Sofia
bun install

bun install resolves all workspace deps and wires symlinks across apps/*, packages/*, and services/*. After pulling a branch that adds a new workspace package, re-run bun install so the new symlink is created (otherwise Vite fails to resolve @0xsofia/* imports).

Copy the per-app .env files (they are gitignored):

Build the GraphQL package once (codegen regenerates src/generated/index.ts):

bun run --filter @0xsofia/graphql codegen

For services/group-api, generate the Prisma client + apply migrations:

bun run --filter group-api db:generate
bun run --filter group-api db:deploy

Dev commands

Root shortcuts (defined in the top-level package.json):

Loading the extension in Chrome: after bun run dev:extension, open chrome://extensions/ → enable Developer mode → "Load unpacked" → pick apps/extension/build/chrome-mv3-dev/.

Architecture

The extension is the primary Sofia surface. It reads the browser history, proposes intentions (learning, work, fun, buying, inspiration, music, trust, distrust), pins URLs to IPFS, then creates atoms and triples on Intuition via the Sofia fee proxy (fixed fee + 5%).

The explorer consumes the same GraphQL indexer to surface a user's reputation, streaks, circles, and discovery ranking. WebSocket subscriptions on the shared @0xsofia/graphql package keep UI data live; it also queries a remote MCP trust engine (VITE_MCP_TRUST_URL) for reputation scoring.

Circles (gated groups) are backed by services/group-api: a Hono + Prisma/Postgres backend handling join requests, admin review, membership/roles, and notifications (REST history + Ably realtime push). The on-chain MEMBER_OF triple is minted by the user via the explorer cart after an admin approves — the backend only gates access.

Shared logic lives in packages: @0xsofia/taxonomy (topics/atom registry), @0xsofia/quests (quest catalogue + XP), @0xsofia/design-system (components/theme), and @0xsofia/graphql (indexer client).

Detailed docs per surface:

• Extension architecture
• Explorer realtime
• group-api security

Intuition protocol — key concepts

Contributing

• Branches off dev. PRs target dev, then dev → main for releases.
• After merging dev or adding a workspace, re-run bun install.
• TypeScript is non-strict (matches existing style).
• Prettier is configured per package (bun run format).
• Barrel imports: always import { X } from "~/lib/services", never from individual files (extension specifically — see extension CLAUDE.md).

License

See LICENSE.