Part I
Project Overview & Vision
The Kalenjin Digital Heritage Platform is a community-first initiative to build the most comprehensive, living digital archive of Kalenjin language, culture, identity, and knowledge — accessible to every Kalenjin anywhere in the world.
§ 1 · Executive Summary
Executive Summary
The Kalenjin people constitute one of Kenya's largest ethnic groups, comprising roughly 6.4 million people across numerous related sub-groups and dialects — among them the Nandi, Kipsigis, Tugen, Marakwet, Pokot, Sabaot, Terik, and Ogiek. Despite their remarkable achievements in athletics, politics, agriculture, and education, the Kalenjin have no centralised digital infrastructure that preserves their language, culture, and collective identity for present and future generations.
This document specifies the complete system design for the Kalenjin Digital Heritage Platform (KDHP) — a web application, iOS/Android mobile application, and shared FastAPI backend that will serve as the authoritative, community-driven digital home of the Kalenjin people worldwide. The platform will combine encyclopaedic cultural documentation with social features, multimedia content, community governance, and practical services such as helplines, fundraising, and event management.
The platform is not a top-down publication. It is a living, community-owned resource in which every registered member can contribute words, definitions, cultural knowledge, stories, photographs, and audio recordings. All contributions are subject to community review, expert verification, and transparent voting processes to ensure accuracy and authenticity.
8+
Kalenjin Dialects Covered
3
Translation Languages (Kalenjin · English · Kiswahili)
45+
Feature Modules Specified
§ 2 · Vision, Mission & Principles
Vision, Mission & Guiding Principles
Vision Statement
A world in which every Kalenjin person — whether living in Eldoret, Nairobi, London, Houston, or Melbourne — has instant, rich access to their language, heritage, and community, and where the Kalenjin contribution to humanity is fully visible and celebrated.
Mission Statement
To build and sustain a free, community-governed digital platform that preserves and promotes the Kalenjin language, culture, traditions, achievements, and identity across all dialects and generations, enabling every Kalenjin person to connect, learn, contribute, and belong.
Guiding Principles
Community Ownership
The platform belongs to the Kalenjin community. No single corporation or individual controls its content or direction.
Open Access
Core content — language, culture, history — is freely accessible without registration. Contribution and social features require an account.
Accuracy First
Community voting, expert review, and dialect tagging ensure that every definition and cultural record is authentic and correctly attributed.
Mobile-First
The majority of Kalenjin users access the internet via mobile. The React Native app is treated as the primary client, not a secondary one.
Diaspora Inclusive
Features and content explicitly serve Kalenjin communities across Kenya, East Africa, and the global diaspora equally.
Accountability
A structured, governed system to surface misconduct and recognise excellence — in the spirit of traditional Kalenjin social accountability.
§ 3 · Project Scope & Goals
Project Scope & Goals
The platform is divided into three delivery phases over an estimated 18-month initial build period, with ongoing community-driven expansion thereafter.
In-Scope Features
- Multi-dialect Kalenjin language dictionary with English and Kiswahili translations
- Audio pronunciation recordings and community-submitted phonetic transcriptions
- Cultural encyclopaedia covering traditions, ceremonies, rites of passage, food, clothing
- Notable people directory (athletes, politicians, academics, artists, entrepreneurs)
- Kalenjin music library — songs, artists, mixtapes, and streaming links
- Geographic distribution maps (historical and current), including diaspora mapping
- Organizations and communities directory (local and diaspora)
- Community helplines and support resources
- Content creators directory and support ecosystem
- Innovations showcase
- Events and ceremonies calendar with RSVP and virtual streaming support
- Community accountability and public recognition system
- Education resources, scholarships, and mentorship matching
- Fundraising and contribution platform
- Full community contribution, review, and voting system
- Discussion forums and comment threads
- User profiles with contribution history and reputation scores
- Moderation dashboard for elected community moderators
- Push notifications (mobile) and email notifications (web)
- Multi-language UI (English, Kiswahili)
Explicitly Out-of-Scope (v1)
- AI-generated language learning (planned for Phase 3)
- Live video streaming infrastructure (third-party embeds used instead)
- Native payment processing (third-party providers used)
- Native e-commerce or marketplace
§ 4 · Stakeholders
Stakeholders & User Roles
| Stakeholder Type | Description | Primary Needs | Platform Role |
|---|---|---|---|
| Community Members | General Kalenjin public — local and diaspora | Access language, culture, news, events; connect with community | Visitor / Member |
| Contributors | Active members who submit words, cultural records, corrections | Share knowledge, earn reputation, correct inaccuracies | Contributor |
| Elders & Knowledge Holders | Culturally authoritative individuals verified by community | Preserve authentic cultural knowledge; validate submissions | Cultural Expert |
| Content Creators | Musicians, YouTubers, podcasters, bloggers producing Kalenjin content | Audience growth, collaboration, monetisation support | Creator |
| Organizations | Community orgs, diaspora groups, NGOs, cultural associations | List services, announce events, recruit members | Organisation |
| Moderators | Community-elected moderators responsible for content quality | Review contributions, resolve disputes, enforce policies | Moderator |
| Administrators | Platform technical and governance administrators | System health, policy enforcement, elections | Admin |
§ 5 · Kalenjin Dialects
Kalenjin Dialects Overview
The Kalenjin are not a single homogeneous group but a cluster of closely related Nilotic peoples who share linguistic and cultural commonalities. The platform must handle dialect-aware content throughout — every word, proverb, and cultural record must be correctly attributed to its dialect(s), and variations across dialects must be explicitly preserved rather than flattened into a single standard.
| Dialect / Sub-group | Primary Region(s) | Approx. Speakers | ISO Code | Notes |
|---|---|---|---|---|
| Nandi | Nandi County, Uasin Gishu | ~900,000 | niq | Largest sub-group; forms basis of "standard" Kalenjin |
| Kipsigis | Kericho, Bomet | ~1,500,000 | sgc | Most numerous; significant diaspora in UK and USA |
| Tugen | Baringo County | ~200,000 | tuy | Ancestral home of Lake Baringo region |
| Marakwet | Elgeyo-Marakwet County | ~150,000 | enb | Famous irrigation farmers of the Elgeyo escarpment |
| Pokot (West) | West Pokot, Trans-Nzoia | ~600,000 | pko | Also has communities in Uganda; semi-pastoralist |
| Sabaot | Mount Elgon | ~200,000 | spy | Also in Uganda; strong mountain cultural identity |
| Terik | Nandi / Kakamega border | ~50,000 | tec | Endangered; significant Luhya assimilation pressures |
| Ogiek (Dorobo) | Mau Forest, Mount Kenya | ~25,000 | oki | Hunter-gatherers; UNESCO endangered language status |
| Elgeyo | Elgeyo-Marakwet County | ~150,000 | eyo | Closely related to Marakwet; some classify as one group |
| Sebei | Eastern Uganda | ~100,000 | sbs | Ugandan Kalenjin; important diaspora connection |
Design Note — Dialect Neutrality
The platform must never privilege one dialect as more "correct" than another. Every dialect is treated as equally valid. The UI will allow users to filter views by dialect and will always show dialect attribution alongside every word or cultural entry. The system uses a
dialect_id foreign key on all language content, and entries may be tagged with multiple dialects when shared.
✦ ✦ ✦
Part II
Feature Specification
A detailed specification of every feature module. Each module defines its purpose, user stories, data requirements, and functional rules. Every module has been designed to work in both the web app and the React Native mobile app via the shared FastAPI backend.
§ 6 · Feature Module
Language & Dictionary Module
The language module is the core and most critical module of the platform. It serves as the definitive community-driven dictionary of all Kalenjin dialects, with rich metadata, audio pronunciations, usage examples, etymology, and community-verified definitions in Kalenjin, English, and Kiswahili.
6.1 Word Database
Each word entry is a rich, multi-layered record. Words are not simplified to single definitions — the system captures the full spectrum of meaning, context, dialect variation, and usage.
Word Entry Fields
- Headword — The word in Kalenjin script (using the agreed romanisation system and/or any community-adopted orthography)
- Phonetic Transcription — IPA (International Phonetic Alphabet) notation
- Dialect Tags — One or more dialects this form belongs to
- Part of Speech — Noun, verb, adjective, adverb, pronoun, particle, interjection, idiomatic phrase, proverb
- Word Class — Noun class / gender marker where applicable
- Root / Etymology — Proto-Kalenjin root, loanword origin, or derivation history
- Primary Definition (Kalenjin) — Definition stated in Kalenjin
- English Definition — Accurate English translation and definition
- Kiswahili Definition — Accurate Kiswahili translation and definition
- Usage Examples — Multiple example sentences with translations in all three languages
- Audio Pronunciation(s) — Up to one recording per dialect variant, contributed by native speakers
- Tone Marks — Tone pattern notation (Kalenjin languages are tonal)
- Register — Formal, informal, archaic, sacred/ceremonial, children's speech, etc.
- Semantic Domain — Categorisation: agriculture, body, family, animals, celestial, warfare, emotions, etc.
- Related Words — Synonyms, antonyms, derived forms, compound words
- Cultural Notes — Contextual notes about the cultural significance or usage context of the word
- Images — Optional illustrations (especially for nouns: plants, tools, animals, clothing)
- Status — Pending Review, Community Reviewed, Expert Verified, Disputed, Archived
- Contributor — User who submitted the entry
- Revision History — Full version history of all edits with contributor attribution
- Vote Score — Community upvote/downvote tally
Alternate Dialect Forms
A word in one dialect may have a phonologically different form in another dialect while referring to the same concept. The system handles this through a concept-centric model: a single Concept entity groups all dialect-specific word forms together. This means searching for a Nandi word can optionally surface the equivalent Kipsigis form of the same concept.
6.2 Dialect Variation System
Dialect variation is a first-class concern, not an afterthought. The UI provides a Dialect Filter component that persists in the user's profile. When a user sets their dialect preference, all dictionary views, search results, and pronunciation playback default to that dialect, while still showing cross-dialect comparisons on demand.
- Dialect Comparison View — Side-by-side table of how the same concept is expressed in each dialect, with audio for each
- Dialect Change Tracker — Shows words that have shifted in meaning, pronunciation, or usage between dialects over time
- Dialect-Only Browse — Browse the dictionary filtered to a single dialect
- Missing Dialect Coverage Alerts — Community-visible flags on concepts that have no entry for a specific dialect, prompting community contributions
6.3 Pronunciation & Audio System
Kalenjin is a tonal language family. Correct pronunciation is inseparable from correct meaning. The platform implements a full audio infrastructure for community-contributed pronunciation recordings.
Technical Requirement
Audio files are stored in the media object store (S3-compatible) and served via CDN. All audio is encoded as AAC at 64kbps for bandwidth efficiency while maintaining quality adequate for phonological study. The mobile app caches frequently accessed audio locally.
- In-Browser Recording — Users can record pronunciations directly in the web app using the MediaRecorder API. Recordings are transcoded server-side to AAC.
- In-App Recording — React Native Expo AV library is used for mobile recording.
- Multiple Recordings Per Word — Each word/dialect pair can have multiple submitted recordings. The community votes to surface the most accurate/clear recording as the primary.
- Speaker Metadata — Each recording is tagged with the speaker's claimed dialect, age group, and home region (anonymised if requested).
- Audio Waveform Visualisation — A lightweight waveform display is shown on word detail pages.
- Tone Pattern Diagram — Visual tone pattern (H/L marks or musical staff representation) linked to each pronunciation.
- Slow Playback — Playback at 0.75x and 0.5x speed for learners.
6.4 Translation & Definition Engine
Every word entry must have definitions in three languages: Kalenjin (dialect-specific), English, and Kiswahili. The system also supports phrase-level translation for common expressions, proverbs, and idioms.
- Search in Any Language — Users can type a word in English or Kiswahili and find the Kalenjin equivalent(s) and vice versa.
- Fuzzy Search — Powered by Elasticsearch, fuzzy matching handles common spelling variations and incomplete entries.
- Phrase Search — Multi-word queries resolve to idioms and proverbs as well as individual words.
- Definition Versioning — All submitted definitions are versioned. The current accepted definition is the one with the highest community vote score that has also passed moderation review.
- Competing Definitions — Multiple definitions for the same word can coexist if they represent genuinely different usages, dialects, or registers. The community votes to rank them; all are shown.
- Machine Translation Assist — Optional AI-assisted translation suggestions (using an external translation API, never shown to users as definitive — only as a contribution aid with a clear disclaimer).
6.5 Community Voting & Verification
Community voting is the primary quality assurance mechanism for language content. The voting system is designed to surface accurate, authentic content while discouraging gaming and factionalism.
Voting Mechanics
- Every registered user can cast one upvote or downvote on any definition, pronunciation recording, or cultural entry.
- Users cannot vote on their own submissions.
- Vote weights are influenced by the voter's Reputation Score and their declared expertise in the relevant dialect.
- A Cultural Expert badge holder's upvote carries 3× the weight of a standard member vote on language definitions.
- Definitions that receive a configurable net upvote threshold (e.g. +15) advance to Community Reviewed status.
- Cultural Experts can grant Expert Verified status after reviewing Community Reviewed entries.
- Disputed definitions (those with significant downvotes relative to upvotes) are flagged and sent to a Moderator Review queue.
- All vote tallies are publicly visible. Vote manipulation (sockpuppeting, coordinated voting) is a bannable offence monitored algorithmically.
Verification Levels
| Status | Criteria | Icon | Who Can Grant |
|---|---|---|---|
| Pending | Newly submitted, not yet reviewed | ⏳ | Auto (system) |
| Community Reviewed | Net +15 community votes with no open disputes | ✅ | Auto (system) |
| Expert Verified | Approved by ≥1 Cultural Expert of the relevant dialect | 🏅 | Cultural Expert |
| Disputed | Net negative votes or open dispute flag | ⚠️ | Community / Moderator |
| Archived | Obsolete or superseded; preserved for history | 📦 | Moderator |
6.6 Language Learning Features
Beyond being a reference dictionary, the platform includes structured learning paths to help diaspora members, children of Kalenjin parents, and interested outsiders learn the language.
- Thematic Word Sets — Curated vocabulary groups: greetings, family terms, numbers, colours, body parts, common verbs, food vocabulary, etc.
- Flashcard Mode — Spaced-repetition flashcard practice for any word set or dialect.
- Daily Word — A featured word of the day with full entry details, pronunciation, and cultural context, delivered via push notification to subscribed users.
- Phrasebook — A conversational phrasebook organised by situation: greetings, visiting a home, market transactions, ceremonies, medical emergencies.
- Grammar Guide — Community-authored grammar notes per dialect covering noun classes, verb tenses, tone rules, and sentence structure.
- Contribution Challenges — Gamified challenges that encourage community members to record pronunciations for words that lack audio, or to submit translations for words in underrepresented dialects.
- Progress Tracking — Users can track words they have studied, with a personal vocabulary dashboard.
§ 7 · Feature Module
Culture & Traditions Module
A living encyclopaedia of Kalenjin culture. This module covers every dimension of traditional and contemporary Kalenjin life, documented in rich multimedia form with dialect and regional attribution.
7.1 Rites of Passage & Ceremonies
The Kalenjin have a highly structured system of age-sets (ipinda) and rites of passage that define social identity and responsibility. Each rite is documented as a structured article with multimedia support.
- Initiation (Tumdo) — The circumcision ceremony, its preparation, songs, dress, rules, regional variations, the role of the kiptaiyat (instructor), and post-initiation responsibilities
- Age-Set System — Documentation of all named age-sets, their historical periods, responsibilities, and current elders; interactive age-set timeline
- Marriage Customs — Courtship traditions, bride wealth (kipsaet) practices per dialect, wedding ceremonies, songs, obligations of in-laws
- Birth & Naming Ceremonies — Birth customs, naming conventions (including the significance of names), first-naming ceremonies, taboos
- Death & Mourning Rites — Funeral customs, mourning dress and behaviour, the role of community, difference between "good" and "bad" deaths in Kalenjin belief, post-burial rites
- Harvest Ceremonies — Agricultural rituals, first-fruits offering, community celebrations
- Rain-Calling Ceremonies — Traditional rainmaking rituals, relevant to the Elgeyo, Marakwet, and Tugen groups in particular
- The Kokwet System — The traditional community council, its procedures, the role of the kiruogindet (spokesman), dispute resolution processes
7.2 Clothing, Adornment & Material Culture
Traditional Kalenjin clothing and adornment are rich, dialect-specific, and deeply symbolic. The platform documents these with high-quality photographs, detailed descriptions, and purchase/artisan links where available.
- Traditional Dress per Dialect — Documented with photography: shukas, beadwork patterns, hide garments, headwear by gender and age-set
- Beadwork Encyclopaedia — Bead colours, their meanings (which vary by dialect), patterns for different occasions, how to read beadwork
- Ceremonial Attire — Specific dress for initiation, marriage, warfare, rain ceremonies, elder councils
- Traditional Tools & Artefacts — Hunting tools, agricultural implements, musical instruments, household items, with Kalenjin names in all dialects
- Contemporary Kalenjin Fashion — Modern adaptations of traditional elements; community submissions of outfits and designs
- Artisan Directory — Verified directory of Kalenjin artisans and craftspeople making traditional items, with contact information
7.3 Food, Cuisine & Agriculture
- Traditional Foods Encyclopaedia — Entries for every traditional Kalenjin food and drink: mursik (fermented milk), ugali variations, kimyet, traditional meats, vegetables, with Kalenjin names per dialect
- Recipes with Cultural Context — Community-contributed recipes, each framed with the cultural setting in which the dish is eaten
- Agricultural Heritage — Documentation of traditional Kalenjin agricultural practices, crop varieties, the Marakwet irrigation furrow system (enkanit), livestock breeds
- Food Calendar — What is traditionally eaten at each season, ceremony, or life event
- Medicinal Plants — Traditional herbal knowledge: plant names in all dialects, preparation methods, conditions treated
7.4 Proverbs, Oral Literature & Belief
- Proverb Database — Full database of Kalenjin proverbs with dialect attribution, literal translation, figurative meaning, and usage context in all three languages
- Riddles (Tegeret) — Traditional riddles with answers, dialect variants, and the age/occasion context in which they are used
- Folk Stories & Oral Histories — Community-submitted and expert-verified oral history recordings and transcriptions
- Traditional Religion & Belief — Documentation of the traditional Kalenjin cosmology, the concept of Asis (the sun/god), ancestor veneration, sacred sites, and the role of orgoiyot (prophet/diviner)
- Historical Narratives — Community-documented oral history of major historical events: the Uasin Gishu plateau settlement, colonial-era interactions, land dispossession, migration narratives
- Tongue Twisters & Children's Songs — Language play for younger learners
§ 8 · Feature Module
Notable People Module
A comprehensive directory celebrating the achievements of Kalenjin people across every field of human endeavour. This is not a hall of fame with a curated few — it aspires to document every verifiable Kalenjin achievement, from world-record-breaking athletes to local innovators and village teachers who transformed their communities.
Person Profile Fields
- Full name (and Kalenjin name if different), date of birth, home region, dialect/sub-group
- Field of achievement (multi-select): Athletics, Politics, Academia, Business, Arts/Music, Medicine, Law, Sports (other), Military, Community Leadership, Education, Agriculture, Technology, Environment, Journalism, NGO/Civil Society, Religion
- Biography (community-contributed, Expert Reviewed)
- Key achievements list with dates and sources
- Profile photograph and media gallery
- Links to verifiable external sources (Wikipedia, news archives, official records)
- Contributions to the Kalenjin community specifically
- Quotes / interviews
- Social media / contact links (if public figure)
- Status: Living / Deceased
Category Highlights
Athletes
World records, Olympic medals, marathon victories. Includes dedicated race results database for Kalenjin athletes. Links to World Athletics profiles.
Politicians & Leaders
National and county government officials, historical leaders, presidents (Daniel arap Moi), governors, senators. Community rating of their service to the Kalenjin community.
Academics & Professionals
Professors, doctors, researchers, engineers. Includes a mentorship request feature connecting students with Kalenjin professionals in their field.
Artists & Musicians
Traditional and contemporary musicians, visual artists, photographers, filmmakers. Linked to the Music module.
Business & Entrepreneurs
Founders, executives, and innovators. Links to their ventures and a brief on how they give back to the community.
Community Champions
Unsung heroes — village health workers, teachers, conservation leaders, youth mentors. Nominated and documented by community members.
Integrity Policy
Person profiles are among the highest-trust content on the platform. All profiles require a minimum of two independent community-submitted source citations. Profiles of living persons require the subject's consent (or a verified family member's consent) before publication, or rely entirely on information already in the public domain with clear source attribution. An opt-out request mechanism is provided.
§ 9 · Feature Module
Music & Entertainment Module
Kalenjin music is a vibrant, evolving art form spanning traditional ceremonial chants, contemporary Kalenjin-language pop, benga, hip-hop, gospel, and diaspora fusions. This module serves as the definitive library and community hub for Kalenjin music.
9.1 Songs & Tracks Library
- Song Entry Fields: Title (Kalenjin and English), artist(s), album, dialect, genre, year, lyrics (in Kalenjin with transliteration and English/Kiswahili translation), audio preview (30-second clip), full streaming links (Spotify, Apple Music, YouTube, Boomplay, Audiomack)
- Traditional Songs: Ceremonial songs categorised by occasion (initiation, wedding, harvest, war, mourning), with cultural context notes and audio recordings by community elders
- Age-Set Songs: Songs specific to each age-set, documented with historical context
- Contemporary Music: All genres, community-submitted or officially contributed by artists
- Lyric Submissions: Community-contributed song lyrics with translation, subject to moderation
- Song of the Week: Editorially selected feature, surfaced on home page
9.2 Artist Profiles
Dedicated artist pages with biography, discography, genre tags, dialect of performance, social links, and upcoming events. Artists can claim their profiles through a verification process.
9.3 Mixtapes & Playlists
- Community Playlists: Any registered user can create and share a playlist of Kalenjin songs from the library
- Official Mixtapes: Curated mixtapes produced by platform editors or guest DJs, with track-listing linked to the song database
- Thematic Collections: Best of Nandi wedding songs, Kipsigis gospel, traditional chants, diaspora hip-hop, etc.
- Downloadable Mixtape Metadata: Track lists available as PDF for offline reference
9.4 Music Forum & Community
- Discussion threads attached to each song and artist page
- Community ratings (1–5 stars) for songs and albums
- Artist collaboration requests board
- Talent Discovery section: emerging artists can submit demo tracks for community feedback
§ 10 · Feature Module
Geography & Distribution Module
An interactive cartographic and encyclopaedic resource documenting where Kalenjin people live, have historically lived, and are currently distributed across the globe.
10.1 Historical Geography
- Animated timeline maps showing Kalenjin migration from their Nilotic origins through present day
- Historical territory documentation per sub-group with source citations
- Colonial-era land dispossession documentation (Uasin Gishu Plateau, Maasai-Kalenjin boundaries)
- Pre-colonial inter-group relationships and alliances mapped geographically
- Sacred sites and historically significant locations
10.2 Current Distribution in Kenya
- County-level population data with dialect breakdown (sourced from KNBS census data)
- Interactive choropleth map of Kalenjin population density by county
- Sub-county and ward level granularity where data is available
- Urban concentration mapping: Nairobi, Nakuru, Eldoret, Kisumu concentrations
10.3 Global Diaspora Map
- Community-contributed diaspora data: users can voluntarily register their city/country of residence
- Heatmap of self-reported diaspora concentration by country and city
- Links from each diaspora location to the local Kalenjin organisations in that city
- Diaspora count statistics per country, updated dynamically from community contributions
- Diaspora stories: community members can submit short "where I am now" stories linked to their pin on the map
10.4 Places Encyclopaedia
- Kalenjin names for geographical features: mountains, rivers, valleys, forests, towns
- Etymology and meaning of place names
- Sacred sites with cultural significance documented and protected (some information restricted to Cultural Expert access by community decision)
§ 11 · Feature Module
Organizations & Communities Module
11.1 Organisation Directory
A comprehensive, searchable directory of every Kalenjin-affiliated organisation. Organisation types include: cultural associations, welfare groups, investment/chama groups, diaspora associations, political constituencies, youth groups, women's groups, sports clubs, religious congregations, NGOs, and professional networks.
Organisation Profile Fields
- Name, type, founding year, dialect/sub-group affiliation
- Geographic scope: local (ward/sub-county), national, international, diaspora (with country)
- Mission statement, activities, and membership criteria
- Contact information (address, phone, email, website, social media)
- Leadership directory (optional, with consent)
- Recent announcements and events
- Community rating and reviews
- Verification status (claimed and verified by the organisation itself)
11.2 Helplines & Support Resources
A curated, verified directory of helplines and support services relevant to Kalenjin community members — both within Kenya and in diaspora countries.
| Category | Examples | Fields |
|---|---|---|
| Mental Health | Kenya Red Cross psychosocial support, diaspora counselling services | Name, phone, website, hours, language(s) supported, cost |
| Legal Aid | Land rights legal aid (especially relevant to Kalenjin land tenure issues), immigration advice for diaspora | Name, type, jurisdiction, contact, languages |
| GBV & Domestic Violence | Kenya GBV hotlines, diaspora shelter referrals | 24/7 flag, anonymous contact option, safe exit button |
| Youth Support | Drug rehabilitation, unemployment counselling | Age range, services, contact |
| Financial Assistance | Community welfare funds, emergency chama loans | Eligibility, application process, contact |
| Elder Care | Community elder visitation programmes | Region, volunteer contact, services offered |
| Education & Scholarship | HELB, Kalenjin-specific bursary funds | Eligibility, deadlines, application link |
Safety Design Requirement
The Helplines section must include a Quick Exit button (especially in the GBV section) that immediately navigates to a neutral page (e.g., Google) and clears browser history of the helplines page. This is an accessibility and safety requirement, not a feature suggestion. It must be implemented in both web and mobile apps.
§ 12 · Feature Module
Content Creators Module
A dedicated ecosystem for Kalenjin content creators — YouTube channels, podcasters, bloggers, TikTokers, Instagram pages, Twitter/X accounts, and newsletter writers — who produce content about or for the Kalenjin community in any language.
12.1 Creator Profiles
- Creator name, bio, content type(s), platform links, language(s) of content, dialect focus
- Content categories: Language Teaching, Culture Documentation, News & Commentary, Entertainment, Music, Sports, Religion, Business & Finance, Diaspora Life
- Latest content feed (RSS/API integration where available — YouTube RSS, podcast RSS, etc.)
- Community subscriber/follower count shown alongside platform native counts
- Creator verification badge (confirmed identity)
- Community support links (Patreon, buy-me-a-coffee, M-Pesa number, bank details for bank transfers)
12.2 Creator Support & Collaboration
- Collaboration Board — Creators can post requests for collaborators (e.g., "Looking for a Nandi dialect speaker for my language series")
- Equipment & Skill Exchange — Community members offering editing skills, recording space, translation services
- Creator Fund — A community fund (fed by platform donations) that awards small grants to emerging creators who apply and are voted on by the community
- Content Challenge Sponsorship — Partner organisations can sponsor content challenges with prize pools
- Resource Library — Shared bank of royalty-free Kalenjin music, stock photography, and design templates for creators to use
§ 13 · Feature Module
Innovations Module
Documenting and celebrating Kalenjin-origin innovations across all fields, from traditional agricultural engineering to modern technology startups.
- Innovation Profiles — Description, innovator(s), problem solved, impact, status (concept/prototype/deployed), categories: Agriculture, Water, Energy, Technology, Health, Education, Community Organisation
- Traditional Innovations — The Marakwet furrow irrigation system, traditional beehive construction, communal cattle management systems
- Technology Startups — Kalenjin-founded or Kalenjin-led tech ventures with descriptions, investment status, and links
- Patents & Research — Kalenjin academics and inventors who hold patents or have published significant research
- Open Innovation Board — Community members can post problems facing the community and invite solution proposals, which are voted on
- Innovation Forum — Discussion space for technology, agriculture, and community problem-solving
§ 14 · Feature Module
Events & Ceremonies Module
14.1 Event Calendar
A unified calendar of Kalenjin events worldwide — cultural ceremonies, community meetings, sports events, diaspora gatherings, fundraisers, concerts, and educational programmes.
Event Entry Fields
- Title, description, organiser (linked to Organisation profile or individual)
- Type: Cultural Ceremony, Sports, Concert/Entertainment, Meeting, Conference, Fundraiser, Religious, Educational, Diaspora Gathering
- Date(s) and time with timezone handling
- Location: Physical address (with map pin) and/or virtual (stream link)
- Dialect/sub-group relevance
- Admission: Free, Ticket (with external ticketing link), Invitation-only
- RSVP count (for events that enable it)
- Media gallery: post-event photos and recordings
- Discussion thread
14.2 Traditional Ceremony Calendar
Many Kalenjin ceremonies follow seasonal or cyclical schedules. This sub-module maintains a community-informed calendar of traditional ceremonies including initiation seasons, harvest festivals, and community councils, with guidance on appropriate visitor conduct.
14.3 RSVP & Attendance
- Users can RSVP to public events; RSVP counts are visible
- Organisers can optionally require RSVP approval (gated attendance)
- Reminder push notifications 48 hours and 1 hour before an event the user has RSVPed to
- Post-event prompt to submit photos and write a review
§ 15 · Feature Module
Community Accountability & Recognition System
Traditional Kalenjin society had sophisticated mechanisms for social accountability through the kokwet (community council), age-set peer pressure, and public praise or censure. This module digitises these principles in a fair, governed, and legally defensible way.
Legal & Ethical Warning
This module carries significant legal risk if implemented carelessly. Public callouts of named individuals can constitute defamation if the claims are false. The system must require verifiable evidence before any name is published, include a due process period in which the named party can respond, require Moderator approval before publication, and maintain a clear appeals and retraction process. Legal counsel must review the moderation policy before this feature goes live. Platform terms of service must clearly address this module.
15.1 Community Recognition (Praise)
- Community Champion Nominations — Any member can nominate any individual for a Community Champion recognition
- Nominations require a written description of the act/service, the nominator's identity (not anonymous), and any supporting evidence
- Community voting determines whether the nomination achieves recognition
- Published recognitions are tied to the honoured person's profile or a new profile created with their consent
- Tiered recognition: Local Champion, County Champion, National Champion, Diaspora Champion
15.2 Community Accountability (Callout)
- Accountability Report Submission — Registered users can submit an accountability report against a named individual or organisation
- Required fields: nature of misconduct (categorised), evidence (documents, screenshots, witness statements), relationship of reporter to the matter
- All reports are anonymous to the public during the review phase but reporter identity is known to Moderators
- Due Process Period — The named party is notified privately and given 14 days to submit a response before any public action is taken
- Moderator Panel reviews both sides and votes on publication
- Published reports include both the accusation and the response (if provided) — never accusation-only
- Categories: Financial Fraud, GBV, Child Abuse, Corruption (public office), Land Grabbing, Cultural Appropriation, Misrepresentation
- False reports result in the reporter's account suspension; serial false reporters are permanently banned
- Retraction & Resolution — If a matter is resolved, both parties can jointly request that the report be marked "Resolved" with an explanation
§ 16 · Feature Module
Education & Help Module
16.1 Scholarship & Bursary Database
- Searchable directory of scholarships and bursaries available to Kalenjin students at all levels
- Sources: Government constituency bursaries, NGO scholarships, diaspora-funded scholarships, university-specific awards
- Fields: name, funder, amount, eligibility (sub-group, county, level of study, academic criteria), deadline, application link
- Deadline reminder: users can subscribe to deadline alerts for specific scholarships
- Community-submitted bursary opportunities with moderation before publication
16.2 Mentorship Programme
- Mentors register their expertise, availability, preferred communication method, and eligible mentee profile
- Students/young professionals apply for mentorship by field and career level
- Matching algorithm considers field alignment, dialect/region preference, time zone, and availability
- Structured mentorship: platform provides session templates, goal-setting tools, and progress check-in prompts
- Mentorship feed: mentors can share career advice posts visible to all members
16.3 Job Board
- Jobs posted by Kalenjin-owned businesses, organisations, and employers who actively recruit Kalenjin talent
- Any organisation can post (moderated); users can apply with a profile link
- Fields: role, employer, location, salary range, deadline, application instructions
16.4 Educational Resources Library
- Community-uploaded educational materials: study guides, past exam papers, research papers on Kalenjin language and culture, government policy documents relevant to Kalenjin regions
- Kalenjin-authored academic works database
- Primary and secondary school Kalenjin language teaching resources
§ 17 · Feature Module
Fund & Contributions Module
Financial Compliance Note
All payment processing is handled by trusted third-party providers (M-Pesa Daraja API, Stripe, PayPal, Flutterwave). The platform itself does not hold, transfer, or custody funds. Each campaign is managed by the organising party and the platform serves as a discovery and accountability layer only. Funds transparency reports are required for all platform-listed campaigns.
17.1 Platform Sustainability Fund
- Community members can make one-time or recurring donations to support platform operations
- Donors are publicly acknowledged (with consent) on a Supporters page
- Transparent public spending dashboard: where donations go, current platform costs, reserve balance
17.2 Community Fundraising Campaigns
- Any verified organisation or individual can launch a fundraising campaign after Moderator approval
- Campaign fields: title, purpose, target amount, deadline, organiser identity (verified), payment channels, progress updates
- Campaign categories: Education (bursary fundraising), Medical Emergency, Community Infrastructure, Cultural Preservation, Disaster Relief, Business Startup
- Progress bar and donor count shown publicly
- Mandatory progress reports at 50% and 100% of goal, and at campaign close
- Completion report: how funds were used, with receipts or evidence
17.3 Community Investment Pool (Chama)
- Digital infrastructure for community savings and investment groups
- Members can join or create a digital chama, record contributions, and vote on investment decisions
- Contribution ledger visible to all chama members
- Investment proposal and voting system
- This module integrates with M-Pesa for contribution tracking
§ 18 · Feature Module
Community Contribution Model
The entire platform is built on community-contributed content. This section defines exactly how contributions work, how quality is maintained, and how contributors are recognised and rewarded.
18.1 Contributor Reputation System
A transparent, multi-dimensional reputation score that reflects the quality, volume, and accuracy of a user's contributions over time.
| Action | Reputation Points |
|---|---|
| Submit a word entry (approved) | +10 |
| Submit a word entry (Community Reviewed) | +20 |
| Submit a word entry (Expert Verified) | +50 |
| Submit a pronunciation recording (accepted) | +15 |
| Submit a cultural article (approved) | +25 |
| Submit a correction that is accepted | +8 |
| Receive an upvote on any contribution | +2 |
| Receive a downvote on any contribution | -1 |
| Have a submission rejected for inaccuracy | -15 |
| File a false accountability report | -100 |
| Be awarded Community Champion | +500 |
18.2 Contributor Tiers & Privileges
| Tier | Points Required | Badge | Additional Privileges |
|---|---|---|---|
| New Member | 0 | 🌱 | Submit contributions, vote, comment |
| Contributor | 50 | ✏️ | Edit existing entries (subject to review), suggest dialect tags |
| Trusted Contributor | 250 | ⭐ | Vote weight ×1.5, fast-track review queue for submissions |
| Senior Contributor | 1000 | 🌟 | Nominate Cultural Experts, flag suspicious voting patterns |
| Cultural Expert | Nominated + community approval | 🏅 | Expert Verify entries, ×3 vote weight on language content |
| Moderator | Community elected | ⚖️ | Review queue access, content removal, dispute resolution |
✦ ✦ ✦
Part III
Technical Architecture
A detailed specification of the full technology stack, system design patterns, infrastructure components, and integration contracts across the React web app, React Native mobile app, and FastAPI backend.
§ 19 · Architecture
Architecture Overview
The platform follows a three-tier client-server architecture with shared backend services. Both the web and mobile clients communicate exclusively through the REST API exposed by the FastAPI backend. There is no direct database access from any client.
High-Level Component Diagram
Architecture — Component Overview
┌─────────────────────────────────────────────────────────────────────┐
│ CLIENT LAYER │
│ │
│ ┌─────────────────┐ ┌──────────────────────────┐ │
│ │ React Web App │ │ React Native App │ │
│ │ (Next.js / CRA)│ │ (Expo SDK / bare) │ │
│ │ │ │ iOS + Android │ │
│ └────────┬────────┘ └──────────┬───────────────┘ │
│ │ HTTPS / REST │ HTTPS / REST │
└────────────┼───────────────────────────────┼───────────────────────┘
│ │
▼ ▼
┌─────────────────────────────────────────────────────────────────────┐
│ API GATEWAY / CDN │
│ │
│ Cloudflare (DNS + WAF + CDN + DDoS) → NGINX (load balancer) │
└──────────────────────────────┬──────────────────────────────────────┘
│
┌──────────────────────────────▼──────────────────────────────────────┐
│ FASTAPI APPLICATION LAYER │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌────────────────────────┐ │
│ │ Auth Router │ │Language Router│ │Culture / People Router │ │
│ └──────────────┘ └──────────────┘ └────────────────────────┘ │
│ ┌──────────────┐ ┌──────────────┐ ┌────────────────────────┐ │
│ │ Media Router │ │ Events Router│ │Moderation / Admin Router│ │
│ └──────────────┘ └──────────────┘ └────────────────────────┘ │
│ ┌──────────────┐ ┌──────────────┐ ┌────────────────────────┐ │
│ │ Fund Router │ │ Search Router│ │ WebSocket Manager │ │
│ └──────────────┘ └──────────────┘ └────────────────────────┘ │
└──────────────────────────────┬──────────────────────────────────────┘
│
┌──────────────────────────────▼──────────────────────────────────────┐
│ DATA & SERVICE LAYER │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌───────────────────────┐ │
│ │ PostgreSQL │ │ Redis Cache │ │ Elasticsearch 8.x │ │
│ │ (Primary DB)│ │ + Sessions │ │ (Full-text search) │ │
│ └──────────────┘ └──────────────┘ └───────────────────────┘ │
│ ┌──────────────┐ ┌──────────────┐ ┌───────────────────────┐ │
│ │ S3-compat. │ │ Celery + │ │ Firebase / APNs │ │
│ │ Object Store│ │ RabbitMQ │ │ Push Notifications │ │
│ │ (Audio/Img) │ │ (Task Queue)│ │ │ │
│ └──────────────┘ └──────────────┘ └───────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
Technology Stack Summary
| Layer | Technology | Version Target | Justification |
|---|---|---|---|
| Web Frontend | React + Next.js | Next.js 14+ | SSR/SSG for SEO, fast page loads, App Router |
| Mobile App | React Native (Expo) | Expo SDK 51+ | Cross-platform iOS/Android, shared business logic, OTA updates |
| API Backend | FastAPI (Python) | FastAPI 0.110+ | High performance, async, auto OpenAPI docs, Pydantic validation |
| ORM | SQLAlchemy + Alembic | SQLAlchemy 2.0 | Async SQLAlchemy, clean migration management |
| Primary DB | PostgreSQL | v16+ | ACID compliance, full-text search, JSONB, PostGIS for geography |
| Cache / Sessions | Redis | Redis 7+ | Session storage, API response caching, rate limiting, pub/sub |
| Search | Elasticsearch | v8.x | Multilingual full-text search, fuzzy matching, faceted search |
| Object Storage | AWS S3 / Cloudflare R2 | — | Audio files, images, documents; CDN-served |
| Task Queue | Celery + RabbitMQ | Celery 5+ | Async audio transcoding, email delivery, search indexing |
| Push Notifications | Firebase FCM + APNs | — | Android (FCM) and iOS (APNs) push notifications |
| CDN / WAF | Cloudflare | — | DDoS protection, global edge, R2 storage integration |
| Container Orchestration | Docker + Docker Compose (dev) / Kubernetes (prod) | — | Reproducible environments, horizontal scaling |
| CI/CD | GitHub Actions | — | Automated testing, deployment pipelines |
§ 20 · Frontend Architecture
Frontend — React / Next.js Web Application
20.1 Project Structure
Next.js — Directory Structure
kalenjin-web/
├── app/ # App Router (Next.js 14)
│ ├── (public)/ # Public routes (no auth)
│ │ ├── page.tsx # Home page
│ │ ├── dictionary/ # Dictionary browse
│ │ │ ├── [word]/page.tsx # Word detail page
│ │ ├── culture/ # Culture module
│ │ ├── people/ # Notable people
│ │ ├── music/ # Music library
│ │ ├── geography/ # Maps & distribution
│ │ ├── organizations/ # Org directory
│ │ ├── creators/ # Content creators
│ │ ├── events/ # Event calendar
│ │ ├── education/ # Education resources
│ │ ├── fund/ # Fundraising
│ ├── (auth)/ # Auth routes
│ │ ├── login/page.tsx
│ │ ├── register/page.tsx
│ ├── (dashboard)/ # Protected user dashboard
│ │ ├── profile/
│ │ ├── contributions/
│ │ ├── settings/
│ ├── (admin)/ # Moderator / Admin routes
│ │ ├── moderation/
│ │ ├── elections/
├── components/
│ ├── dictionary/ # Dictionary-specific components
│ │ ├── WordCard.tsx
│ │ ├── AudioPlayer.tsx
│ │ ├── DialectFilter.tsx
│ │ ├── VotingButtons.tsx
│ ├── layout/
│ │ ├── Navbar.tsx
│ │ ├── Footer.tsx
│ │ ├── Sidebar.tsx
│ ├── shared/
│ │ ├── SearchBar.tsx
│ │ ├── DialectBadge.tsx
│ │ ├── ReputationBadge.tsx
│ │ ├── MapEmbed.tsx
│ │ ├── AudioRecorder.tsx
├── lib/
│ ├── api.ts # Axios instance + interceptors
│ ├── auth.ts # NextAuth.js config
│ ├── hooks/ # Custom React hooks
│ ├── utils/ # Date helpers, formatters
├── store/ # Zustand global state
├── public/ # Static assets
└── i18n/ # i18next locale files (en, sw)
20.2 Key Web-Specific Concerns
- SEO — Next.js generates static pages (SSG) for all public dictionary entries, cultural articles, and person profiles. This ensures all content is indexable by Google. Dynamic metadata (Open Graph, Twitter Card, JSON-LD structured data) is generated per page.
- Internationalisation —
next-i18nexthandles English/Kiswahili UI language switching. Language preference is stored in the user profile and respected without page reload. - Progressive Web App — Service worker + manifest.json configured for offline access to recently visited pages and cached dictionary entries.
- Accessibility — WCAG 2.1 AA compliance minimum. Semantic HTML throughout. Audio player has full keyboard controls. Maps include text alternatives. Colour contrast ratios audited.
- State Management — Zustand for global state (user session, dialect preference, audio player state). React Query (TanStack Query) for server state, caching, and mutation management.
§ 21 · Mobile Architecture
Mobile Application — React Native (Expo)
21.1 Project Structure
React Native (Expo) — Directory Structure
kalenjin-mobile/
├── app/ # Expo Router file-based routing
│ ├── (tabs)/
│ │ ├── index.tsx # Home feed
│ │ ├── dictionary.tsx # Dictionary tab
│ │ ├── culture.tsx # Culture tab
│ │ ├── community.tsx # Community tab
│ │ ├── profile.tsx # User profile tab
│ ├── dictionary/[word].tsx # Word detail screen
│ ├── people/[id].tsx # Person profile screen
│ ├── events/[id].tsx # Event detail screen
│ ├── auth/login.tsx
│ ├── auth/register.tsx
│ └── _layout.tsx
├── components/
│ ├── AudioPlayer/ # expo-av based audio player
│ ├── AudioRecorder/ # expo-av recording component
│ ├── WordCard/
│ ├── MapView/ # react-native-maps wrapper
│ ├── DialectPicker/
│ ├── Flashcard/
├── hooks/
│ ├── useAudio.ts
│ ├── useLocation.ts
│ ├── useOfflineSync.ts
├── services/
│ ├── api.ts # Shared API client
│ ├── notifications.ts # Expo Notifications setup
│ ├── storage.ts # AsyncStorage wrappers
│ ├── offlineCache.ts # Offline dictionary caching
└── store/ # Zustand (shared with web via monorepo)
21.2 Mobile-Specific Features
- Offline Dictionary — Users can download their preferred dialect's dictionary for offline use. SQLite (via expo-sqlite) stores the local dictionary. Words accessed while offline are served from the local database; sync happens when connectivity is restored.
- Push Notifications — Expo Notifications API abstracts FCM (Android) and APNs (iOS). Notification types: Daily Word, Event Reminders, Vote Results, Contribution Approvals, New Definitions for words the user has bookmarked.
- Audio Recording — expo-av handles microphone access and audio recording. Recorded audio is uploaded when online; queued for upload when offline.
- Biometric Authentication — expo-local-authentication enables Face ID / fingerprint login for returning users.
- Share Integration — Native share sheet for sharing word entries, cultural articles, and events via WhatsApp, SMS, and other apps.
- Maps — react-native-maps renders interactive geography module maps with OpenStreetMap tiles (free tier).
- App Store / Play Store — EAS Build (Expo Application Services) for building and submitting to both stores. EAS Update for over-the-air JS bundle updates between full releases.
§ 22 · Backend Architecture
Backend — FastAPI Application
22.1 Application Structure
FastAPI — Backend Directory Structure
kalenjin-api/
├── app/
│ ├── main.py # FastAPI app init, router registration
│ ├── config.py # Settings via pydantic-settings
│ ├── database.py # Async SQLAlchemy engine + session
│ ├── dependencies.py # Shared FastAPI dependencies
│ │
│ ├── routers/
│ │ ├── auth.py # Registration, login, refresh, OAuth
│ │ ├── users.py # User profiles, settings
│ │ ├── dictionary.py # Words, concepts, dialect forms
│ │ ├── pronunciation.py # Audio upload, listing, voting
│ │ ├── culture.py # Cultural articles, ceremonies, food
│ │ ├── people.py # Notable people directory
│ │ ├── music.py # Songs, artists, playlists
│ │ ├── geography.py # Locations, diaspora data
│ │ ├── organizations.py # Org directory, helplines
│ │ ├── creators.py # Creator profiles
│ │ ├── events.py # Event calendar, RSVPs
│ │ ├── accountability.py # Recognitions, reports
│ │ ├── education.py # Scholarships, mentorship, jobs
│ │ ├── fund.py # Campaigns, donations
│ │ ├── voting.py # Universal voting endpoints
│ │ ├── search.py # Elasticsearch-backed search
│ │ ├── notifications.py # Push + email notification management
│ │ ├── moderation.py # Moderator dashboard endpoints
│ │ └── admin.py # Admin-only platform management
│ │
│ ├── models/ # SQLAlchemy ORM models
│ │ ├── user.py
│ │ ├── language.py
│ │ ├── culture.py
│ │ ├── media.py
│ │ ├── community.py
│ │ └── ...
│ │
│ ├── schemas/ # Pydantic request/response schemas
│ │ ├── user.py
│ │ ├── language.py
│ │ └── ...
│ │
│ ├── services/ # Business logic layer
│ │ ├── auth_service.py
│ │ ├── language_service.py
│ │ ├── vote_service.py
│ │ ├── search_service.py # Elasticsearch integration
│ │ ├── media_service.py # S3 upload, transcoding
│ │ ├── notification_service.py
│ │ └── reputation_service.py
│ │
│ ├── tasks/ # Celery background tasks
│ │ ├── audio_transcode.py
│ │ ├── search_index.py
│ │ ├── email_tasks.py
│ │ └── reputation_recalc.py
│ │
│ └── middleware/
│ ├── rate_limit.py
│ ├── cors.py
│ └── request_id.py
│
├── migrations/ # Alembic migrations
├── tests/ # pytest test suite
├── Dockerfile
├── docker-compose.yml
└── requirements.txt
22.2 FastAPI Application Bootstrap
Python — app/main.py (Illustrative)
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
from contextlib import asynccontextmanager
from app.routers import (
auth, users, dictionary, pronunciation, culture,
people, music, geography, organizations, creators,
events, accountability, education, fund, voting,
search, notifications, moderation, admin
)
from app.database import engine, Base
from app.middleware.rate_limit import RateLimitMiddleware
@asynccontextmanager
async def lifespan(app: FastAPI):
# Startup: create tables, init redis, warm ES indices
async with engine.begin() as conn:
await conn.run_sync(Base.metadata.create_all)
yield
# Shutdown: flush connections
app = FastAPI(
title="Kalenjin Digital Heritage API",
version="1.0.0",
docs_url="/api/docs",
redoc_url="/api/redoc",
lifespan=lifespan,
)
app.add_middleware(CORSMiddleware, allow_origins=["*"], # refined in prod
allow_credentials=True, allow_methods=["*"], allow_headers=["*"])
app.add_middleware(RateLimitMiddleware)
# Register all routers
for router in [auth, users, dictionary, pronunciation, culture, people,
music, geography, organizations, creators, events,
accountability, education, fund, voting, search,
notifications, moderation, admin]:
app.include_router(router.router, prefix="/api/v1")
§ 23 · Data Architecture
Database Design — PostgreSQL
The primary datastore is PostgreSQL 16 with PostGIS extension for geospatial data. The schema is designed around the concept of content versioning, dialect attribution, and community governance.
23.1 Core Language Schema
dialects
Reference Table
idUUID (PK)Primary key
codeVARCHAR(10)ISO code, e.g. 'niq', 'sgc'
name_enVARCHAR(100)English name, e.g. 'Nandi'
name_nativeVARCHAR(100)Self-name in the dialect
primary_regionsTEXT[]Array of primary geographic regions
approx_speakersINTEGERApproximate speaker count
is_endangeredBOOLEANUNESCO endangered status flag
created_atTIMESTAMPTZ
concepts
Core Language Entity
idUUID (PK)Unique concept identifier
semantic_domainVARCHAR(50)e.g. 'agriculture', 'body', 'family'
created_byUUID (FK → users.id)First contributor
created_atTIMESTAMPTZ
word_entries
Core Language Entity — Dialect-specific form
idUUID (PK)
concept_idUUID (FK → concepts.id)Groups dialect forms
dialect_idUUID (FK → dialects.id)Dialect this form belongs to
headwordVARCHAR(200)The word in Kalenjin romanisation
ipaVARCHAR(200)IPA phonetic transcription
tone_patternVARCHAR(50)H/L/F tone notation
part_of_speechVARCHAR(30)noun, verb, adj, adv, etc.
registerVARCHAR(30)formal, informal, archaic, sacred
def_kalenjinTEXTDefinition in the dialect
def_englishTEXTEnglish definition
def_kiswahiliTEXTKiswahili definition
etymologyTEXTRoot / origin notes
cultural_notesTEXTCultural context and usage
statusVARCHAR(20)pending | reviewed | verified | disputed | archived
vote_scoreINTEGERMaterialised vote tally (updated by trigger)
submitted_byUUID (FK → users.id)
verified_byUUID (FK → users.id)Cultural Expert who verified
created_atTIMESTAMPTZ
updated_atTIMESTAMPTZAuto-updated on edit
word_examples
Language Entity
idUUID (PK)
word_entry_idUUID (FK → word_entries.id)
sentence_kalenjinTEXTExample sentence in Kalenjin
sentence_englishTEXTEnglish translation
sentence_kiswahiliTEXTKiswahili translation
submitted_byUUID (FK → users.id)
pronunciation_recordings
Media Entity
idUUID (PK)
word_entry_idUUID (FK → word_entries.id)
audio_urlTEXTCDN URL of the AAC audio file
duration_msINTEGERDuration in milliseconds
is_primaryBOOLEANCommunity-voted primary recording
speaker_age_groupVARCHAR(20)child | youth | adult | elder
speaker_regionVARCHAR(100)Self-declared home region
vote_scoreINTEGER
submitted_byUUID (FK → users.id)
created_atTIMESTAMPTZ
votes
Governance Entity — Universal
idUUID (PK)
voter_idUUID (FK → users.id)
target_typeVARCHAR(40)word_entry | pronunciation | cultural_article | person | etc.
target_idUUIDID of the voted-on entity
valueSMALLINT+1 (upvote) or -1 (downvote)
created_atTIMESTAMPTZ
UNIQUE(voter_id, target_type, target_id)One vote per user per item
§ 24 · Media Architecture
Media & File Storage
| Media Type | Format | Max Size | Storage Path | CDN Served |
|---|---|---|---|---|
| Pronunciation audio | AAC (transcoded from any input) | 5 MB | audio/pronunciation/{word_id}/{recording_id}.aac | Yes |
| Traditional song audio | AAC / MP3 | 20 MB | audio/songs/{song_id}/preview.aac | Yes |
| User profile photo | JPEG/WebP (resized to 400×400) | 2 MB raw | images/profiles/{user_id}/avatar.webp | Yes |
| Word entry illustration | JPEG/WebP (max 1200px wide) | 5 MB raw | images/words/{word_id}/{image_id}.webp | Yes |
| Cultural article images | JPEG/WebP | 10 MB raw | images/culture/{article_id}/{image_id}.webp | Yes |
| Event cover image | JPEG/WebP (1200×630) | 5 MB raw | images/events/{event_id}/cover.webp | Yes |
| Document uploads (scholarships, fund receipts) | PDF only | 15 MB | docs/{type}/{entity_id}/{doc_id}.pdf | Authenticated URLs only |
24.1 Audio Processing Pipeline
Audio Upload Flow
Client records/selects audio
↓
POST /api/v1/pronunciations/upload (multipart)
↓
FastAPI validates MIME type, size
↓
Raw file stored to temp path in object store
↓
Celery task: audio_transcode.py
├── FFmpeg: convert to AAC 64kbps mono 22050Hz
├── Extract duration, generate waveform data (JSON)
├── Delete temp raw file
└── Write final .aac to permanent path
↓
Database record created with audio_url, duration_ms, waveform_data
↓
Elasticsearch index updated (word now has audio flag)
↓
Push notification to word's subscribers (new pronunciation available)
§ 25 · Search Architecture
Search System — Elasticsearch
Search is among the most critical user experiences on the platform. The Elasticsearch cluster maintains dedicated indices for each major content type, with custom analysers built for Kalenjin language characteristics including tone marks and variant spellings.
25.1 Search Indices
- kalenjin_words — All word entries with headword, definitions (en, sw, kalenjin), dialect, semantic domain, part of speech. Custom analyser strips tone marks for fallback search.
- kalenjin_culture — Cultural articles, ceremonies, food, proverbs. Full-text on titles and body text.
- kalenjin_people — Notable people profiles. Searchable by name, field, region, achievement keywords.
- kalenjin_music — Songs and artists. Searchable by title, artist name, lyrics excerpt, genre, dialect.
- kalenjin_events — Events. Searchable by title, location, organiser, event type. Date-ranged filtering.
- kalenjin_organizations — Organisation directory. Searchable by name, type, region, services.
25.2 Search Features
- Cross-language search — A single search bar searches across all languages simultaneously. Query "milk" returns mursik and all related entries.
- Fuzzy matching — Handles common misspellings with configurable edit distance (typically fuzziness: auto)
- Dialect faceting — Results can be filtered by one or more dialects
- Phonetic search — Soundex/phonetic token filter for Kalenjin words that sound similar despite different spellings
- Search suggestions / autocomplete — prefix query returns suggestions as the user types
- Search analytics — All searches logged (without PII) to understand common search patterns, missing entries, and popular content
§ 26 · Security Architecture
Authentication & Authorisation
26.1 Authentication Flows
| Method | Implementation | Notes |
|---|---|---|
| Email + Password | bcrypt hashed passwords; JWT access (15 min) + refresh (30 day) tokens | Primary auth method |
| Google OAuth | OAuth 2.0 via Google; token exchanged for internal JWT | Convenient for diaspora users |
| Phone (M-Pesa number) | OTP via Africa's Talking SMS | Critical for Kenya access |
| Apple Sign-In | Required for iOS App Store compliance | Mobile only |
| Biometric | expo-local-authentication (wraps device auth) | Mobile only, re-uses existing session |
26.2 Authorisation Model (RBAC)
Python — Role-based permission dependency example
from enum import Enum
from fastapi import Depends, HTTPException
class Role(str, Enum):
MEMBER = "member"
CONTRIBUTOR = "contributor"
TRUSTED = "trusted_contributor"
EXPERT = "cultural_expert"
MODERATOR = "moderator"
ADMIN = "admin"
def require_role(*roles: Role):
async def checker(current_user = Depends(get_current_user)):
if current_user.role not in roles:
raise HTTPException(status_code=403,
detail="Insufficient permissions")
return current_user
return checker
# Usage in router:
@router.post("/words/{id}/verify")
async def verify_word(
id: UUID,
user = Depends(require_role(Role.EXPERT, Role.MODERATOR, Role.ADMIN))
):
...
§ 27 · Real-time Architecture
Real-time Features & Push Notifications
27.1 WebSocket Channels (FastAPI WebSockets)
- Moderation Dashboard — Live feed of new submissions requiring review
- Vote Counters — Live vote count updates on word and cultural entry pages
- Community Forum — Real-time comment threads using WebSocket + Redis pub/sub
- Event Live Updates — RSVP count and announcements for active events
27.2 Push Notification Types
| Trigger | Recipient | Channel |
|---|---|---|
| Daily Word of the Day | All subscribed users | Push (mobile) + optional email |
| Contribution approved | Submitter | Push + in-app |
| Contribution disputed | Submitter | Push + email |
| Bookmarked word updated | Users who bookmarked the word | Push + in-app |
| Event reminder (48h and 1h) | RSVPed users | Push + email |
| New event in user's region | Users with location set to that region | Push |
| New accountability report (public) | All moderators | Push + email |
| Mentorship request received | Mentor | Push + email |
| Scholarship deadline in 7 days | Users who set deadline alerts | Push + email |
| Fund campaign goal reached | Campaign donors | Push + email |
✦ ✦ ✦
Part IV
Data Models
Complete database schema for all major entities. Every table includes audit fields (created_at, updated_at, created_by) unless noted as a pure reference table.
§ 28 · Data Models
User & Auth Models
users
Core Entity
idUUID (PK)gen_random_uuid()
emailVARCHAR(254) UNIQUENullable (phone-only accounts)
phoneVARCHAR(20) UNIQUENullable (E.164 format)
usernameVARCHAR(50) UNIQUESlugified display name
display_nameVARCHAR(100)Shown publicly
password_hashVARCHAR(100)bcrypt hash; null for OAuth-only
rolerole_enummember | contributor | trusted | expert | moderator | admin
primary_dialect_idUUID (FK → dialects.id)User's home dialect
dialect_idsUUID[]All dialects the user speaks
home_regionVARCHAR(100)Self-declared home region
current_countryVARCHAR(2)ISO 3166-1 alpha-2
current_cityVARCHAR(100)For diaspora mapping (optional)
reputation_scoreINTEGER DEFAULT 0Materialised; updated by trigger
avatar_urlTEXTCDN URL
bioTEXTUp to 500 chars
is_verifiedBOOLEAN DEFAULT falseEmail/phone verified
is_activeBOOLEAN DEFAULT trueFalse = banned/suspended
push_tokenTEXTFCM/APNs device token (latest)
notification_prefsJSONB{daily_word: true, events: true, ...}
ui_languageVARCHAR(5) DEFAULT 'en'en | sw
created_atTIMESTAMPTZ
last_login_atTIMESTAMPTZ
oauth_accounts
Auth Entity
idUUID (PK)
user_idUUID (FK → users.id)ON DELETE CASCADE
providerVARCHAR(20)google | apple
provider_user_idVARCHAR(200)Provider's user identifier
UNIQUE(provider, provider_user_id)
§ 29 · Data Models
Language Models (Extended)
word_revisions
Audit / Versioning Entity
idUUID (PK)
word_entry_idUUID (FK → word_entries.id)
revision_numberINTEGER1, 2, 3…
snapshotJSONBFull snapshot of word_entry at this revision
change_summaryTEXTHuman-written note about the edit
edited_byUUID (FK → users.id)
created_atTIMESTAMPTZ
proverbs
Language / Culture Entity
idUUID (PK)
dialect_idUUID (FK → dialects.id)
text_kalenjinTEXT NOT NULLProverb in original dialect
literal_enTEXTWord-for-word English translation
meaning_enTEXTFigurative meaning in English
meaning_swTEXTFigurative meaning in Kiswahili
usage_contextTEXTWhen this proverb is used
audio_urlTEXTOptional audio recitation
statusVARCHAR(20)pending | reviewed | verified | disputed
submitted_byUUID (FK → users.id)
created_atTIMESTAMPTZ
§ 30 · Data Models
Culture & Media Models
cultural_articles
Content Entity
idUUID (PK)
categoryVARCHAR(50)ceremony | clothing | food | belief | history | agriculture | medicine | governance
dialect_idsUUID[]Dialects this article applies to
title_enVARCHAR(300)
title_kalenjinVARCHAR(300)Optional Kalenjin title
body_enTEXTMarkdown body in English
body_swTEXTMarkdown body in Kiswahili
cover_image_urlTEXTCDN URL
media_urlsTEXT[]Additional image gallery URLs
statusVARCHAR(20)draft | pending | published | archived
vote_scoreINTEGER
submitted_byUUID (FK → users.id)
created_atTIMESTAMPTZ
updated_atTIMESTAMPTZ
songs
Music Entity
idUUID (PK)
title_kalenjinVARCHAR(300)
title_enVARCHAR(300)Optional English title
song_typeVARCHAR(30)traditional | contemporary | gospel | hiphop | benga | folk | ceremony
ceremony_contextVARCHAR(50)initiation | wedding | harvest | mourning | null
dialect_idUUID (FK → dialects.id)Primary dialect of performance
lyrics_kalenjinTEXTFull lyrics
lyrics_enTEXTEnglish translation
preview_audio_urlTEXT30-second CDN preview
streaming_linksJSONB{spotify: url, youtube: url, boomplay: url, ...}
yearSMALLINT
statusVARCHAR(20)pending | published | archived
notable_people
People Entity
idUUID (PK)
full_nameVARCHAR(200)
kalenjin_nameVARCHAR(200)Traditional name if different
fieldsTEXT[]Array of achievement fields
dialect_idUUID (FK → dialects.id)
home_regionVARCHAR(150)
birth_yearSMALLINT
death_yearSMALLINTNull if living
biography_enTEXT
biography_swTEXT
achievementsJSONB[{year, description, source_url}]
photo_urlTEXTCDN URL
source_urlsTEXT[]Verifiable external sources
consent_obtainedBOOLEANFor living persons
social_linksJSONB{twitter, instagram, linkedin, website}
statusVARCHAR(20)pending | published | disputed | archived
vote_scoreINTEGER
§ 31 · Data Models
Community Models
events
Community Entity
idUUID (PK)
titleVARCHAR(300)
event_typeVARCHAR(40)cultural | sports | concert | meeting | conference | fundraiser | religious | educational | diaspora
descriptionTEXT
organiser_user_idUUID (FK → users.id)Nullable if org-organised
organiser_org_idUUID (FK → organizations.id)Nullable if user-organised
starts_atTIMESTAMPTZ
ends_atTIMESTAMPTZ
timezoneVARCHAR(50)IANA timezone string
location_pointGEOGRAPHY(Point, 4326)PostGIS point for physical location
location_addressTEXTHuman-readable address
is_virtualBOOLEAN
virtual_linkTEXTZoom/YouTube/Meet URL
admissionVARCHAR(20)free | ticketed | invite_only
ticket_linkTEXTExternal ticketing URL
rsvp_countINTEGER DEFAULT 0Materialised
statusVARCHAR(20)draft | published | cancelled | completed
fund_campaigns
Finance Entity
idUUID (PK)
titleVARCHAR(300)
categoryVARCHAR(40)education | medical | infrastructure | cultural | disaster | business
descriptionTEXT
target_amountNUMERIC(14,2)In KES or USD
currencyVARCHAR(3)KES | USD | GBP | EUR
amount_raisedNUMERIC(14,2)Materialised; updated by webhook
payment_channelsJSONB{mpesa: phone, stripe: link, paypal: link}
deadlineDATE
organiser_idUUID (FK → users.id)Verified identity required
statusVARCHAR(20)pending_review | active | completed | suspended
completion_reportTEXTRequired at campaign close
✦ ✦ ✦
Part V
API Specification
All API endpoints follow REST conventions, use JSON, and are prefixed with /api/v1. Authentication is via Bearer JWT token in the Authorization header. Rate limiting is applied per-endpoint and per-user. Full OpenAPI 3.x documentation is auto-generated by FastAPI and available at /api/docs.
§ 32 · API
Authentication APIs
POST
/auth/register
Create a new user account
Body: { email?, phone?, username, display_name, password?, primary_dialect_id }
Returns: { user, access_token, refresh_token }
Rate limit: 5 requests / IP / hour
POST
/auth/login
Login with email/phone + password
Body: { identifier, password } — identifier is email or phone
Returns: { access_token, refresh_token, user }
POST
/auth/refresh
Exchange refresh token for new access token
POST
/auth/otp/request
Request OTP via SMS to phone number
POST
/auth/otp/verify
Verify OTP and receive tokens
POST
/auth/oauth/{provider}
Exchange OAuth code from Google/Apple for internal JWT
§ 33 · API
Language & Dictionary APIs
GET
/dictionary/words
List / browse word entries
Query params: q (search), dialect_id, part_of_speech, semantic_domain, status, page, page_size
Returns: Paginated list of word entries with dialect info
Auth: Public (no auth required)
GET
/dictionary/words/{id}
Get full word entry with examples, recordings, votes, revisions
POST
/dictionary/words
Submit a new word entry
Auth: Contributor+ role required
Body: Full word entry schema (dialect_id, headword, definitions, ipa, etc.)
Side effect: Creates reputation event, triggers search indexing task
PUT
/dictionary/words/{id}
Edit a word entry (creates new revision)
Auth: Trusted Contributor+ or original submitter
Side effect: Creates word_revision record; re-queues for review
GET
/dictionary/words/{id}/dialect-comparisons
Get all dialect forms of the same concept
POST
/dictionary/pronunciations
Upload a pronunciation recording (multipart/form-data)
Auth: Member+ (any verified user)
Body: word_entry_id, audio_file, speaker_age_group, speaker_region
Side effect: Queues audio transcoding Celery task
GET
/dictionary/words/daily
Get the current Word of the Day
GET
/dictionary/flashcards
Get a batch of flashcard items for spaced repetition
Query: dialect_id, semantic_domain, count (default 20)
GET
/dictionary/proverbs
List proverbs with dialect and status filtering
POST
/dictionary/proverbs
Submit a new proverb
§ 34 · API
Culture APIs
GET
/culture/articles
List cultural articles
Query: category, dialect_id, status, q, page
GET
/culture/articles/{id}
Get full cultural article
POST
/culture/articles
Submit new cultural article
GET
/people
List notable people
Query: field, dialect_id, living_only, q, page
POST
/people
Submit a new person profile
GET
/music/songs
List songs
GET
/music/artists
List artists
GET
/geography/diaspora
Get diaspora distribution data
Returns: Country and city-level aggregates from community-contributed location data
POST
/geography/diaspora/register
Register or update the authenticated user's diaspora location
§ 35 · API
Community & Social APIs
POST
/votes
Cast a vote on any votable entity
Body: { target_type, target_id, value } — value is +1 or -1
Side effect: Updates materialised vote_score; triggers reputation update for submitter; checks for status threshold promotions
GET
/events
List events with filters
Query: event_type, dialect_id, country, from_date, to_date, is_virtual
POST
/events/{id}/rsvp
RSVP to an event
GET
/organizations
List organisations
GET
/helplines
List helplines
Query: category, country
This endpoint is public and has a higher rate limit to ensure it is always accessible.
POST
/accountability/recognitions
Submit a community recognition nomination
POST
/accountability/reports
Submit a confidential accountability report
Auth: Verified account required. reporter_id stored but not shown publicly.
GET
/education/scholarships
List scholarships and bursaries
GET
/fund/campaigns
List active fundraising campaigns
POST
/fund/campaigns
Create a new fundraising campaign (pending moderator approval)
§ 36 · API
Media & Content APIs
POST
/media/upload-url
Get a pre-signed S3 upload URL for client-side direct upload
Body: { media_type, content_type, entity_type, entity_id }
Returns: { upload_url, final_cdn_url }
Large files (images, documents) are uploaded directly from client to S3 via pre-signed URL to reduce API server bandwidth.
POST
/media/confirm-upload
Confirm a completed direct upload and trigger processing
§ 37 · API
Admin & Moderation APIs
GET
/moderation/queue
Get content items pending moderation review
Auth: Moderator / Admin only
Query: content_type, priority, assigned_to
POST
/moderation/review/{item_id}
Submit a moderation decision (approve / reject / escalate)
GET
/admin/users
Search and manage user accounts
Auth: Admin only
POST
/admin/users/{id}/ban
Suspend or permanently ban a user
GET
/admin/stats
Platform-wide usage and content statistics
✦ ✦ ✦
Part VI
Infrastructure & Operations
§ 38 · Infrastructure
Deployment Architecture
38.1 Environment Strategy
| Environment | Purpose | Infrastructure | Database |
|---|---|---|---|
| Development | Local developer machines | Docker Compose (all services local) | Local PostgreSQL container |
| Staging | Pre-production QA and testing | Kubernetes (small cluster, 1 replica each) | Managed PostgreSQL (small tier) |
| Production | Live user traffic | Kubernetes (auto-scaling) | Managed PostgreSQL (high-availability, 2+ replicas) |
38.2 Cloud Provider Recommendation
Given the primary audience in Kenya and East Africa, the recommended cloud provider for the initial production deployment is Google Cloud Platform with a primary region of africa-south1 (Johannesburg) for lowest latency to East Africa, with a secondary region in Europe (europe-west4) for diaspora users. Cloudflare is used in front of all origins for CDN, DDoS protection, and DNS.
Cost Optimisation Note
As a community nonprofit initiative, eligibility for Google for Nonprofits ($10,000/year GCP credits) and Cloudflare for Nonprofit (free Pro tier) should be pursued immediately after legal entity formation. AWS also offers nonprofit credits via AWS Activate. These programmes can substantially reduce operating costs during the growth phase.
38.3 Kubernetes Service Layout
Kubernetes — Services and Deployments (Production)
Namespace: kalenjin-prod
│
├── Deployments
│ ├── api (FastAPI app — 2-8 replicas, HPA)
│ ├── celery-worker (Background task workers — 2-4 replicas)
│ ├── celery-beat (Scheduled task scheduler — 1 replica)
│ └── next-web (Next.js web app — 2-4 replicas, HPA)
│
├── Services
│ ├── api-service (ClusterIP, exposed via Ingress)
│ └── next-service (ClusterIP, exposed via Ingress)
│
├── Ingress
│ └── nginx-ingress (routes *.kalenjin.com/api/* → api-service)
│ (routes *.kalenjin.com/* → next-service)
│
├── External Services (Managed)
│ ├── Cloud SQL (PostgreSQL) — GCP Cloud SQL for PostgreSQL 16
│ ├── Memorystore (Redis) — GCP Memorystore for Redis 7
│ ├── Elasticsearch — Elastic Cloud (or GKE-deployed)
│ ├── Cloud Storage — GCP GCS (or Cloudflare R2)
│ └── Cloud Pub/Sub — RabbitMQ on GKE or Cloud Pub/Sub
│
└── Secrets (GCP Secret Manager → K8s ExternalSecrets)
├── DATABASE_URL
├── REDIS_URL
├── ELASTICSEARCH_URL
├── JWT_SECRET
├── S3_ACCESS_KEY / S3_SECRET_KEY
├── FCM_SERVER_KEY
├── AFRICAS_TALKING_API_KEY
└── STRIPE_SECRET_KEY
38.4 CI/CD Pipeline
GitHub Actions — CI/CD Workflow Overview
On push to feature branch:
├── Lint (ruff, eslint)
├── Type check (mypy, tsc)
├── Unit tests (pytest, jest)
└── Integration tests (pytest against test DB)
On merge to `develop`:
├── All above
├── Build Docker image (tagged with SHA)
├── Push to Artifact Registry
├── Deploy to STAGING (kubectl rollout)
├── Run E2E tests (Playwright against staging)
└── Notify team on success/failure
On merge to `main` (production release):
├── All above (against prod-spec)
├── Build + tag Docker image (semantic version)
├── Deploy to PRODUCTION (blue-green with automatic rollback)
├── Run smoke tests
├── Tag git release
└── Update changelog
§ 39 · Security
Security Specification
Authentication Security
- JWT access tokens expire in 15 minutes
- Refresh tokens stored in httpOnly cookies (web) or AsyncStorage (mobile)
- Token rotation on every refresh
- Refresh token reuse detection (invalidates family)
- Account lockout after 5 failed login attempts (15-minute lockout)
- Email verification required before contribution privileges
API Security
- HTTPS enforced at all tiers (no HTTP)
- CORS restricted to known origins in production
- Rate limiting: 100 req/min (public), 500 req/min (authenticated)
- Input validation via Pydantic on all request bodies
- SQL injection protected by ORM (no raw SQL)
- File uploads restricted by MIME type and magic bytes
- Pre-signed URLs expire after 15 minutes
Data Privacy
- User passwords are never stored in plaintext. bcrypt with cost factor ≥12.
- PII (email, phone) is encrypted at rest using column-level encryption (pgcrypto)
- GDPR and Kenya Data Protection Act 2019 compliance required. Users have the right to export and delete their data.
- Children's privacy: the platform does not knowingly collect data from users under 13. Age verification on registration.
- Diaspora location data is stored at city-level precision only and cannot be linked to individual users in public views
- Accountability report submissions are anonymised in all public views
§ 40 · Performance
Performance & Scalability
Caching Strategy
| Resource | Cache Location | TTL | Invalidation |
|---|---|---|---|
| Word entry detail | Redis + CDN | 1 hour | On edit or vote threshold crossing |
| Word of the Day | Redis | Until midnight EAT | Daily cron job |
| Dialect list | Redis + in-memory | 24 hours | Manual admin flush |
| Organisation listing | Redis | 30 minutes | On new org creation/update |
| Event calendar | Redis | 15 minutes | On event creation/update |
| User reputation score | Redis | 5 minutes | On vote/contribution action |
| Search results | Redis (SHA of query) | 10 minutes | On related content update |
| Static pages (Next.js SSG) | CDN edge | Stale-while-revalidate 24h | On content status change |
Performance Targets
<200ms
API P95 response time
<3s
Mobile app cold start
99.5%
Uptime SLA target
Offline-First Mobile Architecture
Given that many Kalenjin users in Kenya operate in areas with intermittent connectivity, the mobile app is designed for resilience. The locally cached dictionary (SQLite), bookmarked content, and recently viewed pages are accessible without any network connection. Contributions made offline (e.g., pronunciation recordings, word submissions) are queued in a local database and uploaded automatically when connectivity is restored using Expo's background task API.
§ 41 · Observability
Monitoring & Observability
| Concern | Tool | Key Metrics |
|---|---|---|
| Application Performance | Sentry (errors + performance) | Error rate, P95 latency, transaction traces |
| Infrastructure Metrics | Prometheus + Grafana | CPU/memory, pod restarts, DB connections |
| Log Aggregation | GCP Cloud Logging (or Loki) | Structured JSON logs, request IDs for distributed tracing |
| Uptime Monitoring | UptimeRobot / Betterstack | Endpoint availability, alerting to Slack and email |
| Database | pgBadger + slow query log | Slow queries, connection pool saturation |
| Mobile Crash Reporting | Sentry Mobile SDK | Crash-free rate, ANRs, JS errors |
| Analytics | PostHog (self-hosted, privacy-first) | Feature usage, search terms, DAU/MAU |
✦ ✦ ✦
Part VII
Governance, Moderation & Roadmap
§ 42 · Governance
Community Governance Model
The platform is governed by a layered model: day-to-day content moderation is handled by community-elected Moderators; strategic platform decisions are made by an elected Advisory Council; technical infrastructure is maintained by the founding technical team. No single person or group controls the platform's direction.
42.1 Advisory Council
- Composition: 9 members — one representative per major dialect group, elected by community members of that dialect
- Term: 2 years, staggered so 4-5 seats are up for election each year
- Responsibilities: Approve major policy changes, oversee moderator elections, resolve moderator appeals, define cultural sensitivity policies, approve partnership agreements
- Platform Mechanism: Advisory Council votes are conducted on-platform using the governance voting system, with public vote tallies
42.2 Moderator Elections
- Moderators are elected annually by the community (not appointed by administration)
- Eligibility to stand: Trusted Contributor tier or above, minimum 6 months platform membership, no active sanctions
- Eligibility to vote: Any verified member with at least 30 days membership
- Platform implements a built-in election system: nomination period (14 days), Q&A period (7 days), voting period (7 days)
- Election results are published transparently with full vote tallies
- Moderators can be recalled by community petition (≥500 signatures triggers a recall vote)
§ 43 · Moderation
Content Moderation Framework
43.1 Moderation Queue Priority
| Content Type | Priority | Target Review Time |
|---|---|---|
| Accountability reports (safety-related) | Critical | 4 hours |
| GBV / child safety related reports | Critical | 2 hours |
| Flagged user-generated comments | High | 24 hours |
| New fund campaign submissions | Medium | 48 hours |
| Person profile submissions | Medium | 48 hours |
| Word entry submissions | Standard | 7 days |
| Cultural article submissions | Standard | 7 days |
43.2 Prohibited Content
- Content that incites ethnic hatred or promotes violence against any group
- Sexual content involving minors under any circumstances
- Demonstrably false information submitted with intent to deceive
- Content that violates the privacy of private individuals without their consent
- Spam, commercial advertising not approved by administrators
- Content that impersonates individuals or organisations
- Content that violates Kenyan law or applicable diaspora country laws
§ 44 · Roadmap
Development Roadmap
Phase 1 — Foundation (Months 1–6)
Phase 1 Deliverables
- FastAPI backend with core language, auth, and user APIs
- PostgreSQL schema v1 deployed with Alembic migrations
- Dictionary module (words, dialects, examples, voting)
- Audio pronunciation upload and playback
- Next.js web app: home, dictionary browse, word detail, search
- React Native app (Expo): same core dictionary features, offline mode
- User registration, login, profile, and contribution system
- Basic moderation dashboard
- Seed database with initial Nandi and Kipsigis word entries
Phase 2 — Expansion & Community (Months 4–7)
- Full Kalenjin Dialects: All 8+ dialects with 3,000–5,000 core words each
- Culture & Traditions module: Rites, ceremonies, clothing galleries
- Notable People database: Athletes, politicians, academics, artists
- Music & Entertainment: Song library, artists, mixtapes
- Community voting with transparent scoring
- Discussion forums, Helpline registry, Events calendar
- Enhanced moderation dashboard with workflows
Phase 3 — Advanced Features (Months 8–11)
- Contributor reputation and leveling system
- Advanced search with dialect and source filters
- Innovations, Organizations, Geography modules
- Content Creator profiles with monetization
- Fund & Contributions with transparent tracking
- Email & push notifications with Elasticsearch search
Phase 4 — Sustainability & Scaling (Months 12+)
- ML-powered pronunciation and content recommendations
- Offline-first mobile sync, community monetization
- Academic partnerships, UNESCO grants
- Accessibility improvements, annual conferences
- Diaspora communities, educational integrations
§ 45 · Success Metrics & KPIs
Success Metrics & Key Performance Indicators
User & Engagement Metrics
- User Growth: 50K users by Year 1, 500K by Year 3 | MAU, signups, retention rates
- Contributions: 10K by Month 6, 100K+ by Year 2 | Words, definitions, translations, audio, media
- Content Quality: 90%+ community-approved, 4.5+/5 rating | Vote scores, expert verification
- Usage Depth: 8+ minutes/session, 3+ sessions/week | Session duration, feature diversity
Content Completeness Targets
| Module | Year 1 | Year 2 | Measurement |
|---|---|---|---|
| Language & Dictionary | 15,000 words | 50,000+ with multimedia | Count by dialect, audio coverage |
| Culture & Traditions | 200+ entries | 500+ with documentation | Entry count, gallery size, feedback |
| Notable People | 1,000 profiles | 3,000+ comprehensive | Count by category, completeness, views |
| Music & Entertainment | 500 songs, 50 artists | 2,000+ songs, 200+ artists | Catalog size, playback count |
| Geography | Distribution maps | Interactive regional maps | Accuracy, data sources, updates |
| Organizations & Communities | 200 listed | 500+ with verification | Directory size, verification rate |
Technical Performance Benchmarks
- Page Load Time: <3s on 4G, <1.5s on broadband | Web Core Vitals: LCP <2.5s, FID <100ms, CLS <0.1
- API Response Time: <200ms for 95th percentile | 99.9% uptime SLA
- Search Performance: Full-text results <500ms across 100K+ documents
- Mobile Performance: React Native launch <2s, offline functionality >90%
- Database Scalability: Support 1M+ concurrent reads, sub-100ms query latency
Community Health & Sustainability
- Moderation Efficiency: 90%+ flagged content reviewed <48h, 95% fair appeals
- Community Satisfaction: NPS >50, user satisfaction >4.2/5 stars
- Contributor Retention: 60%+ return for second submission, 30%+ become repeat contributors
- Fundraising: $500K Year 1, $2M+ Year 3 | 2–3% donation conversion rate
- Premium Adoption: 5–10% of users adopt premium features | UNESCO/Ford Foundation grants
· · ·
Conclusion & Call to Action
The Kalenjin Digital Heritage Platform represents an unprecedented opportunity to preserve, celebrate, and amplify the language, culture, history, and achievements of 6.4+ million Kalenjin people worldwide. By combining technical sophistication with community-driven governance and transparent accountability, KDHP will become the definitive digital home of the Kalenjin people for generations to come.
This exhaustive system design document provides the architectural, technical, organizational, and governance blueprint necessary to execute this vision with excellence, scalability, cultural authenticity, and deep respect for Kalenjin heritage and traditions. Every feature, every data model, every user interaction, and every governance mechanism has been designed with the understanding that language is the carrier of culture, culture is the expression of identity, and identity is everything.
This is not merely a digital project — it is an act of cultural preservation, a statement of Kalenjin pride, and a gift to all Kalenjin people everywhere, whether in the Rift Valley, the major cities of Kenya, or the diaspora across the globe. We invite every Kalenjin person, every developer, every designer, every cultural expert, every community advocate, and every friend of the Kalenjin to join us in building this monument to cultural continuity, digital justice, and collective memory.
The digital future of the Kalenjin people is now. The tools are ready. The community is waiting. Let us build it together, with excellence, with integrity, and with love for our people.
Kalenjin Digital Heritage Initiative
System Design Document v1.0.0 — Draft Edition
May 2026
This document represents the collective vision of Kalenjin technologists, cultural experts, community leaders, and digital natives across the diaspora.