Skip to content

Coverage Map

This map freezes the page inventory for the first CodeAlmanac build of yaya-engine, a Laravel 12 + Inertia/React fintech app (Atram's "Yaya" product: weather alerts, preparation tasks, verifications, and payouts delivered over WhatsApp, SMS, Telegram, and a PWA, distributed through FSP partners). Research across ten parallel scans (product/business, API surface, MCP/AI, domain model, messaging/Telegram, admin surfaces, auth, frontend, notifications/jobs, tests/harness/incidents) produced the page list below. Every planned page must be written in Phase 2 unless this file is updated with an exact repo-evidence removal reason.

Page Inventory

Root

  • path: almanac/getting-started.md slug: getting-started purpose: Front door for a new agent: what this repo is, the main subsystems, and where to read next for common work areas. planned links: concepts/vocabulary, architecture/README (as architecture), architecture/route-surfaces, architecture/ai/mcp-servers, architecture/messaging/pipeline, guides/operate-on-laravel-cloud evidence: README.md, CLAUDE.md, BUSINESS.md

concepts/

  • path: almanac/concepts/vocabulary.md slug: vocabulary purpose: Defines Atram, Yaya, Yaya Engine, Yaya Manager, FSP, and Rada and how these terms relate, as the foundational vocabulary for the rest of the wiki. planned links: concepts/fsp, architecture/README, architecture/data/supabase-and-rada-v2 evidence: BUSINESS.md, openspec/project.md, RADA_CODEBASE.md

  • path: almanac/concepts/fsp.md slug: fsp purpose: Explains the Financial Service Provider concept as this repo's multi-tenancy unit: branding, per-FSP channel config, and data scoping. planned links: concepts/vocabulary, architecture/data/domain-model, architecture/messaging/pipeline, decisions/auth/fsp-hostname-resolve evidence: BUSINESS.md, app/Models/Fsp.php, app/Models/Concerns/FiltersByManagerSession.php

  • path: almanac/concepts/verified-vs-onboarded.md slug: verified-vs-onboarded purpose: Explains why users.verified (location confirmed) and users.onboarded (T&C accepted) are distinct states that must always be filtered separately, and what breaks if they are conflated. planned links: architecture/data/domain-model, architecture/ai/mcp-servers, decisions/mcp/mcp-user-filtering evidence: database/migrations/2026_01_16_125929_add_onboarding_fields_to_users_table.php, app/Models/User.php, app/Http/Controllers/Api/UserController.php, app/Telegram/Handlers/LocationShareHandler.php

  • path: almanac/concepts/channel-abstraction.md slug: channel-abstraction purpose: Explains why the messaging system is built around a channel-agnostic interface instead of per-integration code, and what that buys the product (WhatsApp/SMS/Telegram/PWA parity). planned links: architecture/messaging/pipeline, architecture/messaging/telegram-bot, guides/add-messaging-channel evidence: app/Services/Messaging/Contracts/ChannelInterface.php, app/Services/Messaging/ChannelManager.php, app/Services/Messaging/ChannelResolver.php

  • path: almanac/concepts/mcp-tools.md slug: mcp-tools purpose: Explains MCP (Model Context Protocol) tools as the sole contract through which AI agents (Dify, and internally Claude) read and write business data in this repo. planned links: architecture/ai/mcp-servers, reference/mcp-tools, decisions/mcp/mcp-token-minting, guides/add-mcp-tool evidence: app/Mcp/Servers/YayaServer.php, app/Mcp/Servers/InternalYayaServer.php, app/Mcp/Tools/Internal/InternalTool.php

  • path: almanac/concepts/rada-v2-collapse.md slug: rada-v2-collapse purpose: Explains the in-flight architectural migration collapsing the separate Supabase weather/alert database into yaya-engine's own Postgres, why it exists, and what "cutover" means for this repo. planned links: concepts/vocabulary, architecture/data/supabase-and-rada-v2, decisions/rada-v2-postgres-cutover, reference/api-v1-surface evidence: BUSINESS.md, docs/2026-07-08-rada-v2-postgres-verification.md, docs/observability/rada-supabase-tripwire.md, config/rada.php

  • path: almanac/concepts/preparation-plans.md slug: preparation-plans purpose: Explains the user journey data model: Actions/UserActions/ ActionSteps/Verifications/Payouts, i.e. how a user moves from being alerted to completing preparation tasks to receiving a payout. planned links: architecture/data/domain-model, architecture/admin/yaya-manager, guides/bulk-edit-action-catalog evidence: openspec/project.md, database-architecture.md, app/Models/Action.php (model group evidence), app/Models/UserAction.php

architecture/

  • path: almanac/architecture/README.md slug: architecture purpose: Hub page for the system's layers (auth, admin, API, AI/MCP, messaging, data) and how they fit together, correcting the stale aspirational picture in openspec/project.md. planned links: architecture/route-surfaces, architecture/ai/mcp-servers, architecture/auth/auth-architecture, architecture/data/domain-model, architecture/messaging/pipeline, architecture/admin/admin-panel, architecture/admin/yaya-manager, architecture/frontend/inertia-wayfinder evidence: CLAUDE.md, openspec/project.md, composer.json

  • path: almanac/architecture/route-surfaces.md slug: route-surfaces purpose: Maps the distinct HTTP route surfaces (web/PWA, api, api/v1, manager, mcp, ai, telegram, auth, settings, test) to their owners, auth mechanisms, and purpose. planned links: architecture/README, architecture/auth/auth-architecture, architecture/ai/mcp-servers, reference/api-v1-surface evidence: routes/api.php, routes/web.php, routes/manager.php, routes/mcp.php, routes/ai.php, routes/telegram.php, routes/test.php, bootstrap/app.php, app/Http/Middleware/

  • path: almanac/architecture/messaging/pipeline.md slug: messaging-pipeline (route: architecture/messaging/pipeline) purpose: Explains the inbound/outbound message job chain and the ChannelManager/ChannelResolver layer that routes a message to WhatsApp, SMS, Telegram, or PWA. planned links: concepts/channel-abstraction, architecture/messaging/telegram-bot, architecture/ai/mcp-servers (Dify hookup), decisions/messaging/chunk-batch-message-processing, guides/debug-message-delivery evidence: app/Jobs/ProcessIncomingMessage.php, app/Jobs/SendChannelMessage.php, app/Services/Messaging/ChannelManager.php, app/Services/Messaging/ChannelResolver.php, app/Services/Messaging/Channels/WhatsAppChannel.php, app/Services/Messaging/Channels/SmsChannel.php

  • path: almanac/architecture/messaging/telegram-bot.md slug: telegram-bot (route: architecture/messaging/telegram-bot) purpose: Explains the Telegram bot architecture built on Nutgram: command/conversation handlers, the mini-app integration, and the phone/location request automation. planned links: concepts/channel-abstraction, architecture/messaging/pipeline, decisions/messaging/telegram-locale-override evidence: routes/telegram.php, config/nutgram.php, app/Telegram/Conversations/PayoutConversation.php, app/Telegram/Handlers/LocationShareHandler.php, app/Services/Messaging/Telegram/TelegramLocationRequestSender.php, docs/superpowers/specs/2026-04-27-telegram-mini-app-integration-design.md

  • path: almanac/architecture/ai/mcp-servers.md slug: mcp-servers (route: architecture/ai/mcp-servers) purpose: Explains the two MCP servers (public YayaServer for Dify, internal InternalYayaServer for team/Claude use), their auth mechanisms, and how Dify itself fits into the inbound message flow as the live AI layer (not Prism, despite older docs). planned links: concepts/mcp-tools, reference/mcp-tools, architecture/auth/auth-architecture, decisions/mcp/mcp-token-minting, decisions/mcp/dify-kill-switch evidence: app/Mcp/Servers/YayaServer.php, app/Mcp/Servers/InternalYayaServer.php, app/Mcp/Tools/Internal/InternalTool.php, app/Services/Dify/DifyService.php, app/Http/Integrations/Dify/DifyConnector.php, routes/ai.php, routes/mcp.php

  • path: almanac/architecture/auth/auth-architecture.md slug: auth-architecture (route: architecture/auth/auth-architecture) purpose: Explains the three real auth guards (web/admin/api), what WorkOS AuthKit, Passport, and Sanctum actually each do, and the magic link + OTP flow for end users. planned links: architecture/README, architecture/ai/mcp-servers, decisions/auth/magic-link-8-char-tokens, decisions/auth/magic-link-single-use-default evidence: config/auth.php, config/passport.php, config/sanctum.php, routes/auth.php, app/Services/Auth/MagicLinkService.php (or equivalent), app/Models/MagicLink.php, app/Services/Auth/OtpService.php

  • path: almanac/architecture/data/domain-model.md slug: domain-model (route: architecture/data/domain-model) purpose: Maps the Eloquent model groups (user/auth, FSP, messaging, alerts/weather, actions/verifications/payouts, generated links/marketing, admin) and their key relationships. planned links: concepts/fsp, concepts/preparation-plans, concepts/verified-vs-onboarded, reference/enums, architecture/data/supabase-and-rada-v2 evidence: app/Models/User.php, app/Models/Fsp.php, app/Models/Action.php, app/Models/Alert.php, app/Models/Concerns/FiltersByManagerSession.php, database-architecture.md

  • path: almanac/architecture/data/supabase-and-rada-v2.md slug: supabase-and-rada-v2 (route: architecture/data/supabase-and-rada-v2) purpose: Explains the legacy Supabase integration, the "tripwire" safeguard that detects residual calls to it, and the state of the Rada v2 cutover collapsing geography/alert data into yaya-engine's own Postgres. planned links: concepts/rada-v2-collapse, architecture/data/domain-model, decisions/rada-v2-postgres-cutover, reference/api-v1-surface evidence: app/Http/Integrations/Supabase/SupabaseConnector.php, app/Services/SupabaseService.php, docs/observability/rada-supabase-tripwire.md, docs/2026-07-08-rada-v2-postgres-verification.md, config/rada.php

  • path: almanac/architecture/admin/admin-panel.md slug: admin-panel (route: architecture/admin/admin-panel) purpose: Explains the Filament admin panel (/admin) as the data-management/CRUD back office, its resource catalog, and its access control model. planned links: architecture/admin/yaya-manager, concepts/preparation-plans, guides/bulk-edit-action-catalog evidence: app/Providers/Filament/AdminPanelProvider.php, app/Filament/Resources/, app/Support/AdminAccess.php, app/Models/AdminUser.php

  • path: almanac/architecture/admin/yaya-manager.md slug: yaya-manager (route: architecture/admin/yaya-manager) purpose: Explains the Yaya Manager Inertia/React ops console as the task-focused workflow app (validation queue, payouts, user lookup, alerts, analytics), distinct from the Filament admin panel. planned links: architecture/admin/admin-panel, architecture/frontend/inertia-wayfinder, concepts/fsp, concepts/preparation-plans evidence: routes/manager.php, app/Http/Controllers/Manager/, resources/js/pages/manager/, app/Http/Controllers/Manager/Concerns/AuthorizesManagerAccess.php

  • path: almanac/architecture/frontend/inertia-wayfinder.md slug: inertia-wayfinder (route: architecture/frontend/inertia-wayfinder) purpose: Explains the Inertia.js v2 + React + Wayfinder frontend pattern: how a Laravel route becomes a typed TypeScript helper, and the Tailwind v4/shadcn component conventions. planned links: architecture/admin/yaya-manager, architecture/route-surfaces evidence: vite.config.ts, components.json, resources/js/routes/, resources/js/actions/, resources/js/pages/welcome.tsx

  • path: almanac/architecture/notifications.md slug: notifications purpose: Explains the AtramNotification architecture: how it picks a channel (Telegram > PWA push > WhatsApp > SMS), and the separate Slack ops-notification system. planned links: architecture/messaging/pipeline, decisions/messaging/atram-notification-routing evidence: app/Notifications/AtramNotification.php, app/Services/SlackNotificationService.php, docs/slack-notifications.md

  • path: almanac/architecture/generated-links.md slug: generated-links purpose: Explains the generated links marketing-attribution system: trackable multi-use URLs that stamp segmentation data onto new users and feed acquisition analytics. planned links: architecture/admin/admin-panel, concepts/fsp evidence: app/Services/GeneratedLinks/GeneratedLinkService.php, app/Http/Controllers/Api/GeneratedLinkClickController.php, docs/superpowers/specs/2026-05-01-generated-links-design.md

guides/

  • path: almanac/guides/add-mcp-tool.md slug: add-mcp-tool purpose: Guide for adding a new internal MCP tool: extending InternalTool, wiring the required permission, and testing it. planned links: concepts/mcp-tools, architecture/ai/mcp-servers, reference/mcp-tools evidence: app/Mcp/Tools/Internal/InternalTool.php, app/Mcp/Tools/Internal/ (sample tool), openspec/project.md (make:mcp-tool convention)

  • path: almanac/guides/debug-message-delivery.md slug: debug-message-delivery purpose: Guide for diagnosing a failed or silently-dropped outbound message: where to look (delivery logs, Slack alerts, batch chunk errors, column-length truncation). planned links: architecture/messaging/pipeline, decisions/messaging/chunk-batch-message-processing, architecture/notifications evidence: docs/solutions/database-issues/varchar-truncation-sms-retargeting-silent-failure.md, app/Jobs/ProcessMessageBatch.php, app/Services/Messaging/BatchMessagingService.php

  • path: almanac/guides/run-cross-repo-harness.md slug: run-cross-repo-harness purpose: Guide for running harness/test_cross_repo_flow.py to verify the live HTTP contract between yaya-engine and the sibling rada-weather repo. planned links: concepts/rada-v2-collapse, reference/api-v1-surface evidence: harness/test_cross_repo_flow.py, harness/seed_towns.php

  • path: almanac/guides/operate-on-laravel-cloud.md slug: operate-on-laravel-cloud purpose: Guide for operating this app on Laravel Cloud: running Artisan commands remotely, the ephemeral-filesystem gotcha (Passport keys, file downloads), and database access. planned links: architecture/auth/auth-architecture evidence: CLAUDE.md, config/passport.php, docs/solutions/runtime-errors/laravel-cloud-excel-export-404-ephemeral-storage.md, docs/superpowers/specs/2026-07-01-mcp-token-minting-design.md

  • path: almanac/guides/add-messaging-channel.md slug: add-messaging-channel purpose: Guide for adding a new outbound/inbound messaging channel by implementing ChannelInterface and registering it with ChannelManager. planned links: concepts/channel-abstraction, architecture/messaging/pipeline evidence: app/Services/Messaging/Contracts/ChannelInterface.php, app/Services/Messaging/Channels/SmsChannel.php, app/Services/Messaging/ChannelManager.php

  • path: almanac/guides/onboard-new-country-fsp.md slug: onboard-new-country-fsp purpose: Guide for onboarding a new country/FSP market, drawing on the Ethiopia pilot launch as the worked example (config, seeding, locale, geography backfill, common mistakes). planned links: concepts/fsp, concepts/vocabulary, architecture/data/supabase-and-rada-v2 evidence: config/countries.php, database/seeders/EthiopiaPilotFspSeeder.php, docs/solutions/integration-issues/ethiopia-v1-launch-summary.md, docs/solutions/integration-issues/ethiopia-thresholds-dual-system-yaya-365.md

  • path: almanac/guides/bulk-edit-action-catalog.md slug: bulk-edit-action-catalog purpose: Guide for using the action-workbook Excel import/export to bulk-edit the preparation-task catalog instead of editing one row at a time in Filament. planned links: concepts/preparation-plans, architecture/admin/admin-panel evidence: app/Support/ActionWorkbooks/, docs/superpowers/specs/2026-03-15-action-workbook-import-export-design.md, app/Filament/Resources/Actions/Pages/ListActions.php

decisions/

  • path: almanac/decisions/mcp/mcp-token-minting.md slug: mcp-token-minting (route: decisions/mcp/mcp-token-minting) purpose: Records why MCP machine clients needed Passport personal-access tokens minted from a Filament page, and how that layers on the existing OAuth flow. planned links: architecture/ai/mcp-servers, concepts/mcp-tools, guides/operate-on-laravel-cloud evidence: docs/superpowers/specs/2026-07-01-mcp-token-minting-design.md, app/Filament/Pages/ManageMcpTokens.php, config/passport.php

  • path: almanac/decisions/mcp/mcp-user-filtering.md slug: mcp-user-filtering (route: decisions/mcp/mcp-user-filtering) purpose: Records the incident where an MCP tool wrongly reported zero app users because it lacked verified/onboarded filters, and the fix that added explicit, separate filters and pagination signaling. planned links: concepts/verified-vs-onboarded, architecture/ai/mcp-servers, reference/mcp-tools evidence: docs/superpowers/specs/2026-04-24-mcp-user-filtering-design.md, app/Services/UserQueryService.php, app/Mcp/Tools/Internal/QueryUsersTool.php

  • path: almanac/decisions/mcp/dify-kill-switch.md slug: dify-kill-switch (route: decisions/mcp/dify-kill-switch) purpose: Records the decision to add a runtime, per-channel admin toggle that pauses only the Dify AI hand-off without breaking other inbound-message handling. planned links: architecture/ai/mcp-servers, architecture/messaging/pipeline evidence: docs/superpowers/specs/2026-05-16-dify-kill-switch-settings-design.md, app/Settings/KillSwitchSettings.php, app/Jobs/ProcessIncomingMessage.php

  • path: almanac/decisions/messaging/chunk-batch-message-processing.md slug: chunk-batch-message-processing (route: decisions/messaging/chunk-batch-message-processing) purpose: Records why bulk alert sends were chunked into groups of 500 after two real alerts delivered only 17-25% of messages under a single monolithic queue job. planned links: architecture/messaging/pipeline, guides/debug-message-delivery evidence: docs/superpowers/specs/2026-03-18-chunk-batch-message-processing-design.md, app/Services/Messaging/BatchMessagingService.php, app/Jobs/ProcessMessageBatch.php

  • path: almanac/decisions/messaging/telegram-locale-override.md slug: telegram-locale-override (route: decisions/messaging/telegram-locale-override) purpose: Records the fix for Ethiopia-pilot Telegram users being wrongly registered in English because Telegram's language_code has no Amharic value, via a per-FSP default-locale override. planned links: architecture/messaging/telegram-bot, concepts/fsp evidence: docs/superpowers/specs/2026-06-24-telegram-locale-override-design.md, app/Services/Auth/TelegramUserResolver.php

  • path: almanac/decisions/messaging/atram-notification-routing.md slug: atram-notification-routing (route: decisions/messaging/atram-notification-routing) purpose: Records the redesign of the notification system into a single smart-routed AtramNotification base class with a shared delivery-logging listener, replacing ad-hoc per-channel notification logic. planned links: architecture/notifications, architecture/messaging/pipeline evidence: docs/superpowers/specs/2026-05-08-atram-notifications-design.md, app/Notifications/AtramNotification.php

  • path: almanac/decisions/auth/magic-link-8-char-tokens.md slug: magic-link-8-char-tokens (route: decisions/auth/magic-link-8-char-tokens) purpose: Records why magic link tokens shrank from 64 random characters to 8, and the constraints that shaped the change (SMS/WhatsApp URL length, single-source-of-truth generation). planned links: architecture/auth/auth-architecture evidence: docs/superpowers/specs/2026-04-23-magic-link-8-char-tokens-design.md, app/Models/MagicLink.php

  • path: almanac/decisions/auth/magic-link-single-use-default.md slug: magic-link-single-use-default (route: decisions/auth/magic-link-single-use-default) purpose: Records the incident where a wrong single-use default locked users out of their own magic link on a second tap, and the one-line default flip that fixed it. planned links: architecture/auth/auth-architecture, decisions/auth/magic-link-8-char-tokens evidence: docs/solutions/logic-errors/magic-link-single-use-default-blocks-reuse.md, app/Models/MagicLink.php

  • path: almanac/decisions/auth/fsp-hostname-resolve.md slug: fsp-hostname-resolve (route: decisions/auth/fsp-hostname-resolve) purpose: Records the decision behind the public, cached GET /api/fsp/resolve endpoint that lets the PWA brand itself per FSP hostname before authentication. planned links: concepts/fsp, architecture/route-surfaces evidence: docs/decisions/issue-155-fsp-hostname-resolve.md, docs/solutions/integration-issues/fsp-hostname-branding-resolver.md, app/Observers/FspObserver.php

  • path: almanac/decisions/rada-v2-postgres-cutover.md slug: rada-v2-postgres-cutover purpose: Records the decision to collapse Supabase-hosted weather/alert data into yaya-engine's own Postgres, the verification process used, and the process lesson from a cutover ticket that was closed before its effect was confirmed in production. planned links: concepts/rada-v2-collapse, architecture/data/supabase-and-rada-v2, guides/run-cross-repo-harness evidence: docs/2026-07-08-rada-v2-postgres-verification.md, docs/observability/rada-supabase-tripwire.md, docs/solutions/database-issues/p22-geography-cutover-closed-but-prod-tables-empty.md

reference/

  • path: almanac/reference/mcp-tools.md slug: mcp-tools (route: reference/mcp-tools) purpose: Exact lookup table of every MCP tool on both servers, which entities each reads/writes, and the permission it requires. planned links: architecture/ai/mcp-servers, concepts/mcp-tools evidence: app/Mcp/Tools/GetUserActionsTool.php, app/Mcp/Tools/Internal/ (all tools), app/Mcp/Tools/Internal/InternalTool.php

  • path: almanac/reference/artisan-commands.md slug: artisan-commands purpose: Exact lookup list of this repo's custom Artisan commands (Rada weather ingestion/loadtest, Supabase backfills, Telegram webhook management, MCP client provisioning, locale alignment) and what each does. planned links: architecture/data/supabase-and-rada-v2, guides/run-cross-repo-harness evidence: app/Console/Commands/RadaLoadtest/ComposerBulkInsertCommand.php, app/Console/Commands/RadaWeather/IngestWoredasCommand.php, routes/console.php

  • path: almanac/reference/enums.md slug: enums purpose: Exact lookup list of this repo's domain enums and the states or categories each represents (channel types, alert severities, action/step statuses, payout statuses, locales, etc). planned links: architecture/data/domain-model, concepts/preparation-plans evidence: app/Enums/ (full directory)

  • path: almanac/reference/api-v1-surface.md slug: api-v1-surface (route: reference/api-v1-surface) purpose: Exact lookup reference for the versioned /api/v1 surface used by the sibling Rada services (scheduled alerts, composed messages, geography, forecasts, observations, dispatch modes). planned links: architecture/route-surfaces, architecture/data/supabase-and-rada-v2, guides/run-cross-repo-harness evidence: routes/api.php, docs/api/v1/, app/Http/Controllers/Api/V1/

Notes On Scope Decisions

  • docs/solutions/database-issues/varchar-truncation-sms-retargeting-silent-failure.md is folded into guides/debug-message-delivery.md as a concrete failure mode rather than given its own page; it is a single-column-width bug, not a standalone architectural decision.
  • docs/solutions/integration-issues/fsp-hostname-branding-resolver.md is merged into decisions/auth/fsp-hostname-resolve.md since both describe the same endpoint from postmortem vs decision angles.
  • docs/superpowers/specs/2026-05-21-user-export-page-design.md and 2026-05-22-user-export-custom-metadata-design.md are covered inside architecture/admin/admin-panel.md rather than as separate decision pages; they are incremental Filament tooling, not architecturally distinct choices.
  • openspec/ change history is not mapped page-by-page: the team has moved design-doc activity to docs/superpowers/, confirmed by recency (superpowers reaches July 2026; unarchived openspec changes top out mid-May 2026 with archiving stalled since March 2026). openspec/ is mentioned only as historical context inside concepts/vocabulary.md.
  • Mixpanel analytics, LangFuse, and Portkey are documented in CLAUDE.md / openspec/project.md but have zero code presence (confirmed by repo-wide grep); they are noted as aspirational/absent inside architecture/README.md and architecture/ai/mcp-servers.md rather than given dedicated pages.