docs: Mukoko Platform Architecture v5.0

[Bryan Fawcett (bryanfawcett)]

What

Adds docs/architecture/MUKOKO_ARCHITECTURE_v5.0.md and links it from the README's documentation table.

v5.0 records the 2026-10-02 decisions:

• Two non-negotiables: open data and open weights (replacing "No MongoDB (SSPL)" / "open source everywhere"), and Ubuntu in code (Musha/Basa/Nhaka for every mini-app, Ubuntu contributions, community governance).
• Two APIs: the Nyuchi API (api.nyuchi.com, nyuchi/api-gateway, FastAPI on Fly jnb) is internal and the only thing that touches a database; first-party apps each call it with their own client id/secret. api.mukoko.com (mukoko-dev/mukoko-api, Workers, no database access) is the public consumer API for developers, partners and AI agents, organised by namespace (/v1/weather, /v1/news, …).
• Data: MongoDB Atlas as the content system of record; the Supabase relational spine (nyuchi_relational_db) re-adopted; payments on Supabase; Doris on Fly's private network; Redpanda/Flink suspended; ScyllaDB/Cassandra/JanusGraph/Maestro superseded.
• Auth: WorkOS AuthKit; Nyuchi Identity as the designed single boundary.
• Apps: thin clients; super-app-web/mobile replace the mukoko-app plan.
• Every section is marked Live / Designed / Superseded / Deferred, checked against the repos, gh repo list and fly apps list on 2026-10-02.

Notes for review

• No v4.0.2 document exists in any local clone, in either org on GitHub, or in Drive, so the structure follows v4.0.1 (nyuchi/mukoko-platform/docs/foundation/MUKOKO_ARCHITECTURE_v4.0.1.md). The v4.0.3 identity amendment referenced by nyuchi-identity is also missing.
• mukoko-dev/mukoko-api's README says Mukoko apps call api.mukoko.com; this doc follows the owner's correction that first-party apps call the Nyuchi API directly. That README needs the same change.
• Items marked (unverified) in the doc need confirming: the payments Supabase project reference, the event-bus transport, and the state of mukoko-weather-mobile.
• Formatting passes prettier (the org config from ci: adopt the canonical org lint gate #94 and this repo's config) and markdownlint-cli2 with the org config.

🤖 Generated with Claude Code

https://claude.ai/code/session_01GHjaH1Vt2dVLWU68iz8tFq

[Bryan Fawcett (bryanfawcett)]

Closing as superseded. The owner's own Nyuchi Architecture v5.0.0 is now the canonical technical architecture for the whole estate, Mukoko included. It is committed byte-for-byte at nyuchi/.github → profile/canonical/NYUCHI_ARCHITECTURE.md (nyuchi/.github#66), alongside the Mukoko Manifesto and the Bundu Order. A separate agent-written "Mukoko Platform Architecture v5.0" in this repo would just compete with it.

This draft does have detail the owner may want to fold into the next version of the Architecture. These parts are worth carrying over (the branch is kept so the text stays available):

1. The two-API rule. The Nyuchi API (api.nyuchi.com/v1, nyuchi/api-gateway) is internal and the only thing that touches a database. Each first-party app calls it directly with its own client credentials: nyk_… / nys_… pairs issued at POST /v1/api-keys, owned by a workspace and scoped per namespace. api.mukoko.com (mukoko-api, Workers, no database access) is the public consumer API, namespaced as api.mukoko.com/v1/<app>, e.g. /v1/weather rather than weather.mukoko.com/api. The draft also has a migration table from today's per-app /api paths (§ "Two APIs").
2. The Fly app inventory as of 2 October 2026 (fly apps list): mukoko-platform-api (serves the Nyuchi API today), nyuchi-api (created, never deployed, waiting on api-gateway docs: load the Mzizi dev skills; progress reports and the merge gate #123), mukoko-doris (private network only), mukoko-couchdb, mukoko-news-api, nyuchi-identity (scaffold), and mukoko-redpanda / mukoko-flink (suspended).
3. The relational spine conventions for nyuchi_relational_db: one Postgres schema per MongoDB database; table = collection and column = document field, both snake_cased; ids are the MongoDB _id values unchanged; a *Id field becomes a foreign key and a *Ids array becomes a link table, never an array column; MongoDB $jsonSchema validators are the spec (enum → CHECK, required → NOT NULL); OIDC standard claims for persons and Schema.org for organisations.
4. The open-data / open-weights covenant, written out: anonymised aggregate data flows into the open data commons (Doris, Layer 7) and becomes publicly queryable; any model trained on community data is released with open weights; and managed or source-available infrastructure is acceptable where no open alternative is adequate yet.

Items the draft itself marked (unverified) — the payments Supabase project reference, the event-bus transport, and the state of mukoko-weather-mobile — should be checked before any of this goes into the canonical text. The note that mukoko-api's README still says first-party apps call api.mukoko.com also still stands.