Tribes

A social platform where users are positioned in emergent, multi-dimensional ideological space based on their actual behaviour. Healthy discourse arises from the architecture itself.

Stack

Layer	Technology
Frontend	Next.js 16 (App Router, TypeScript, Tailwind)
API	Node.js + Fastify (TypeScript)
Database	PostgreSQL via Supabase + pgvector
Auth	Supabase Auth
Queues	BullMQ + Redis
Shared types	@tribes/shared workspace package

Monorepo structure

tribes/
├── apps/
│   ├── web/          # Next.js frontend
│   └── api/          # Fastify API server
├── packages/
│   └── shared/       # Shared TypeScript types & schemas
├── docs/
│   ├── specs/        # Product requirement specs
│   └── plans/        # Agent planning and completion artifacts
└── skills/           # Mathematical modelling references

Current implementation snapshot

• Core positioning foundations are implemented: event ingestion, refit pipeline, position update worker, auth middleware, and privacy-aware position discovery/query routes.
• Authentication, navigation, and app shell are implemented (PRD 10): Supabase SSR auth/session flow, middleware route protection, auth pages/callback, AppShell, and dashboard/marketing/settings surfaces.
• Foundation reconciliation is implemented (PRD 05): API/schema versioning foundations, recency weighting and regularization hardening, velocity tracking, Redis visibility caching, and dimension interpretation job/worker flows.
• Safety and moderation foundations are implemented (PRD 04 / v0.0.2): safety schema/contracts, statistical detection services, scheduled safety scan pipeline, admin safety endpoints, interventions/appeals, and MVP safety dashboards/pages.
• Transparency UX completion is implemented (PRD 06 / v0.0.3): Compass radar + table view, compose impact preview state machine, onboarding/reveal flow, sphere and cascade UX, and accessibility CI gate.
• /api/v1/users/me and /api/v1/users/me/compass-reveal are live and consumed by the web dashboard/profile surfaces.
• Cohort-aware feature flags are live via /api/v1/config/flags (user-resolved) and /api/v1/admin/config/flags/:key (admin upsert).
• Institutions API includes v1 CRUD and subscription controls (/api/v1/institutions), with subscription delivery eligibility enforced for verified, non-revoked institutions.
• Remaining planned work is primarily in deferred and follow-on specs (e.g. expanded manipulation detection workflow, researcher APIs, GDPR automation jobs, topic mesh, and pre-beta hardening).

Getting started

Prerequisites: Node 20+, pnpm 9+, Redis, a Supabase project with pgvector enabled.

# Install dependencies
pnpm install

# Copy env files and fill in values
cp apps/web/.env.example apps/web/.env.local
cp apps/api/.env.example apps/api/.env

# Run both apps in dev mode
pnpm dev

# Optional: start local Redis + Ollama for topic mesh framing summaries
docker compose up -d redis ollama

# One-time model pull for local Ollama provider
docker exec -it $(docker compose ps -q ollama) ollama pull llama3.2

• Web: http://localhost:3000
• API: http://localhost:3001
• API health: http://localhost:3001/health

Workspace commands

pnpm lint
pnpm typecheck
pnpm test
pnpm build

These are also the commands used by the GitHub Actions CI workflow for pull requests targeting main.

E2E harness

For Playwright E2E setup, required environment variables, auth token options, and run commands, see:

• tests/e2e/README.md

CI and Branching

Pre-merge checks live in .github/workflows/ci.yml and run on pull requests, pushes to main, and merge_group events.

The branching and protection model for those checks is documented in docs/decisions/github-branching-strategy.md. Use that guide when configuring required checks and merge settings in GitHub.

Seeding

Deterministic beta seeding is available from root scripts:

pnpm seed:beta
pnpm seed:beta:clean
pnpm seed:beta:full
pnpm --filter @tribes/api seed:beta -- --seed=phase6 --clean --refit

Expected CLI output is JSON including mode, seed, and counts. Typical counts are:

• Fast: users=10, posts=50, likes=250, follows=0, shares=0, events=300
• Full: users=50, posts=500, likes=2500, follows=500, shares=250, events=3750

Quick verification SQL (Supabase SQL editor):

select count(*) as seed_users
from users
where email like '%@seed.tribes.dev';

select count(*) as seed_posts
from posts
where user_id in (
    select id
    from users
    where email like '%@seed.tribes.dev'
);

select event_type, count(*) as total
from behavior_events
group by event_type
order by event_type;

Specs

See docs/specs/00-index.md for the full product requirements index.

Recent completed releases:

• PRD 10 — Authentication, Navigation & Application Shell (see docs/plans/10-authentication-navigation-shell-complete.md)
• PRD 05 — Foundation Completion & Reconciliation (see docs/plans/05-foundation-completion-reconciliation-complete.md)
• v0.0.2 — PRD 04 Safety & Outlier Detection
• v0.0.3 — PRD 06 Transparency UX Completion

Development order per spec dependency chain:

01 Core Positioning  →  02 Graduated Visibility  →  03 Transparency UX
                                                  ↗
                     04 Safety & Outlier Detection