Pulse — Sports Social Platform

A TypeScript/React Native product prototype for a sports-focused social network, built as a modular monolith with Expo and Supabase.

Pulse combines a social feed, communities, messaging, match/statistics surfaces and virtual prediction mechanics while keeping authentication, authorization, data access and ledger invariants behind explicit backend boundaries.

Highlights

• Expo Router + React Native mobile application with strict TypeScript.
• npm monorepo with seven workspaces and reusable domain, API, contract, UI and validation packages.
• Supabase Auth, PostgreSQL, Storage, RPCs and Row Level Security.
• Ten forward SQL migrations plus deterministic seed and pgTAP database tests.
• API responses validated at runtime with Zod contracts and stable PULSE_* error codes.
• Client screens do not access Supabase tables directly; business writes flow through RPCs.
• Append-only virtual-coin ledger with balanced-entry checks and idempotent market settlement.
• Compound-cursor pagination, authorization/audit infrastructure and storage policies.
• Deterministic demo mode so the interface can run without credentials or a backend.
• CI separates application-quality gates from a Docker-backed local Supabase integration job.

Architecture

The central dependency rule is:

Expo UI
  -> domain/repository boundary
  -> PulseApiClient
  -> Postgres RPC
  -> RLS + constraints
  -> PostgreSQL / Storage

The UI is deliberately prevented from importing Supabase directly. Authorization is enforced at the database/API boundary rather than being treated as a presentation concern.

Product surfaces

The current mobile scaffold includes:

• Arena — sports-oriented social feed and post cards;
• Messages — inbox-style messaging surface;
• Pulse — product discovery/highlight surface;
• StatsHub — match context, statistics and virtual predictions;
• Profile — identity and social metrics;
• Auth / onboarding — sign-in, sign-up, session reconciliation and profile creation.

The project exports 17 static web routes from the Expo Router tree.

Backend and data model

The Supabase layer is much more than a placeholder schema. Across ten migrations it defines social, sports, community, moderation, authorization and virtual-wallet domains.

Selected engineering concerns include:

• user profiles, follows and blocks;
• communities, memberships, channels and messages;
• posts, likes, comments, bookmarks and media;
• sports, competitions, events and statistics;
• prediction markets and virtual-user predictions;
• wallet accounts, balanced ledger entries and settlement;
• notifications, reports and audit events;
• global roles, permissions, entitlements and feature flags;
• public/private Storage policies.

npm run db:smoke executes all ten migrations and the development seed in PostgreSQL-WASM, then checks representative RPC, RLS, block, membership, ledger and settlement invariants.

Authentication and API boundary

Supabase authentication is encapsulated inside packages/api-client. The mobile runtime has two explicit modes:

• demo — deterministic local data, no secrets and no external requests;
• supabase — Auth + RPC-backed repositories using a local/public anon key.

RPC responses are parsed through Zod contracts before they reach the UI. Unexpected response shapes fail explicitly instead of being silently trusted.

Safety model

Pulse Coins are virtual points only. They have no monetary value, purchase flow, withdrawal or conversion path.

The current repository intentionally excludes real-money payments, KYC and regulated betting functionality. Settlement is a backend concern and the client is not allowed to write directly to wallet or ledger state.

Other defensive design choices include:

• RLS on exposed data;
• business writes through permission-checked RPCs;
• service-role operations kept outside the Expo application;
• append-only ledger/audit structures;
• idempotency keys for critical operations;
• block precedence in social visibility;
• separate public/private media policies.

Repository structure

apps/mobile/                  Expo Router application
packages/api-client/          Supabase session, RPC client and repositories
packages/domain/              domain interfaces and feature configuration
packages/rpc-contracts/       Zod envelopes and stable API errors
packages/shared-types/        shared TypeScript types
packages/ui/                  reusable tokens and components
packages/validation/          runtime and form validation
supabase/migrations/          forward SQL migrations
supabase/tests/               pgTAP database tests
scripts/                      architecture, DB and production-preflight checks
docs/                         architecture, design decisions and roadmap

Local development

Requirements:

• Node.js 24
• npm 11+
• Docker for the full local Supabase gate

npm ci
npm run check
npm run mobile:export:web

The app defaults to demo mode and therefore boots without credentials.

For a real local Supabase stack:

npm run db:start
npm run db:reset
npm run db:lint
npm run db:test
npm run db:types

Copy apps/mobile/.env.example to apps/mobile/.env only for local Supabase mode.

Validation

The source snapshot used for this public release was audited with:

ESLint                         PASS
TypeScript (7 workspaces)      PASS
Vitest                         7/7 PASS
Architecture boundary check    PASS
10-migration DB smoke          PASS
RPC/RLS/ledger invariants      PASS
Expo static web export         17 routes PASS

A generated Expo type file was removed from the public source snapshot so that the committed tree remains formatter-clean. GitHub Actions reruns the full quality gate and a separate Docker-backed Supabase integration gate.

Current status

Pulse is an MVP engineering prototype, not a production social network.

The foundation and demo UI are implemented, while several end-to-end product slices remain intentionally incomplete. In particular, recovery flows, full Arena interactions, communities, production sports-data ingestion, backend settlement workers, moderation operations, rate limiting, E2E testing and production security review are still roadmap items.

The production preflight is deliberately blocked until those requirements are satisfied.

See Project status and Roadmap.

License

The software and original documentation in this repository are licensed under the MIT License.

Third-party APIs, provider content, sports data, trademarks and other third-party materials are not covered by this license and remain subject to their respective terms.

Disclaimer

Independent software project. It is not affiliated with or endorsed by Supabase, Expo, any sports league, club or data provider referenced in development fixtures.