Together we gather, together we grow.
Discover, host, and grow community events across African cities.
Mukoko Events is the community events platform of the Mukoko super app. It grew out of the Shona tradition of nhimbe (pronounced /ˈnhimbɛ/) — the communal work gathering where neighbours come together to get something done and share in the harvest.
That spirit — the Ubuntu idea that I am because we are — runs through the whole product. Together we gather, together we grow. Mukoko Events exists to help communities across African cities find one another, plan the moment, and turn up.
Mukoko Events is the public app — the thing an attendee or a host actually opens. Two sibling repos carry the other two surfaces, and the three are easy to confuse:
| Repo | What it is | Where it runs |
|---|---|---|
mukoko-dev/mukoko-events ← here |
The public app and the data plane. The Next.js app, the MongoDB layer, the /api/events* REST surface, and the OAuth resource-server metadata everything else authenticates against. |
Vercel — events.mukoko.com |
mukoko-dev/mukoko-events-admin |
The staff back office. Moderating events, people, entities and platform settings. /admin* here 307s to it. |
Vercel — admin.events.mukoko.com |
mukoko-dev/mukoko-events-mcp |
The agent surface. A stateless MCP server that owns no data — every tool calls this app's HTTP API. | Cloudflare Workers — events.mukoko.com/mcp |
This repo ships no admin routes and no worker: src/app/admin/ does not exist,
and there is no wrangler.toml. What it does ship on their behalf is the host
gate (src/lib/auth/mcp-host.ts) and the .well-known discovery documents the
MCP's OAuth challenge points clients at.
events.mukoko.com is the app's home. Every self-referential URL a crawler
consumes (canonical tags, OpenGraph and Twitter images, the sitemap, robots,
schema.org JSON-LD) points there. See src/lib/site-url.ts.
The product was called Nhimbe until 4 October 2026, when the brand was
retired in favour of Mukoko Events (#155). The old domains
redirect with paths preserved: www.nhimbe.com 308s to events.mukoko.com,
and nhimbe.com follows once its cutover lands. Internal identifiers that would
break saved state if renamed (the nhimbe-theme and other storage keys, .nh-*
CSS classes, iCalendar UIDs, sourceProject: "nhimbe") keep the old name on
purpose.
- Discover & browse — Start on
/discoverand drill into a category, a circle, or a city; search by interest, place, and time. - Create & host — Publish gatherings with rich details, cover art, and recurring schedules, then manage them from one place.
- RSVP & waitlists — Reserve a spot with capacity limits that never oversell a room, and let people queue when it's full.
- Circles — Community groups that live alongside your events and keep people connected between them, each leading with its own events timeline.
- Calendars — Followable event calendars, a branded month view, and one-tap calendar export.
- Check in with QR — Fast, on-the-day attendance using QR codes and on-site kiosk mode.
- Signage — Turn any screen into a live event display for venues and lobbies.
- Shamwari, your AI helper — A friendly assistant that helps you find the right event and write great descriptions.
- Reviews, ratings & referrals — Build trust, help the best gatherings rise, and grow reach through the people who show up.
- Reminders & updates — Keep attendees in the loop so no one misses the moment.
- Your language — Available in English and Shona, with more on the way.
- Anywhere — Installable, fast, and accessible (WCAG AAA), in light or dark.
- Next.js 16 (App Router, React 19, TypeScript strict, Tailwind v4) — one full-stack app, no separate backend.
- MongoDB (Mukoko v3.1 cluster) — read/written server-side only via the
mongodbdriver; SSR-first, writes through Server Actions. - WorkOS AuthKit — hosted sign-in end to end.
- Cloudflare — R2 for media, and the AI Gateway fronting Shamwari, with Atlas Vector Search for retrieval. (Model identifiers are deliberately not committed anywhere in this repo — see AGENTS.md.)
- Vercel — builds and deploys every push (preview per branch, production on
main).
Maps (Leaflet + OpenStreetMap), geocoding (OSM Nominatim), and weather (the shared Mukoko embed) need no API keys.
You'll need a recent Node.js LTS and npm.
npm install # install dependencies
cp .env.example .env.local # then fill in your values
npm run dev # dev server at http://localhost:11825
npm run build # production build
npm run lint # ESLint
npm run test:run # the Vitest suite, once
npm run test:integration # the suite that needs a real MongoDBEvery environment variable is listed, with notes, in .env.example. The architecture reference is AGENTS.md, with longer-form notes under docs/.
| Surface | Route | What it is |
|---|---|---|
| Home | / |
Auth-split — a lean landing when logged out, "Your events" when signed in |
| Discover | /discover |
The browse surface: category tiles → featured circles → city cards |
| Events | /events |
The all-events timeline, scopeable by ?category= / ?city=; plus create, detail, and manage |
| Circles | /circles |
Community groups (formerly "Kraal"), each leading with an events tab |
| Calendar | /calendar |
Branded month view + agenda; followable calendars and ICS export |
| Search | /search |
Interest, place, and time search |
| Signage / kiosk | /signage, /events/[id]/kiosk |
Live event displays and on-site check-in |
| Admin | /admin |
Operator dashboard — a separate app (mukoko-dev/mukoko-events-admin); /admin* redirects there |
Mukoko Events is built to be worked on by coding agents as well as people.
- AGENTS.md — the tool-agnostic standing rules (checks, boundaries, workflow) any runner should follow. This is the authoritative reference.
- docs/ — longer-form design notes and archived plans.
CLAUDE.md and .claude/ are deliberately untracked — they are local
developer conveniences, not part of the repo. Do not expect them in a fresh
clone.
Have a question, an idea, or want to help shape Mukoko Events? Join the people building it:
| Document | Purpose |
|---|---|
| CONTRIBUTING.md | Set up a local environment and contribute |
| AGENTS.md | Standing rules for coding agents |
| .env.example | Every environment variable, annotated |
| SECURITY.md | Security policy and how to report a vulnerability |
| RELEASES.md | Changelog and release process |
We take the safety of the community seriously. If you discover a vulnerability, please report it responsibly — see SECURITY.md. Please don't open a public issue for security reports.
Pull requests are welcome. Read CONTRIBUTING.md for setup, conventions, and the PR process before you start.
Released under the MIT License — see LICENSE.
Mukoko Events is a Mukoko product by Nyuchi Web Services.