Loading…
← Engineering HandbookComing soon
WatchSankofa
A pan-African creative-content streaming platform, film, music, poetry, writing and photography, built mobile-first for African connectivity realities, with Claude-powered discovery.
View the product page- Data model
- 26 tables · 26 indexes · RLS on all 26 · 50 policies · trigger-driven
- Stack
- 9 technologies
- Provenance
- real build journals
The problem
African creative content lacks its own distribution infrastructure; existing platforms are Western clones not built for the continent’s connectivity, languages and mobile-first majority.
.jpg&w=3840&q=75)
Architecture
How it’s wired
A container-level view of the real system, the boundaries, the trust edges, and where intelligence and money actually flow.
Browse pages are server-rendered; media never proxies through the app server (direct-to-origin uploads to Cloudflare Stream + R2). Postgres triggers keep counters, feeds and badges live, and a scheduled function recomputes the trending score every six hours.
.jpg&w=3840&q=75)
By the numbers
26
tables · 50 RLS policies
7
AI routes · 2 models
7
custom players · 0 libraries
50K
AI tokens / user / day cap
Stack
Next.js 16 (App Router, Turbopack)TypeScript (strict)Supabase (Postgres + RLS + Realtime)Anthropic Claude (Sonnet + Haiku)Zustand + persistUpstash Redis + RatelimitCloudflare Stream (HLS/DASH)Cloudflare R2 (S3 presigned)hand-written service worker (no framework)
Intelligence
Seven Claude route handlers across two models, Sonnet 4.6 for judgment-heavy work (afribrain, creative-dna, discover, taste-profile, creator-assistant) and Haiku 4.5 for cheap, high-volume labelling (enrich, card-description), behind three caching tiers and a 50,000-token-per-user-per-day budget, tuned for African cultural context.
Data model
26 tables · 26 indexes · RLS on all 26 · 50 policies · trigger-driven
- content (creators, works, series, albums, collections) + discovery (taste_profiles, history)
- denormalized counters kept live by triggers: works.view/heart/comment/share_count + trending_score/is_trending
- fan-out triggers write activity_feed + notifications on new work / follow / note; check_and_award_badges tiers badges automatically
- atomic increment_view_count as a SECURITY DEFINER RPC, called fire-and-forget behind a UUID-regex guard
Key decisions
Why it’s built this way
Architecture Decision Records, the trade-offs made deliberately, in the open.
ADR-01
Dual-model routing as explicit cost engineering
- Context
- Some AI work needs judgment; most is cheap, high-frequency labelling.
- Decision
- Sonnet 4.6 for generation (afribrain, discover, taste-profile, creator-assistant, creative-dna); Haiku 4.5 for enrich + card copy, with a documented per-call cost estimate in code.
- Consequence
- Quality where it matters, cents where it doesn’t, a truer story than "all Sonnet."
ADR-02
Split Cloudflare storage with direct-to-origin uploads
- Context
- Media must never proxy through the app server.
- Decision
- Video → Cloudflare Stream via TUS direct upload (the server stores only the returned uid); audio and images → R2 via S3 presigned PUT (the client PUTs straight to the bucket). Live ingest (RTMPS + WebRTC) is provisioned the same way.
- Consequence
- The app server never touches a byte of media.
ADR-03
Postgres-as-engine, logic in triggers, not app code
- Context
- Counters, feeds and badges must stay correct under concurrency.
- Decision
- DB triggers maintain heart / follow / comment / works counts, fan out activity_feed + notifications, and award tiered badges; a scheduled recalculate_trending_scores runs every six hours.
- Consequence
- Engagement state stays consistent with no app-side bookkeeping.
.jpg&w=3840&q=75)
The hard parts, solved
Where the engineering earned its keep
01
Three-layer AI cost defense
Claude prompt caching wraps static system prompts in an ephemeral block ("cache read = 10% of base cost"); a Redis response cache keys identical single-turn calls by sha256(model|system|message) with a 15-min TTL; and a Redis platform-context snapshot is cached 15 min, all under a per-user 50,000-token/day budget enforced via Redis INCRBY with a 24h TTL.
02
A trending algorithm that lives in Postgres
A scheduled function scores every work as weighted engagement (views×1 + hearts×5 + comments×10 + shares×8) multiplied by an exponential 7-day half-life decay, then ROW_NUMBER() OVER (PARTITION BY category) flags the top 10 per category as trending, recomputed by cron every six hours.
03
Zero player libraries
Seven fully custom media players, film, music, dance, poetry, waveform, writing-reader and a mini-player, built directly over the native HTML5 media element with no hls.js / react-player / video.js; the Zustand store persists only volume / mute / shuffle / repeat / queue, so playback survives navigation without remounting.
Sourced from AfriFlix (afriflix-v2), supabase/master.sql, lib/claude.ts, middleware.ts, components/players/*, vercel.json.
.jpg&w=3840&q=75)
Keep exploring