HeyNaija

A Nigeria-first social network being built toward community ownership. PLAN.md has the product plan, what is built, and what comes next; ADR 0002 explains the architecture and lists every known limitation.

The public introductions are /about (purpose and direction) and /progress (product development, separate from governance). The canonical feature inventory is docs/FEATURE_ROADMAP.md, generated from docs/feature-roadmap.json; the audit notes explain evidence, availability limits and outstanding confirmations.

Status: staging is live at https://staging.heynaija.ng and production is deployed at https://heynaija.ng. Signup stays invite-only: production is not publicly launched until the conditions in PLAN.md §11 are met. Everything needed to deploy is in infra/deploy/ and .github/workflows/, with step-by-step guides in docs/deployment/. What works:

• Accounts: join with an invite code (18 and over during the beta, a temporary rule; the API refuses a signup without the age confirmation), sign up, confirm email, sign in and out, and regain access with an emailed code (handled by Ory Kratos). There is no password-recovery flow; losing access to the account email is not covered by a separate recovery process.
• Posting: posts and expandable threaded replies with cursor pagination and up to four images each (with descriptions for screen readers, and a full-screen viewer), likes, private bookmarks.
• People: profiles with a photo, display name and bio; follow, mute and block.
• Notifications: replies, likes, follows and moderation outcomes, with an unread count in the navigation.
• Communities: five launch communities, and Building HeyNaija, where the app's builders work in the open.
• Feeds: Latest, Following (people and communities, each post says why it is there), per-community, trending, and search over members, communities and posts.
• Safety: report a post or account, a moderation queue (remove post, suspend account, dismiss), appeals from suspended members, a decision log, rate limits.
• Look: light, dark and system themes; works down to phone width.
• Portability: download your own data from Settings as JSON (format 3, including reposts and quote references).
• Governance information: /governance (founding-stage status, how members would govern, the path to community ownership, empty states for votes, the treasury and decisions), the draft constitution at /governance/constitution, and explainers for legal membership, voluntary online voting and optional NIN verification. Draft v0.3 proposes Incorporated Trustees, three founding trustees on initial three-year terms, and two annual representatives. Activation does not trigger founding trustee re-election; all three trustee seats open at term expiry. No incorporation or legal community ownership is claimed. The generated CAC review copy, charter/policy guide and legal questions require Nigerian counsel review before adoption. pnpm governance:check checks the public/CAC text. Settings shows each member's own status. Identity verification, voting membership, binding votes and the treasury are not live, and the API refuses to start with them switched on (ADR 0005, open items). Age is its own status, separate from accounts, identity and voting (ADR 0006); what opening to under-18s requires is in under-18-rollout.md.

How it fits together

Browser ──> Next.js web app (127.0.0.1:3000)
              ├── /api/v1/*  ──> NestJS API ──> Postgres (members, posts, invites)
              │                      └──> Redis (BullMQ: image processing jobs)
              ├── /media/*   ──> object storage (public bucket of processed images)
              └── /kratos/*  ──> Ory Kratos ──> Postgres (identities, sessions)
                                     │  └──> Mailpit (dev email inbox)
                                     └── webhooks ──> API (invite check on signup)

• Ory Kratos owns accounts: email, handle, sign-in by emailed code or Google, and sessions. There are no passwords (ADR 0003). We write none of that ourselves.
• The API owns everything else. It asks Kratos who a session cookie belongs to on every request, and only accepts identities that joined with an invite.
• The web app is the only thing the browser talks to; it proxies the other two.

Path	What
apps/web	Next.js web app: feeds, threads, profiles, communities, moderation, and the account pages rendered from Kratos flows
apps/api	NestJS + Fastify API: session guard, invites, posts, communities, feeds, search, moderation, rate limits
packages/db	Drizzle schema, migrations and community seed data for the app database
infra/kratos	Kratos configuration and identity schema
infra/compose	Local stack: Postgres, Redis, Kratos, Mailpit, MinIO

Run it locally

Needs Node 22+, pnpm 10 and Docker.

pnpm install
pnpm infra:env          # writes or tops up .env with random local secrets
pnpm infra:up           # Postgres :5433, Redis :6380, Kratos :4533/:4534, Mailpit :8026, MinIO :9100/:9101
pnpm build
pnpm db:migrate
pnpm db:seed            # creates the communities (safe to re-run)
pnpm media:init         # creates the two storage buckets on the local MinIO
pnpm demo:seed          # optional: 14 demo members, threads, images, likes and follows (re-run to refresh)

This is the beginning of the README. Read the rest at the original. Read the full README ↗