# abdulrahmnh/revora architecture

> Architecture diagram of the GitHub repository abdulrahmnh/revora, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/abdulrahmnh/revora
- Repository: https://github.com/abdulrahmnh/revora
- Video tour (about a minute): https://gitdiagram.com/abdulrahmnh/revora/video

## Overview

Mujaser is an embedded Salla revenue-intelligence product. Its merchant loop is to establish a store session, assess data readiness, present a prioritized opportunity, record a merchant decision and any WhatsApp handoff truth, then measure completed-order observations and report observed value with conservative attribution. The three documented engines cover abandoned carts, lost customers, and second purchases. The tree and excerpts support the main API, integration, and engine boundaries; detailed persistence and worker dispatch wiring is not fully sampled, so uncertain links are omitted.

Main entry points: [`packages/core/src/database/client.ts`](https://github.com/abdulrahmnh/revora/blob/main/packages/core/src/database/client.ts) (PostgreSQL access), [`packages/core/src/integrations/salla/sync-service.ts`](https://github.com/abdulrahmnh/revora/blob/main/packages/core/src/integrations/salla/sync-service.ts) (Salla integration), [`apps/web/src/app/app/embedded/salla/page.tsx`](https://github.com/abdulrahmnh/revora/blob/main/apps/web/src/app/app/embedded/salla/page.tsx) (Embedded app), [`packages/core/src/opportunities/merchant-decision-loop.ts`](https://github.com/abdulrahmnh/revora/blob/main/packages/core/src/opportunities/merchant-decision-loop.ts) (Decision and action)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Merchant experience"]
  node_embedded["Embedded app<br/>[page.tsx]"]
  node_session_api["Session API<br/>[route.ts]"]
end

subgraph group_foundation["Store foundation"]
  node_session_auth["Embedded session"]
  node_salla_integration["Salla integration<br/>[sync-service.ts]"]
  node_readiness_api["Readiness API<br/>[route.ts]"]
  node_readiness["Data readiness"]
  node_stage_api["Merchant stage API<br/>[route.ts]"]
  node_stage_service["Merchant stage"]
  node_cart_ingest["Cart ingestion"]
end

subgraph group_opportunities["Opportunity lifecycle"]
  node_cart_engine["Cart recovery engine"]
  node_lost_engine["Lost customer engine"]
  node_second_engine["Second purchase engine"]
  node_feed_api["Opportunity feed API<br/>[route.ts]"]
  node_feed["Prioritized feed"]
  node_decision_api["Opportunity actions<br/>[route.ts]"]
  node_decision_loop["Decision and action"]
  node_whatsapp["WhatsApp handoff<br/>[whatsapp-action.ts]"]
end

subgraph group_operations["Measurement and operations"]
  node_worker["Background worker<br/>[index.ts]"]
  node_measurement["Outcome observation"]
  node_attribution["Attribution receipts"]
  node_reporting["Value and insights"]
  node_notifications_api["Notifications API<br/>[route.ts]"]
  node_notifications["Notification service"]
  node_database[("PostgreSQL access<br/>[client.ts]")]
end

node_merchant(("Merchant"))
node_salla(("Salla"))

node_merchant -->|"opens"| node_embedded
node_embedded -->|"requests session"| node_session_api
node_session_api -->|"creates session"| node_session_auth
node_salla -->|"provides token"| node_session_api
node_salla -->|"provides store data"| node_salla_integration
node_worker -->|"runs sync"| node_salla_integration
node_salla_integration -->|"stores synced data"| node_database
node_readiness_api -->|"assesses"| node_readiness
node_readiness -->|"reads store data"| node_database
node_stage_api -->|"gets stage"| node_stage_service
node_stage_service -->|"reads store state"| node_database
node_salla_integration -->|"ingests carts"| node_cart_ingest
node_cart_ingest -->|"upserts carts"| node_database
node_cart_engine -->|"reads and saves"| node_database
node_lost_engine -->|"reads and saves"| node_database
node_second_engine -->|"reads and saves"| node_database
node_feed_api -->|"loads feed"| node_feed
node_feed -->|"reads opportunities"| node_database
node_embedded -->|"requests opportunities"| node_feed_api
node_merchant -->|"submits decision"| node_decision_api
node_decision_api -->|"records action"| node_decision_loop
node_decision_loop -->|"persists action"| node_database
node_decision_loop -->|"creates handoff"| node_whatsapp
node_merchant -->|"confirms execution"| node_whatsapp
node_measurement -->|"records observations"| node_database
node_attribution -->|"records receipts"| node_database
node_reporting -->|"reads outcomes"| node_database
node_notifications_api -->|"reconciles and loads"| node_notifications
node_notifications -->|"reads and writes intents"| node_database

click node_embedded "https://github.com/abdulrahmnh/revora/blob/main/apps/web/src/app/app/embedded/salla/page.tsx"
click node_session_api "https://github.com/abdulrahmnh/revora/blob/main/apps/web/src/app/api/session/salla-embedded/route.ts"
click node_session_auth "https://github.com/abdulrahmnh/revora/blob/main/packages/core/src/auth/salla-embedded-session.ts"
click node_salla_integration "https://github.com/abdulrahmnh/revora/blob/main/packages/core/src/integrations/salla/sync-service.ts"
click node_worker "https://github.com/abdulrahmnh/revora/blob/main/apps/worker/src/index.ts"
click node_readiness_api "https://github.com/abdulrahmnh/revora/blob/main/apps/web/src/app/api/readiness/route.ts"
click node_readiness "https://github.com/abdulrahmnh/revora/blob/main/packages/core/src/readiness/data-readiness-service.ts"
click node_stage_api "https://github.com/abdulrahmnh/revora/blob/main/apps/web/src/app/api/merchant-stage/route.ts"
click node_stage_service "https://github.com/abdulrahmnh/revora/blob/main/packages/core/src/merchant-stage/merchant-stage-service.ts"
click node_cart_ingest "https://github.com/abdulrahmnh/revora/blob/main/packages/core/src/integrations/salla/abandoned-cart-ingestion-service.ts"
click node_cart_engine "https://github.com/abdulrahmnh/revora/blob/main/packages/core/src/opportunities/abandoned-cart-recovery-engine.ts"
click node_lost_engine "https://github.com/abdulrahmnh/revora/blob/main/packages/core/src/opportunities/lost-customer-recovery-engine.ts"
click node_second_engine "https://github.com/abdulrahmnh/revora/blob/main/packages/core/src/opportunities/second-purchase-engine.ts"
click node_feed_api "https://github.com/abdulrahmnh/revora/blob/main/apps/web/src/app/api/opportunities/route.ts"
click node_feed "https://github.com/abdulrahmnh/revora/blob/main/packages/core/src/opportunities/opportunity-feed.ts"
click node_decision_api "https://github.com/abdulrahmnh/revora/blob/main/apps/web/src/app/api/opportunities/%5BopportunityId%5D/actions/route.ts"
click node_decision_loop "https://github.com/abdulrahmnh/revora/blob/main/packages/core/src/opportunities/merchant-decision-loop.ts"
click node_whatsapp "https://github.com/abdulrahmnh/revora/blob/main/packages/core/src/opportunities/whatsapp-action.ts"
click node_measurement "https://github.com/abdulrahmnh/revora/blob/main/packages/core/src/observation/factual-outcome-observation.ts"
click node_attribution "https://github.com/abdulrahmnh/revora/blob/main/packages/core/src/opportunities/opportunity-attribution-receipts.ts"
click node_reporting "https://github.com/abdulrahmnh/revora/blob/main/packages/core/src/analytics/impact-ledger-service.ts"
click node_notifications_api "https://github.com/abdulrahmnh/revora/blob/main/apps/web/src/app/api/notifications/route.ts"
click node_notifications "https://github.com/abdulrahmnh/revora/blob/main/packages/core/src/notifications/notification-service.ts"
click node_database "https://github.com/abdulrahmnh/revora/blob/main/packages/core/src/database/client.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_embedded,node_session_api toneBlue
class node_session_auth,node_salla_integration,node_readiness_api,node_readiness,node_stage_api,node_stage_service,node_cart_ingest toneAmber
class node_cart_engine,node_lost_engine,node_second_engine,node_feed_api,node_feed,node_decision_api,node_decision_loop,node_whatsapp toneMint
class node_worker,node_measurement,node_attribution,node_reporting,node_notifications_api,node_notifications,node_database toneRose
class node_merchant,node_salla toneIndigo
```

## Components

### Merchant experience

- [Embedded app](https://github.com/abdulrahmnh/revora/blob/main/apps/web/src/app/app/embedded/salla/page.tsx): `apps/web/src/app/app/embedded/salla/page.tsx`
- [Session API](https://github.com/abdulrahmnh/revora/blob/main/apps/web/src/app/api/session/salla-embedded/route.ts): `apps/web/src/app/api/session/salla-embedded/route.ts`

### Store foundation

- [Embedded session](https://github.com/abdulrahmnh/revora/blob/main/packages/core/src/auth/salla-embedded-session.ts): `packages/core/src/auth/salla-embedded-session.ts`
- [Salla integration](https://github.com/abdulrahmnh/revora/blob/main/packages/core/src/integrations/salla/sync-service.ts): `packages/core/src/integrations/salla/sync-service.ts`
- [Readiness API](https://github.com/abdulrahmnh/revora/blob/main/apps/web/src/app/api/readiness/route.ts): `apps/web/src/app/api/readiness/route.ts`
- [Data readiness](https://github.com/abdulrahmnh/revora/blob/main/packages/core/src/readiness/data-readiness-service.ts): `packages/core/src/readiness/data-readiness-service.ts`
- [Merchant stage API](https://github.com/abdulrahmnh/revora/blob/main/apps/web/src/app/api/merchant-stage/route.ts): `apps/web/src/app/api/merchant-stage/route.ts`
- [Merchant stage](https://github.com/abdulrahmnh/revora/blob/main/packages/core/src/merchant-stage/merchant-stage-service.ts): `packages/core/src/merchant-stage/merchant-stage-service.ts`
- [Cart ingestion](https://github.com/abdulrahmnh/revora/blob/main/packages/core/src/integrations/salla/abandoned-cart-ingestion-service.ts): `packages/core/src/integrations/salla/abandoned-cart-ingestion-service.ts`

### Opportunity lifecycle

- [Cart recovery engine](https://github.com/abdulrahmnh/revora/blob/main/packages/core/src/opportunities/abandoned-cart-recovery-engine.ts): `packages/core/src/opportunities/abandoned-cart-recovery-engine.ts`
- [Lost customer engine](https://github.com/abdulrahmnh/revora/blob/main/packages/core/src/opportunities/lost-customer-recovery-engine.ts): `packages/core/src/opportunities/lost-customer-recovery-engine.ts`
- [Second purchase engine](https://github.com/abdulrahmnh/revora/blob/main/packages/core/src/opportunities/second-purchase-engine.ts): `packages/core/src/opportunities/second-purchase-engine.ts`
- [Opportunity feed API](https://github.com/abdulrahmnh/revora/blob/main/apps/web/src/app/api/opportunities/route.ts): `apps/web/src/app/api/opportunities/route.ts`
- [Prioritized feed](https://github.com/abdulrahmnh/revora/blob/main/packages/core/src/opportunities/opportunity-feed.ts): `packages/core/src/opportunities/opportunity-feed.ts`
- [Opportunity actions](https://github.com/abdulrahmnh/revora/blob/main/apps/web/src/app/api/opportunities/%5BopportunityId%5D/actions/route.ts): `apps/web/src/app/api/opportunities/[opportunityId]/actions/route.ts`
- [Decision and action](https://github.com/abdulrahmnh/revora/blob/main/packages/core/src/opportunities/merchant-decision-loop.ts): `packages/core/src/opportunities/merchant-decision-loop.ts`
- [WhatsApp handoff](https://github.com/abdulrahmnh/revora/blob/main/packages/core/src/opportunities/whatsapp-action.ts): `packages/core/src/opportunities/whatsapp-action.ts`

### Measurement and operations

- [Background worker](https://github.com/abdulrahmnh/revora/blob/main/apps/worker/src/index.ts): `apps/worker/src/index.ts`
- [Outcome observation](https://github.com/abdulrahmnh/revora/blob/main/packages/core/src/observation/factual-outcome-observation.ts): `packages/core/src/observation/factual-outcome-observation.ts`
- [Attribution receipts](https://github.com/abdulrahmnh/revora/blob/main/packages/core/src/opportunities/opportunity-attribution-receipts.ts): `packages/core/src/opportunities/opportunity-attribution-receipts.ts`
- [Value and insights](https://github.com/abdulrahmnh/revora/blob/main/packages/core/src/analytics/impact-ledger-service.ts): `packages/core/src/analytics/impact-ledger-service.ts`
- [Notifications API](https://github.com/abdulrahmnh/revora/blob/main/apps/web/src/app/api/notifications/route.ts): `apps/web/src/app/api/notifications/route.ts`
- [Notification service](https://github.com/abdulrahmnh/revora/blob/main/packages/core/src/notifications/notification-service.ts): `packages/core/src/notifications/notification-service.ts`
- [PostgreSQL access](https://github.com/abdulrahmnh/revora/blob/main/packages/core/src/database/client.ts): `packages/core/src/database/client.ts`

### Other components

- **Merchant**
- **Salla**

## Connections

- Merchant → Embedded app: opens
- Embedded app → Session API: requests session
- Session API → Embedded session: creates session
- Salla → Session API: provides token
- Salla → Salla integration: provides store data
- Background worker → Salla integration: runs sync
- Salla integration → PostgreSQL access: stores synced data
- Readiness API → Data readiness: assesses
- Data readiness → PostgreSQL access: reads store data
- Merchant stage API → Merchant stage: gets stage
- Merchant stage → PostgreSQL access: reads store state
- Salla integration → Cart ingestion: ingests carts
- Cart ingestion → PostgreSQL access: upserts carts
- Cart recovery engine → PostgreSQL access: reads and saves
- Lost customer engine → PostgreSQL access: reads and saves
- Second purchase engine → PostgreSQL access: reads and saves
- Opportunity feed API → Prioritized feed: loads feed
- Prioritized feed → PostgreSQL access: reads opportunities
- Embedded app → Opportunity feed API: requests opportunities
- Merchant → Opportunity actions: submits decision
- Opportunity actions → Decision and action: records action
- Decision and action → PostgreSQL access: persists action
- Decision and action → WhatsApp handoff: creates handoff
- Merchant → WhatsApp handoff: confirms execution
- Outcome observation → PostgreSQL access: records observations
- Attribution receipts → PostgreSQL access: records receipts
- Value and insights → PostgreSQL access: reads outcomes
- Notifications API → Notification service: reconciles and loads
- Notification service → PostgreSQL access: reads and writes intents