The
apps/oshun/area: the nine deployable V1 application surfaces of the Oshun platform — one backend-for-frontend, plus the web, admin, tenant, mobile, and Telegram clients that consume it.
What this area is#
Where libs/contracts/ owns the wire types and libs/* own the domain engines,
apps/oshun/ is where Oshun is actually served. These are the leaf nodes of
the dependency graph — the runnable processes and bundles a person or operator
opens. Each is a standalone Nx projectType: "application" tagged
scope:oshun, type:app, and a platform:* tag (node, web, admin-web,
tenant-web, mobile). None of them implements domain logic of its own; they
compose the domain libraries and the BFF into a shippable experience.
The area has one hub and eight spokes. The hub is @oshun/bff — a large Fastify
backend-for-frontend (1,000+ source files, 488 route modules) that aggregates
every domain (Nisaba, Nyx, Veritas, Arete, Tara, Metis, Lilith, Isis, Aja,
Psyche, Sophia, Iris, and the admin/operator surfaces) behind one HTTP edge. The
spokes are the clients that call it: @oshun/web (the consumer website / PWA),
@oshun/admin (operator cockpit) and @oshun/tenant-admin (tenant console) as
Next.js apps, @oshun/mobile and @oshun/admin-mobile as Expo/React-Native
shells, and @oshun/telegram-bot + @oshun/telegram-miniapp for the Telegram
channel. @oshun/content-service-app is a ninth, smaller deployable: a thin
process entrypoint that boots the agentic content service.
The split is deliberate. The BFF is the only app that talks to the domain libraries directly; every other surface talks to the BFF over HTTP and stays free of domain runtime. That keeps the clients thin and lets the platform expose one canonical, validated API instead of N drifting ones.
Surface model#
The web and mobile clients render the consumer shell (Home, Explore, Activity,
Library, Profile, plus per-domain surfaces like Nisaba reading, Nyx sky, Tara
ritual). The admin apps render the operator cockpit (review queues, incidents,
policy, moderation, research integrity), and @oshun/tenant-admin renders the
tenant cockpit (members, integrations, policy attestation, tenant-scoped
audit). The README for @oshun/admin-mobile states the boundary rule plainly:
"Admin routes render dedicated operator wayfinding and never inherit customer
shell chrome."
How it fits the wider system#
The dependency arrow points one way: clients depend on the BFF, the BFF depends
on the domain libraries and contracts. @oshun/web, @oshun/admin, and
@oshun/tenant-admin reach the BFF over HTTP (e.g. tenant-admin's
src/lib/tenant-bff.ts forwards the tenant session cookie as a bearer token to
OSHUN_BFF_URL, defaulting to http://localhost:4010); the mobile shells do
the same through their runtime config. The Telegram bot composes
@oshun/messaging-channels rather than the BFF directly. Shared shell
vocabulary (workspace models, shell-mode gating like canEnterAdminShell) comes
from @oshun/navigation, so all surfaces agree on information architecture.
The boundary these apps enforce is "validated edge, thin client": the BFF parses
and validates every payload against the contract schemas and degrades per-domain
honestly (its /readyz returns a "normalized per-domain degradation summary"),
while the clients render whatever the BFF returns — including honest "backend
unreachable" states rather than fabricated data. Walk the "used by" / "depends
on" edges on any node below to see exactly which domains and contracts each app
composes.
Entity catalog (12)#
The 12 tracked Nx projects in oshun, each a code-linked entity node — package, type, source path, declared targets, and its internal dependency graph (depends-on / used-by, resolved from the package manifests, §6/§8), read from the project graph. Grouped by architectural layer; walk the dependency links to travel the system. 11 of these carry an authored deep-dive (what / why / how it fits); the rest are generated scaffolds awaiting one.
api (3)#
OSHUN backend-for-frontend service
The platform backend-for-frontend (apps/oshun/bff), a Fastify TypeScript
service and by far the largest node in this area (~1,062 non-test source files;
src/app.ts alone wires 464 register*Routes modules). createApp in
src/app.ts assembles the whole surface: request tracing, tenant + residency
middleware, idempotency, then the consumer feeds (/home, /continue,
/library, /search, /activity, /notifications, /profile), the
per-domain routes (Nisaba, Nyx, Veritas, Arete, Tara, Metis, Lilith, Isis, Aja,
Psyche, Sophia, Iris, Themis, safety), and a vast admin/operator surface
(admin-isis-*, admin-aja-*, admin-yemaya-*, admin-bellona-*,
admin-hathor-*, admin-studio-*). Its package.json depends on dozens of
@oshun/*, @aja/*, @euterpe/*, @metis/*, and @yemaya/* workspace
libraries plus pg, ioredis, and zod — it is the one app that composes the
domain engines directly. Seams are injectable and fail-closed (e.g. the Sophia
answer synthesizer is null ⇒ extractive composer; the deletion runner stays
scheduled rather than fabricating completion when the bus is absent).
Deployable shell for the agentic content service (ledger §3.2): boots the @oshun/content-service HTTP server over an Iris-routed creative writer + judge panel with durable run persistence. Running it requires a configured model provider ([~] for cloud deploy).
A small deployable shell, honestly thin (apps/oshun/content-service; the Nx
project name is @oshun/content-service-app, a single src/main.ts plus its
package.json). It is the process entrypoint for the agentic content service
(ledger §3.2): main() boots createDurableContentService /
createContentHttpServer from @oshun/content-service over an Iris-routed
Anthropic writer (wrapSharedProvider(createAnthropicProvider())) and a
three-member JudgePanel from @oshun/content-quality-judge, with creative
models pinned via resolveCreativeModel. It fails loud at startup without
ANTHROPIC_API_KEY ("generates with a real model or fails loud — it never
fabricates output") and supports CONTENT_SERVICE_DISABLED_MODELS for incident
downgrades. The real logic lives in the libraries it composes; this node is the
wiring + fail-loud guard around them, and the cloud deploy itself is tracked as
[~].
Telegram bot library (long-poll entrypoint kit) over the V1 messaging-channel policy core — NOT deployed; the live inbound path is the BFF webhook
The Oshun Telegram bot service (apps/oshun/telegram-bot), a TypeScript package
built on grammy that composes the V1 messaging-channel policy core from
@oshun/messaging-channels. src/index.ts defines per-environment
configuration (dev/staging/prod tokens + webhook secrets), a
webhook-secret-checked update handler, a per-process rate limiter, crisis-phrase
detection, a Sophia grounder (real retriever-backed or fixture), and real
speech-to-text via resolveSttVoiceProvider (fail-closed without credentials —
it replies "could not transcribe" rather than fabricating). It fails loud in
production against the UNCONFIGURED_PROD_BOT_TOKEN sentinel.
crypto-invoice-handler.ts implements the /upgrade crypto-paywall command. A
real, fail-closed integration.
GrammyWebhookRequest56GrammyWebhookResponse61TelegramBotEnvironment66UNCONFIGURED_PROD_BOT_TOKEN80TELEGRAM_BOT_ENVIRONMENTS82selectTelegramBotEnvironment103CryptoInvoiceWiring111TelegramBotWebhookWiring119resetGrammyWebhookRateLimiterForTests182handleGrammyCompatibleWebhook186deliverGrammyResponse275createOshunGrammyBot378registerBotCommands456setPacingSleepForTests474 +2 moreunclassified (9)#
The operator cockpit (apps/oshun/admin), a Next.js app (~628 .ts/.tsx
files; 24 route groups under src/app: review, inbox, incidents,
policy, moderation, trust-safety, research-integrity, privacy,
rights, support, editorial, isis, lilith, personas,
tenant-console, messaging, models, …). src/middleware.ts gates entry,
and the app ships ~48 Playwright e2e specs covering operator flows (unified
inbox, policy-bundle editor, DSAR review, moderation appeals, copilot audit
invariants, persona release, redesign signoff). It is a real, deeply-featured
admin surface that drives the BFF's admin-* routes; runs on port 3020.
The admin mobile companion (apps/oshun/admin-mobile), an Expo Router app (~94
.ts/.tsx files) described in its README as "the urgent operations companion
for escalations, on-call approvals, and high-priority incident acknowledgement."
It implements V1-AMOB-001: four thumb-reachable operator tabs (Urgent, Inbox,
Incidents, More) over the canonical admin workspace model, with shell-entry
gating via canEnterAdminShell/canEnterAdminWorkspace from
@oshun/navigation and session-expiry checks on mount. Real source under src/
(urgent-queue model + client + hook, review queue/decision/routing/evidence
clients, a dozen AdminMobile* components) and a Maestro e2e suite (auth,
step-up, review, incidents, signoff). Implemented, not scaffold.
Oshun Clipper — Manifest V3 browser extension that clips pages and text selections into the Oshun library as provenance-preserving sources
Browser clipper WebExtension (apps/oshun/clipper-extension/src): MV3
background/content scripts behind a typed capture-contract, a
chrome-adapter isolating the extension APIs, clip-flow/clip-payload for
capture-to-upload, and a health-check module — tested at the flow level
without a live browser.
Oshun Synthetics LTD corporate website (oshunsynthetics.com) — static export
The unified consumer mobile shell (apps/oshun/mobile), an Expo Router +
TypeScript app (~480 .ts/.tsx files) targeting iOS, Android, and web. Its
structural tabs are Home, Explore, Activity, Library, Profile (per ADR-0056),
with the assistant exposed as a global continuity sheet rather than a sixth tab.
It includes domain launch tiles (v2/, v3/, v6/ with companion apps like
V3CompanionApp, EgbeStewardApp), profile settings persistence, and runtime
config. The project.json carries an extensive Maestro-based e2e/device matrix
(core, nisaba-study, signoff, offline-retry suites across an iPhone profile and
a lower-tier Android profile) plus EAS build/submit and store-asset generation
targets. A real, launch-oriented app.
Static Telegram Mini App surfaces for Oshun V1
The static Telegram Mini App surfaces (apps/oshun/telegram-miniapp), a Next.js
app exposing seven read-oriented surfaces — today (Tara ritual), sophia
(grounded Q&A), veritas (claim review), nyx (sky), arete (check-in),
nisaba (reader), illustration (Isis card) — defined in
src/app/surface-data.ts and rendered through
src/app/[surface]/SurfaceWorkspace.tsx. src/lib/telegram-webapp.ts handles
the Telegram WebApp bridge. Honest scope note: the per-surface content in
surface-data.ts is curated, statically-typed launch fixture data (each
surface's evidence, provenance, and payload are hand-authored constants), so
this app demonstrates the Mini App surface shapes and Telegram integration
rather than serving live per-user domain data.
The tenant console (apps/oshun/tenant-admin), a Next.js app for tenant-scoped
administration — members, integrations, policy attestation, and tenant audit
history. src/app/page.tsx renders the tenant home over TenantShell, listing
workspaces from @oshun/navigation's listOshunTenantWorkspaceDefinitions(),
gated by getTenantServerSession(). Its src/lib/tenant-bff.ts performs
server-side BFF reads, forwarding the tenant.-prefixed session cookie as a
bearer token and returning null (honest "backend unreachable") on failure
rather than fabricating data. Smaller than @oshun/admin but real and
session-gated; runs on port 3030.
Native watch companions for the OSHUN mobile app (apps/oshun/wearable):
watchos/ (SwiftUI Swift Package) and wearos/ (Kotlin/Jetpack Compose), both
implementing the companion contract whose canonical TypeScript source of truth
is libs/oshun/shell-wearable — streaks/milestones, complications, guided
breath sessions with amplitude-mapped haptics under battery/skin budgets, quiet
hours, and consent-gated summaries.
The consumer-facing website and installable PWA (apps/oshun/web), a Next.js +
TypeScript app and the largest client surface (~5,600 .ts/.tsx files; 52
route directories under src/app). It renders the full unified shell — Home,
Explore, Activity, Library, Profile — plus dedicated per-domain surfaces
(nisaba, nyx, veritas, arete, tara, sophia, metis, lilith,
personas, studio/egbe-studio/mawu-studio, billing, legal, settings) and
operator/tenant entry points. It carries real PWA infrastructure
(public/sw.js, public/manifest.json), critical-route performance budgets
(src/performance/criticalRouteBudgets.ts) gated by Lighthouse via
lighthouserc.cjs, axe-core accessibility specs, and an extensive Playwright
e2e suite. Production-grade and mature, not scaffold.