Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 8 additions & 8 deletions site/src/content/docs/kweli/cross-app-verification.mdx
Original file line number Diff line number Diff line change
@@ -1,19 +1,19 @@
---
title: Cross-app verification
description: How sibling Mukoko apps (Nhimbe, BushTrade, News, …) verify venues by deep-linking to the Kweli gateway instead of building their own flow.
description: How sibling Mukoko apps (Nhimbe, BushTrade, News, …) verify places and organizations by deep-linking to the Kweli gateway instead of building their own flow.
sidebar:
label: Cross-app how-to
---

import { Aside } from '@astrojs/starlight/components';

<Aside type="caution">
**Never build your own venue verification.** Kweli is the ecosystem's single verification surface. Sibling apps only _read_ `bundu.verificationTier` from the graph and render the mineral badge; anything that changes verification state happens on Kweli.
**Never build your own place or organization verification.** Kweli is the ecosystem's single verification surface. Sibling apps only _read_ `bundu.verificationTier` from the graph and render the mineral badge; anything that changes verification state happens on Kweli.
</Aside>

## The verify gateway

When a venue on your app needs to prove who it is, deep-link the user to the Kweli gateway:
When a place or organization on your app needs to prove who it is, deep-link the user to the Kweli gateway:

```text
https://kweli.mukoko.com/[locale]/verify?entity=<entityId>
Expand All @@ -23,20 +23,20 @@ https://kweli.mukoko.com/[locale]/verify?place=<placeId>&source=<yourapp>
| Query param | Required | Meaning |
|-------------|----------|---------|
| `entity` | no | The `entity.entities` UUID to verify |
| `place` | no | The `places.places` UUID — the gateway resolves the venue's entity via `ownerEntityId` |
| `place` | no | The `places.places` UUID — the gateway resolves the place's entity via `ownerEntityId` |
| `source` | no | Your app's identifier (e.g. `nhimbe`, `bushtrade`) for attribution |

The gateway resolves the venue, shows the current verification tier, the claim action for representatives, and the community vouch panel for everyone else.
The gateway resolves the place, shows the current verification tier, the claim action for representatives, and the community vouch panel for everyone else.

With **no query params**, `/verify` is a valid entry point rather than a 404: it renders a venue finder (search the graph by name), the signed-in user's owned venues and pending claims, and the tier ladder. Linking bare `/verify` is fine when your app doesn't know the venue's UUID.
With **no query params**, `/verify` is a valid entry point rather than a 404: it renders a place finder (search the graph by name), the signed-in user's owned places and pending claims, and the tier ladder. Linking bare `/verify` is fine when your app doesn't know the place's UUID.

## Rendering the badge

Read `bundu.verificationTier` from the venue's graph document and render the mineral-tiered badge (the `nyuchi-verified-badge` contract): 1 Community/Terracotta, 2 Identity/Cobalt, 3 Government/Gold, 4 Licensed/Tanzanite. The badge is **read-only** in your app — see the [tier ladder](/kweli/verification/#the-four-tier-ladder).
Read `bundu.verificationTier` from the place's graph document and render the mineral-tiered badge (the `nyuchi-verified-badge` contract): 1 Community/Terracotta, 2 Identity/Cobalt, 3 Government/Gold, 4 Licensed/Tanzanite. The badge is **read-only** in your app — see the [tier ladder](/kweli/verification/#the-four-tier-ladder).

## Example: integrating from Nhimbe

An event on Nhimbe is hosted at a venue. Nhimbe shows the venue's badge and offers a verify CTA when the venue is unverified:
An event on Nhimbe is hosted at a place. Nhimbe shows the place's badge and offers a verify CTA when the place is unverified:

```tsx
// Badge: read-only, straight from the graph document
Expand Down
10 changes: 5 additions & 5 deletions site/src/content/docs/kweli/overview.mdx
Original file line number Diff line number Diff line change
@@ -1,18 +1,18 @@
---
title: Mukoko Kweli overview
description: What Mukoko Kweli is — the public renderer of the Mukoko geographic knowledge graph for Africa and the ecosystem's venue-verification surface.
description: What Mukoko Kweli is — the Africa Trust Platform, the places-and-verification backbone of the Mukoko geographic knowledge graph.
sidebar:
label: Overview
---

