Getting Started With Yaya Engine

Atram is a climate-finance company: it delivers AI-powered weather alerts and financial-preparation guidance to financially vulnerable users in emerging markets, over WhatsApp, SMS, and a whitelabel PWA [@business-md]. Distribution runs mostly through FSP partners — banks and microfinance lenders such as Fortune Credit in Kenya or Bancamía in Colombia — that already serve those users, plus a fallback "Atram" FSP for direct users with no partner bank [@business-md]. Yaya Engine, this repository, is the central orchestration layer behind that product: it holds users, FSP associations, preparation plans, verification evidence, and payouts, and it dispatches every outbound message, so most of Atram's other services (rada-weather, rada-message-system, alert-manager) treat it as the system of record rather than duplicating its tables [@business-md]. The current focus is the FLASH pilot: WhatsApp delivery, FSP-associated user data, preparation plans and actions, evidence upload and verification, alert dispatch, and manual M-Pesa payout tracking, with loan restructuring and automated payouts explicitly left to the FSP or a later phase [@claude-md].

If a term in this paragraph is unfamiliar — FSP, Yaya vs. Yaya Engine vs. Yaya Manager, Rada, FLASH — read Vocabulary first. It is the fastest way to stop tripping over names that sound interchangeable but are not.

Start with the correction, not the aspiration

Before touching any subsystem, read Yaya Engine system architecture. CLAUDE.md and openspec/project.md describe a four-layer system where every AI response passes from Dify through Portkey (an LLM guardrail router) and gets traced in LangFuse, and they list Prism PHP as an installed orchestration dependency. None of that exists in the code that runs today: there is no Portkey, no LangFuse, and no Prism dependency anywhere in app/ or config/, and the real AI path is a direct HTTP integration where DifyService builds a chat request and DifyConnector posts it straight to Dify's /v1/chat-messages endpoint with no guardrail proxy in between. The same gap shows up in auth: the docs imply a separate workos guard, but WorkOS SSO actually rides the plain web session guard alongside every other web login. Treat the architecture hub page as the corrected map and treat CLAUDE.md/openspec/project.md as a record of original intent, not current behavior — the two disagree in several places, and code wins.

The dense clusters

Five areas carry most of the system's weight, and each has its own reading path.

Messaging and channels. Every inbound and outbound message — WhatsApp, SMS, Telegram, the PWA — flows through a shared pipeline described in Messaging pipeline, with Channel abstraction explaining how one code path serves four different transports. Telegram gets its own page, Telegram bot, because its bot-command and broadcast model differs from the webhook-driven WhatsApp/SMS flow. If a message did not arrive, Debug message delivery is the guide to run down why, and Add a messaging channel is the guide for adding a fifth transport. Decisions that shaped this cluster include Chunk/batch message processing, Telegram locale override, and Atram notification routing.

AI and MCP. Dify is the AI agent that talks to end users; it reads and writes business data by calling MCP tools hosted on this repo, and the internal engineering team calls a second, separately-authenticated MCP server over OAuth. MCP servers and Dify AI integration is the entry point, Add an MCP tool is the guide for extending either server, and MCP tools reference is the exact tool catalog. The concept page MCP tools explains why tools rather than a raw API surface. Three decisions constrain this cluster: MCP token minting, MCP user filtering, and the Dify kill switch that can pause the Dify hand-off per channel.

Auth. Three session guards — web, admin, and api (Passport) — cover three different populations: staff SSO through WorkOS, admin/ops console logins, and machine clients calling the internal MCP server. End users authenticate through magic links or OTP into a Sanctum token, not through any of those three guards directly. Auth architecture is the full breakdown; the decisions Magic-link 8-char tokens, Magic-link single-use default, and FSP hostname resolve explain specific choices in that flow.

Admin surfaces. Two consoles exist side by side on purpose: the Filament panel is general-purpose CRUD over every model (Admin panel), while Yaya Manager is a purpose-built Inertia/React app for the ops team's verification-queue and payout workflows, scoped by FSP and manager.* permissions (Yaya Manager). Bulk-edit the action catalog is a common task inside that ops surface, and Inertia and Wayfinder explains how the React frontend calls back into Laravel routes.

Data model and the Rada v2 migration. Domain data model maps the Eloquent graph for users, FSPs, messaging, alerts, and preparation plans (see also Preparation plans and Verified vs. onboarded for two states that are easy to conflate). A separate migration is underway to collapse the current Supabase-backed alert/dispatch database into this repo's own Postgres; Supabase and Rada v2 and Rada v2 collapse describe the interim state, and Rada v2 Postgres cutover records the cutover decision. Onboard a new country/FSP is the guide for the most common data-model-touching task: bringing in a new FSP partner.

Cutting across all of it

Two more pages sit underneath everything above rather than inside one cluster: HTTP route surfaces map lists the nine separate route files and which guard and audience each one answers to, and Notifications and Generated links cover cross-cutting delivery and link-generation concerns used by several of the clusters above.

For day-to-day operations rather than a specific subsystem, Operate on Laravel Cloud covers running Artisan commands and reading logs against the hosted environment, and Run cross-repo harness covers exercising Yaya Engine together with its sibling Rada services. When a task needs an exact lookup rather than an explanation, go straight to the reference pages: Artisan commands, Enums, and API v1 surface for the versioned REST namespace that other Atram services call.