Engineering an AI-powered community operating system.
A hyperlocal platform where a Nigerian neighborhood gets safety, commerce, and trust as native primitives — with geography itself as the schema.
The neighborhood is invisible to apps built for the planet.
Facebook, WhatsApp and X are built for planetary reach. That scope generates a constant hum of noise that drowns out the one thing that governs daily life — what is happening on your street, right now. In urban Nigeria that gap isn't an inconvenience; it's a safety and economic problem.
Neighborhood watch runs on tangled WhatsApp threads and physical sirens — no real-time escalation, no location streaming, no reliable way to reach the people who could actually help.
Buyers fear paying upfront; sellers fear pay-on-delivery. The electrician two doors down is invisible to the neighbor who needs one.
Global apps assume LTE and a flagship phone, and fall over on the 2G/3G networks much of suburban and rural Nigeria runs on.
Geography is the schema.
Every post, alert, and listing is bound to physical coordinates and routed through Nigerian Wards and Local Government Areas. The neighborhood is not a filter applied to a social graph — it is the graph. Three pillars sit on that spatial foundation.
Sentinel AI
Real-time threat analysis and a self-terminating SOS escalation ladder.
HuudCoin & Escrow
A hyperlocal marketplace protected by community-backed Social Witness Escrow.
TrustOS
A reputation ledger turning physical validation into a portable numeric score.
Location resolution is first-class. Safety-critical work never touches the request path.
Mobile PWA (Next.js 16 · React 19 · Capacitor)
│ HTTPS / WSS
▼
API Gateway ── JWT · Redis sliding-window limits
│
┌─────────────┼──────────────┐
▼ ▼ ▼
Identity Safety & Marketplace
& TrustOS Emergency & Escrow
│ │ │
▼ ▼ ▼
MongoDB MongoDB Redis
Better Auth + Geo tags + BullMQ| Layer | Technology | Why it's there |
|---|---|---|
| Client | Next.js 16 · Service Workers | Offline location-log queues; Web Push without an app store |
| Geo | Haversine matching + MongoDB tags | Nearest-LGA boundary resolution and location.lga-tagged content queries |
| Async | Redis + BullMQ | SOS escalation, emergency fan-out, trip monitoring — off the event loop |
| AI | Google Gemini 2.0 Flash | Contextual threat scoring and search-intent parsing |
| Identity | Better Auth + MongoDB | Session and credential management |
Sentinel AI: hybrid threat detection.
The naive build sends every post to an LLM and trusts the answer — slow, costly, and dangerously non-deterministic for a Level 10 emergency. Sentinel runs a three-stage cascade that only escalates to the model when it must. The geospatial clustering behind this pipeline gets its own dedicated case study.
Keyword prefilter
A curated security-keyword list — armed men, gunmen, car snatching, ambush, kidnap, ransom — does a cheap first pass. No match, no cost.
Cultural dictionary
The detail a generic build misses. Nigerian threat and scam language isn't in any English toxicity model, so Sentinel ships a hand-built cultural dictionary encoding local vernacular with severity and category — 419 and yahoo boy as high-severity scam signals, pidgin insults tagged by type.
Gemini scoring
Only content clearing the earlier stages reaches Gemini 2.0 Flash, which returns a contextual threat score from 0–10 — informed by keyword matches and same-LGA temporal clustering: are several people nearby reporting the same thing within the last 30 minutes?
Red-zone. “Armed men on our street” fans out to the entire LGA immediately.
Alert. Logged, surfaced to the community, watched for escalation.
Normal. “Water is finished” is a Level 2 utility note, not an emergency.
A panic-button ladder that stops itself.
The worst design is a single blast that reaches no one or spams everyone. NeyborHuud models the alarm as a time-based escalation ladder on a BullMQ worker, entirely off the request path. The cadence is configuration, not code.
Level 1. Notify priority-1 guardians via WebSocket, push and SMS simultaneously.
Level 2. Still unacknowledged? Widen to priority-2 guardians.
Level 3. Keep widening the ring of contacts.
Final. Page every remaining accepted, non-expired guardian not yet notified.
Self-terminate. Before every level fires, the worker re-checks status and acknowledgments. One guardian ack short-circuits the whole ladder — no duplicate pages, no alarm that keeps screaming after help is coming.
In parallel, a Haversine distance check against connected users' live locations broadcasts to opted-in neighbors within 500 metres while the client streams a GPS trail into an append-only tracking log. Running this on durable background workers — not inline in the HTTP handler — is what lets the alarm survive a dropped connection or a slow phone.
A three-tab feed, ranked by LGA membership.
A broken streetlight in your LGA outranks a viral video from across the country. Rather than one flat timeline, the feed splits into three tabs, each a different content query over the same resolved location.lga field set on every post.
Local-first, blended with content from LGAs you follow.
Content scoped tightly to your resolved home LGA.
Content from LGAs you explicitly follow, beyond home.
TrustOS: a materialized ledger.
Trust is earned physically and spent digitally. Reputation is a 0–1,000 numeric score backed by an append-only event log. Every trust-affecting action writes an event with a fixed point value and updates a materialized score on the user record, so reads stay O(1).
| Event | Δ Score | Effect |
|---|---|---|
| ID verified | +200 | Largest single trust milestone |
| Constructive action | +small | Helpful comment, completed job |
| Base (new user) | 300 | Trusted enough to join, not to abuse |
| Abuse penalty | −300 | False reports, misconduct |
High-trust actions like tipping are gated behind score thresholds, and Tier-3 members can vouch for a newcomer within a 500m radius — enforced with its own Haversine distance check — granting temporary trusted access.
Why these choices hold together.
Push the intelligence to the edges of a deterministic core.
The LLM scores but doesn't decide. Guardians escalate but the ladder stops itself. Geography ranks the feed but a threat score can override it. Trust is fluid but backed by an immutable ledger.
Gemini is one input to a deterministic safety pipeline — never the pipeline itself.
Safety-critical escalation lives on BullMQ workers, resilient to dropped connections.
Haversine distance and LGA boundary matching power geofencing, feed ranking, fan-out, and vouching alike.
An append-only ledger with a materialized read model keeps reputation fast and auditable.
That's what makes it an operating system rather than a bag of features: a small set of hard primitives — spatial boundaries, durable background work, a trust ledger, and a constrained AI layer — that every one of the 35 modules is composed from.