Social SoftwareTechnical Reference

This page covers the technical detail behind the Social Software ecosystem as implemented in the current codebase: database schema, API surface, business logic modules, MCP server, federation protocol, and the reasoning behind key architectural decisions. For the product thinking and structural vision, start with the narrative.

Tech Stack

Application

Infrastructure

Database Schema

The database is the source of truth. Every table, RLS policy, and RPC function was defined before any application code was written.

Users and identity

An auto-profile trigger fires on user signup. Row-Level Security policies gate all access.

Four-tier layer tables

Revenue and economics

Governance and moderation

Federation and self-hosting

Infrastructure

Database functions and views

RLS: embeds are publicly readable; only authenticated users can create embed records.

Business Logic

Seven library modules in src/lib/ implement the core business logic. All are pure functions or thin wrappers around Supabase RPCs, with no UI dependencies.

Lineage (lineage.ts)

Encodes the provenance DAG using PostgreSQL's ltree extension. Every app's full ancestry is stored in a single column.

Ancestor queries use the @> operator (ancestor contains descendant). Descendant queries use <@ (descendant is contained in ancestor). Both are single indexed queries, not recursive CTEs.

Revenue (revenue.ts)

Implements logarithmic decay distribution and settlement.

calculateSplit(amount, ancestors) — takes a total amount and the ancestor chain (root → current). Reverses the chain so index 0 = current maintainer, then applies 50% decay at each generation. The last ancestor receives whatever remains. Amounts below $0.000001 are dropped.

settleRevenue(appId, amount, source) — the full settlement pipeline:

1. Record revenue entry in revenue_pool
2. Walk ancestors using getAncestors() RPC
3. Calculate split via calculateSplit()
4. Insert into distributions table, calling increment_balance() RPC for each recipient
5. Mark pool as settled, increment app tip total
6. Append immutable event to audit trail

triggerStripePayouts(distributionIds) — Stripe Connect transfer for each unsettled distribution. Skips creators without a connected Stripe account and transfers below Stripe's $0.50 minimum. Code-complete but untested against live keys.

Linter (linter.ts)

The AI Verification Engine. Eight regex-based rules, each returning a severity (error or warning) and a human-readable message.

Any error-severity issue blocks compilation. Warnings are informational. The linter runs on every keystroke in the fork IDE and on every MCP publish_layer call.

Layers (layers.ts)

CRUD operations for the four-tier architecture.

Federation (federation.ts)

Peer-to-peer layer sharing between independent ecosystem nodes.

Imported layers become local roots with their own lineage. They can be forked, built upon, and generate revenue within the importing node.

Seed (seed.ts)

Contains the genesis bounty board React code and the injected api-client.jsx that gates all network access through a controlled interface. The api-client also exports composition primitives: useEcosystemApp(appId) for fetching another app's code and metadata, and EcosystemEmbed for rendering another app inline in an isolated iframe. Used by the npm run seed script.

API Surface

18 API routes, each a thin orchestration layer: validate input, call business logic, return response.

Core app routes

Bounty routes

Revenue and lineage

AI, telemetry, governance

Layers, manifests, federation, MCP

MCP Server

The MCP server exposes the ecosystem to AI coding tools via two transports:

• stdio — npm run mcp for Cursor, Claude Desktop, Windsurf
• HTTP — POST /api/mcp with JSON-RPC body for web clients

Resources (context discovery)

Tools (9 total)

Both transports call the same business logic modules. There is no separate MCP backend.

Frontend

14 pages covering the full user journey from discovery through forking, composition, earning, and governance.

Architecture Decisions

Why ltree instead of Neo4j

The provenance DAG is the most important data structure in the system. The obvious choice would be a graph database. PostgreSQL's ltree was chosen instead for three reasons:

• Operational simplicity. One database instead of two. Supabase gives auth, RLS, RPCs, and real-time subscriptions on the same instance that stores lineage. Neo4j would mean a second managed service, a second connection pool, and cross-database coordination for revenue settlement.
• Colocated transactions. Revenue settlement needs to atomically query ancestors, insert distributions, update balances, and record an audit event. With ltree in Postgres, this is one transaction.
• Shallow DAG. Fork lineages are typically 3–10 levels deep. ltree handles this effortlessly. The system is not traversing social networks with millions of edges.

The trade-off: ltree represents tree paths, not arbitrary graphs. Multi-parent merges (app C forks both A and B) are not supported at the lineage level. Multi-parent composition happens at the manifest level instead.

Why Sandpack instead of WebContainers

• Attack surface. WebContainers run a full Node.js environment (fs, net, child_process). Sandpack only runs React components with no filesystem, no network, and no server-side execution.
• Startup time. Sandpack instantiates in under 2 seconds. WebContainers take 5–10 seconds.
• API client injection. A read-only api-client.jsx is injected into every sandbox, gating all network access through a controlled interface. Combined with the linter blocking fetch() to external URLs, the sandbox is structurally locked down.

WebContainers are the upgrade path for full-stack forks once the sandbox model is proven.

Why a custom linter instead of ESLint

• Speed. Eight regex-based rules return in milliseconds. ESLint with a plugin architecture for eight rules would be overkill.
• Scope enforcement. The most important rule checks whether actual API calls match declared permission scopes, distinguishing read from write by HTTP method. This is a domain-specific check that does not map to any existing ESLint rule.
• Auditability. Eight rules, each a clearly documented pattern. Anyone reading the file understands the entire security model in 90 seconds.

The trade-off: regex-based linting is evadable. The mitigation is defence in depth — the linter catches accidental violations, while the Sandpack CSP enforces the network boundary structurally. A production system would add AST-level analysis.

Why event sourcing

Every state mutation appends an immutable row to the events table. No updates, no deletes.

• Governance disputes. If a creator claims unfair flagging or revenue miscalculation, the full history of every action is available.
• Replay capability. The event stream can reconstruct any past state.
• Audit compliance. For a platform handling real money through creator payouts, an immutable trail is a legal requirement.

Why content-addressable hashing

Every piece of code is SHA-256 hashed on publish. This enables:

• Federation integrity. Imported layers are verified against their hash.
• Deduplication. Identical changes from different developers are recognised as the same code.
• Immutable references. Manifests point to specific layer hashes. Updating a layer creates a new hash; existing manifests continue to reference the original.

Known Limitations