Skip to content

Yaya Engine System Architecture

Yaya Engine is the Laravel 12 system of record behind Yaya, a fintech platform that delivers weather alerts and financial-preparation guidance to end users over WhatsApp, SMS, Telegram, and a PWA, distributed white-label through FSP partners. It owns user profiles, FSP associations, preparation plans and their actions, verification evidence, payouts, and the messaging pipeline that reaches every channel. Around that core sit three separate consoles — a Filament admin panel, a distinct Yaya Manager Inertia app for ops, and an MCP tool layer that lets both an external AI agent (Dify) and the internal engineering team (via Claude) read and write business data. This page is the map of how those pieces fit together, and where the project's own documentation gets ahead of what is actually running.

The documented picture versus the real one

CLAUDE.md describes the system as four "Core Layers" — API, Data, MCP, and WhatsApp Integration — sitting under a request flow where Dify hands every AI response through Portkey (an LLM router and guardrail) before logging to Mixpanel and LangFuse (an observability tracer) [@claude-md]. openspec/project.md goes further, listing echolabsdev/prism (Prism PHP, a provider-agnostic LLM orchestration library) as an installed dependency and describing Portkey and LangFuse as part of the target stack [@project-md]. None of this is true of the code that runs today. composer.json has no echolabsdev/prism requirement, and a repository-wide search for "Prism", "Portkey", and "LangFuse" across app/ and config/ returns zero matches [@composer-json]. The AI layer that actually exists is a direct integration: DifyService builds a chat request keyed on the User's ID as the Dify session ID (so a conversation carries over across channels) and hands it to DifyConnector, a Saloon HTTP client that POSTs straight to Dify's /v1/chat-messages endpoint with a bearer API key [@dify-service] [@dify-connector]. There is nothing between Yaya Engine and Dify — no guardrail proxy, no observability sidecar. See MCP servers and Dify AI integration for the full flow and the kill switch that can pause this hand-off per channel.

The same gap shows up in the admin surface. project.md marks Filament as "to be installed" and Sanctum as "to be installed," but filament/filament is a real dependency and the primary admin surface: sixteen resources under app/Filament/Resources/ (Users, Fsps, Actions, MessageBatches, Conversations, RequestedPayouts, and more), served through AdminPanelProvider, which mounts the panel at /admin behind the admin guard [@admin-panel-provider] [@filament-resources-dir]. Sanctum is likewise live — it is the actual end-user PWA auth mechanism, issued after a magic-link or OTP exchange (see Auth architecture). Treat openspec/project.md as a snapshot of original intent, not as documentation of the current system; where it disagrees with code, the code wins.

The three guards and who uses them

config/auth.php defines exactly three authentication guards, and each one maps to a distinct population of people or machines rather than to three parallel architectural layers [@auth-config]:

  • web — session-based, backed by the users provider (App\Models\User). This is the guard WorkOS AuthKit rides for staff SSO: routes/auth.php wraps WorkOS's AuthKitLoginRequest/AuthKitAuthenticationRequest/AuthKitLogoutRequest helpers directly against the default web guard, so logging in through WorkOS is indistinguishable, guard-wise, from any other web session [@routes-auth]. There is no separate workos guard, despite diagrams that suggest one.
  • admin — session-based, backed by admin_users (App\Models\AdminUser). This is what the Filament panel, the Yaya Manager app, and the small /mcp/login session controller all authenticate against.
  • api — driver passport, backed by admin_users [@passport-config]. Passport in this codebase is not end-user authentication; it issues personal-access tokens to service-account AdminUser records so machine clients (the internal team, via Claude Desktop/Code) can call the OAuth-protected /mcp/internal-yaya MCP server. See Auth architecture for the full breakdown, including the magic-link and OTP flows that put a Sanctum token in an end user's hands.

Layers and their entrypoints

Five system areas do the actual work, each documented on its own page:

  • HTTP surface — nine distinct route files (web, api, manager, mcp, ai, auth, settings, telegram, test) each answer to a different guard and audience, from the public WhatsApp/Telegram webhooks to the service-to-service /api/v1 namespace that replaced direct Supabase RPCs for sibling Rada services. See HTTP route surfaces map.
  • AI and MCP — YayaServer exposes three tools at /mcp/yaya for Dify to call machine-to-machine; InternalYayaServer exposes twenty tools at /mcp/internal-yaya for the team to call over OAuth. See MCP servers and Dify AI integration, and the tool catalog in the MCP tools reference.
  • Auth — three guards, WorkOS SSO, Passport for machine tokens, Sanctum for end users, plus the magic-link and OTP flows that get a phone number to a Sanctum token. See Auth architecture.
  • Domain data — the Eloquent model graph spanning users/FSPs, messaging, alerts/weather, actions/verifications/payouts, and the newer Rada v2 geography and dispatch tables. See Domain data model and Supabase and the Rada v2 cutover.
  • Messaging and admin consoles — the inbound/outbound message pipeline across WhatsApp/SMS/Telegram/PWA, the Filament admin panel, and the separate Yaya Manager ops console. See Messaging pipeline, Admin panel, and Yaya Manager.

Two consoles exist side by side deliberately: Filament is the general-purpose CRUD admin over every model, while Yaya Manager is a purpose-built Inertia/React app for the ops team's daily verification-queue and payout workflows, gated by granular manager.* permissions rather than Filament's broader admin access. A reader who only knows CLAUDE.md's four-layer table will miss both of them, along with the fact that the "MCP Layer" is really two independently-authenticated servers with very different audiences and write permissions.