import { Aside } from '@astrojs/starlight/components';

[kweli.mukoko.com](https://kweli.mukoko.com) is the **public-facing renderer of the Mukoko geographic knowledge graph for Africa**. Every venue in the graph — a national park, a restaurant, a school, a tech company, an NGO, a landmark, a government office — has exactly one canonical page. That page is the venue's identity to the world: name, type, location with an inline map, hours, photos, operating organization, reviews, trust score, and verification badge.
[kweli.mukoko.com](https://kweli.mukoko.com) is the **Africa Trust Platform** — the places-and-verification backbone of the Mukoko geographic knowledge graph. It is not a venue app: Kweli owns three trust journeys for the whole ecosystem — **place verification, organization verification, and person verification** — and publicly renders the graph it verifies. Every place in the graph — a national park, a restaurant, a school, a tech company, an NGO, a landmark, a government office — has exactly one canonical page. That page is the place's identity to the world: name, type, location with an inline map, hours, photos, operating organization, reviews, trust score, and verification badge.

_Kweli_ means "truth" in Swahili. The trust score **is** the kweli — it travels with every entity across the whole Mukoko ecosystem. Kweli is also the ecosystem's single venue-verification surface: sibling apps never build their own verification (see [Cross-app verification](/kweli/cross-app-verification/)).
_Kweli_ means "truth" in Swahili. The trust score **is** the kweli — it travels with every entity across the whole Mukoko ecosystem. Kweli is the ecosystem's single verification surface: sibling apps never build their own verification (see [Cross-app verification](/kweli/cross-app-verification/)). Growing the graph is agentic too — the **fundi-ingestion** Worker (in the Kweli repo, `workers/fundi-ingestion/`) turns regions into tier-0 place and entity records, and Kweli's admin sync submits tasks to it.

<Aside type="note">
The user-facing term is always **venue** — broad and entity-type-agnostic, not nightlife-specific. Legacy "bars" naming in some routes is an inherited artifact being refactored away.
The canonical term is **place** — the graph's own noun, broad and entity-type-agnostic. "Venue" in some existing copy and component names, like the legacy "bars" routes, is an inherited artifact being refactored away.
</Aside>

## Data model
Expand All @@ -21,7 +21,7 @@ The graph lives in MongoDB. Every collection `_id` is a **UUID string** (not an

| Collection | Role |
|------------|------|
| `places.places` | The **venue anchor** — 15k+ documents across 21 countries. Name, slug, `placeType` array, address, `geo`, `hierarchy` (country/province), `ownerEntityId`, translations, media. |
| `places.places` | The **place anchor** — 15k+ documents across 21 countries. Name, slug, `placeType` array, address, `geo`, `hierarchy` (country/province), `ownerEntityId`, translations, media. |
| `places.placesGeo` | Administrative geography — continent, country, province, city, town, village documents with ISO codes and GeoJSON centroids/boundaries. |
| `places.categories` | The category taxonomy — 21 categories mapping `categorySlug` → schema.org `@type`(s). |
| `entity.entities` | The owning **organization** node — every place has an `ownerEntityId` pointing here. |
Expand Down
2 changes: 1 addition & 1 deletion site/src/content/docs/kweli/verification.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ after tier 3 is held.

## Starting a verification

Representatives do not need a deep link: [`kweli.mukoko.com/en/verify`](https://kweli.mukoko.com/en/verify) is the flow's front door. It offers a venue finder (search the graph by name), the signed-in user's owned venues and pending claims with status chips, and the tier-ladder explainer. Sibling apps can still deep-link a specific venue — see [Cross-app verification](/kweli/cross-app-verification/).
Representatives do not need a deep link: [`kweli.mukoko.com/en/verify`](https://kweli.mukoko.com/en/verify) is the flow's front door. It offers a place finder (search the graph by name), the signed-in user's owned places and pending claims with status chips, and the tier-ladder explainer. Sibling apps can still deep-link a specific place — see [Cross-app verification](/kweli/cross-app-verification/).

## The claim flow

Expand Down
Loading