# mohammedalhashmi182-collab/al-narjs-ai architecture

> Architecture diagram of the GitHub repository mohammedalhashmi182-collab/al-narjs-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mohammedalhashmi182-collab/al-narjs-ai
- Repository: https://github.com/mohammedalhashmi182-collab/al-narjs-ai

## Overview

Al-Narjis AI is an Arabic-first AI-agent platform with a public site, customer portal, agent services, and card checkout. The main user journey is discovering a plan or agent, using the portal to engage the platform, and paying for a plan; owners also manage leads and run workflow, schedule, and queue automation. The map preserves documented voice, document-generation, knowledge retrieval, and integration capabilities. Some connections rely on README descriptions or source-index references; unsampled implementation details are not asserted.

Main entry points: [`src/main.py`](https://github.com/mohammedalhashmi182-collab/al-narjs-ai/blob/main/src/main.py) (Application and public site), [`src/automation/workflow_engine.py`](https://github.com/mohammedalhashmi182-collab/al-narjs-ai/blob/main/src/automation/workflow_engine.py) (Workflow engine), [`src/db/session.py`](https://github.com/mohammedalhashmi182-collab/al-narjs-ai/blob/main/src/db/session.py) (Application database), [`src/interfaces/sales_routes.py`](https://github.com/mohammedalhashmi182-collab/al-narjs-ai/blob/main/src/interfaces/sales_routes.py) (Sales dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_app["Application and public site<br/>[main.py]"]
  node_portal["Customer portal<br/>[portal_routes.py]"]
  node_agent_pages["Agent pages<br/>[agent_pages.py]"]
end

subgraph group_agents["Agent platform"]
  node_catalog["Plans and agent roster<br/>[catalog.py]"]
  node_agent_registry["Agent registry<br/>[agent_registry.py]"]
  node_model_provider["Model provider<br/>[model_provider.py]"]
  node_prompt_engine["Prompt engine<br/>[prompt_engine.py]"]
  node_rag["Knowledge retrieval<br/>[rag.py]"]
  node_voice["Voice advisor<br/>[voice_live.py]"]
end

subgraph group_automation["Automation and sales"]
  node_workflow["Workflow engine<br/>[workflow_engine.py]"]
  node_scheduler["Schedule service<br/>[scheduler.py]"]
  node_queue["Queue worker<br/>[queue_worker.py]"]
  node_ceo["AI CEO<br/>[ceo_engine.py]"]
  node_sales["Sales dashboard<br/>[sales_routes.py]"]
  node_lead_pipeline["Lead pipeline<br/>[lead_pipeline.py]"]
end

subgraph group_commerce["Commerce and integrations"]
  node_payments["Payments<br/>[payments.py]"]
  node_store_integrations["Store integrations<br/>[routes.py]"]
  node_docgen["Document generation<br/>[pipeline.py]"]
end

subgraph group_foundation["Data and knowledge"]
  node_database[("Application database<br/>[session.py]")]
  node_models["Domain models<br/>[__init__.py]"]
end

node_visitor(("Visitor / customer"))
node_owner(("Platform owner"))

node_visitor -->|"browses site"| node_app
node_visitor -->|"uses portal"| node_portal
node_owner -->|"manages leads"| node_sales
node_app -->|"reads plans"| node_catalog
node_app -->|"uses registry"| node_agent_registry
node_agent_pages -->|"reads roster"| node_catalog
node_workflow -->|"gets agents"| node_agent_registry
node_workflow -->|"renders prompts"| node_prompt_engine
node_workflow -->|"requests completion"| node_model_provider
node_workflow -.->|"runs via queue"| node_queue
node_app -->|"exposes workflows"| node_workflow
node_app -->|"starts scheduler"| node_scheduler
node_app -->|"starts worker"| node_queue
node_app -->|"exposes AI CEO"| node_ceo
node_ceo -->|"records decisions"| node_database
node_sales -->|"manages pipeline"| node_lead_pipeline
node_lead_pipeline -->|"creates payment"| node_payments
node_payments -->|"checks plan"| node_catalog
node_visitor -->|"checks out"| node_payments
node_portal -->|"reads customer data"| node_database
node_sales -->|"queries leads"| node_database
node_database -->|"maps entities"| node_models
node_app -->|"offers voice advisor"| node_voice
node_app -.->|"offers knowledge retrieval"| node_rag
node_app -.->|"offers document packs"| node_docgen
node_app -->|"mounts integration routes"| node_store_integrations
node_store_integrations -.->|"persists integration state"| node_database

click node_app "https://github.com/mohammedalhashmi182-collab/al-narjs-ai/blob/main/src/main.py"
click node_portal "https://github.com/mohammedalhashmi182-collab/al-narjs-ai/blob/main/src/interfaces/portal_routes.py"
click node_agent_pages "https://github.com/mohammedalhashmi182-collab/al-narjs-ai/blob/main/src/services/agent_pages.py"
click node_catalog "https://github.com/mohammedalhashmi182-collab/al-narjs-ai/blob/main/src/services/catalog.py"
click node_agent_registry "https://github.com/mohammedalhashmi182-collab/al-narjs-ai/blob/main/src/core/agent_registry.py"
click node_model_provider "https://github.com/mohammedalhashmi182-collab/al-narjs-ai/blob/main/src/core/model_provider.py"
click node_prompt_engine "https://github.com/mohammedalhashmi182-collab/al-narjs-ai/blob/main/src/core/prompt_engine.py"
click node_rag "https://github.com/mohammedalhashmi182-collab/al-narjs-ai/blob/main/src/ai/rag.py"
click node_voice "https://github.com/mohammedalhashmi182-collab/al-narjs-ai/blob/main/src/services/voice_live.py"
click node_workflow "https://github.com/mohammedalhashmi182-collab/al-narjs-ai/blob/main/src/automation/workflow_engine.py"
click node_scheduler "https://github.com/mohammedalhashmi182-collab/al-narjs-ai/blob/main/src/automation/scheduler.py"
click node_queue "https://github.com/mohammedalhashmi182-collab/al-narjs-ai/blob/main/src/automation/queue_worker.py"
click node_ceo "https://github.com/mohammedalhashmi182-collab/al-narjs-ai/blob/main/src/automation/ceo_engine.py"
click node_sales "https://github.com/mohammedalhashmi182-collab/al-narjs-ai/blob/main/src/interfaces/sales_routes.py"
click node_lead_pipeline "https://github.com/mohammedalhashmi182-collab/al-narjs-ai/blob/main/src/services/lead_pipeline.py"
click node_payments "https://github.com/mohammedalhashmi182-collab/al-narjs-ai/blob/main/src/services/payments.py"
click node_store_integrations "https://github.com/mohammedalhashmi182-collab/al-narjs-ai/blob/main/src/integrations/routes.py"
click node_docgen "https://github.com/mohammedalhashmi182-collab/al-narjs-ai/blob/main/src/services/docgen/pipeline.py"
click node_database "https://github.com/mohammedalhashmi182-collab/al-narjs-ai/blob/main/src/db/session.py"
click node_models "https://github.com/mohammedalhashmi182-collab/al-narjs-ai/blob/main/src/models/__init__.py"

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_app,node_portal,node_agent_pages toneBlue
class node_catalog,node_agent_registry,node_model_provider,node_prompt_engine,node_rag,node_voice toneAmber
class node_workflow,node_scheduler,node_queue,node_ceo,node_sales,node_lead_pipeline toneMint
class node_payments,node_store_integrations,node_docgen toneRose
class node_database,node_models,node_visitor,node_owner toneIndigo
```

## Components

### User experience

- [Application and public site](https://github.com/mohammedalhashmi182-collab/al-narjs-ai/blob/main/src/main.py): `src/main.py`
- [Customer portal](https://github.com/mohammedalhashmi182-collab/al-narjs-ai/blob/main/src/interfaces/portal_routes.py): `src/interfaces/portal_routes.py`
- [Agent pages](https://github.com/mohammedalhashmi182-collab/al-narjs-ai/blob/main/src/services/agent_pages.py): `src/services/agent_pages.py`

### Agent platform

- [Plans and agent roster](https://github.com/mohammedalhashmi182-collab/al-narjs-ai/blob/main/src/services/catalog.py): `src/services/catalog.py`
- [Agent registry](https://github.com/mohammedalhashmi182-collab/al-narjs-ai/blob/main/src/core/agent_registry.py): `src/core/agent_registry.py`
- [Model provider](https://github.com/mohammedalhashmi182-collab/al-narjs-ai/blob/main/src/core/model_provider.py): `src/core/model_provider.py`
- [Prompt engine](https://github.com/mohammedalhashmi182-collab/al-narjs-ai/blob/main/src/core/prompt_engine.py): `src/core/prompt_engine.py`
- [Knowledge retrieval](https://github.com/mohammedalhashmi182-collab/al-narjs-ai/blob/main/src/ai/rag.py): `src/ai/rag.py`
- [Voice advisor](https://github.com/mohammedalhashmi182-collab/al-narjs-ai/blob/main/src/services/voice_live.py): `src/services/voice_live.py`

### Automation and sales

- [Workflow engine](https://github.com/mohammedalhashmi182-collab/al-narjs-ai/blob/main/src/automation/workflow_engine.py): `src/automation/workflow_engine.py`
- [Schedule service](https://github.com/mohammedalhashmi182-collab/al-narjs-ai/blob/main/src/automation/scheduler.py): `src/automation/scheduler.py`
- [Queue worker](https://github.com/mohammedalhashmi182-collab/al-narjs-ai/blob/main/src/automation/queue_worker.py): `src/automation/queue_worker.py`
- [AI CEO](https://github.com/mohammedalhashmi182-collab/al-narjs-ai/blob/main/src/automation/ceo_engine.py): `src/automation/ceo_engine.py`
- [Sales dashboard](https://github.com/mohammedalhashmi182-collab/al-narjs-ai/blob/main/src/interfaces/sales_routes.py): `src/interfaces/sales_routes.py`
- [Lead pipeline](https://github.com/mohammedalhashmi182-collab/al-narjs-ai/blob/main/src/services/lead_pipeline.py): `src/services/lead_pipeline.py`

### Commerce and integrations

- [Payments](https://github.com/mohammedalhashmi182-collab/al-narjs-ai/blob/main/src/services/payments.py): `src/services/payments.py`
- [Store integrations](https://github.com/mohammedalhashmi182-collab/al-narjs-ai/blob/main/src/integrations/routes.py): `src/integrations/routes.py`
- [Document generation](https://github.com/mohammedalhashmi182-collab/al-narjs-ai/blob/main/src/services/docgen/pipeline.py): `src/services/docgen/pipeline.py`

### Data and knowledge

- [Application database](https://github.com/mohammedalhashmi182-collab/al-narjs-ai/blob/main/src/db/session.py): `src/db/session.py`
- [Domain models](https://github.com/mohammedalhashmi182-collab/al-narjs-ai/blob/main/src/models/__init__.py): `src/models/__init__.py`

### Other components

- **Visitor / customer**
- **Platform owner**

## Connections

- Visitor / customer → Application and public site: browses site (evidence: `README.md`)
- Visitor / customer → Customer portal: uses portal (evidence: `README.md`)
- Platform owner → Sales dashboard: manages leads (evidence: `src/interfaces/sales_routes.py`)
- Application and public site → Plans and agent roster: reads plans (evidence: `src/main.py`)
- Application and public site → Agent registry: uses registry (evidence: `src/main.py`)
- Agent pages → Plans and agent roster: reads roster
- Workflow engine → Agent registry: gets agents (evidence: `src/automation/workflow_engine.py`)
- Workflow engine → Prompt engine: renders prompts (evidence: `src/automation/workflow_engine.py`)
- Workflow engine → Model provider: requests completion (evidence: `src/automation/workflow_engine.py`)
- Workflow engine → Queue worker: runs via queue
- Application and public site → Workflow engine: exposes workflows (evidence: `src/main.py`)
- Application and public site → Schedule service: starts scheduler (evidence: `src/main.py`)
- Application and public site → Queue worker: starts worker (evidence: `src/main.py`)
- Application and public site → AI CEO: exposes AI CEO (evidence: `src/main.py`)
- AI CEO → Application database: records decisions (evidence: `src/automation/ceo_engine.py`)
- Sales dashboard → Lead pipeline: manages pipeline (evidence: `src/services/lead_pipeline.py`)
- Lead pipeline → Payments: creates payment (evidence: `src/services/lead_pipeline.py`)
- Payments → Plans and agent roster: checks plan (evidence: `src/services/payments.py`)
- Visitor / customer → Payments: checks out (evidence: `README.md`)
- Customer portal → Application database: reads customer data (evidence: `src/interfaces/portal_routes.py`)
- Sales dashboard → Application database: queries leads (evidence: `src/interfaces/sales_routes.py`)
- Application database → Domain models: maps entities (evidence: `src/db/session.py`)
- Application and public site → Voice advisor: offers voice advisor (evidence: `README.md`)
- Application and public site → Knowledge retrieval: offers knowledge retrieval (evidence: `src/main.py`)
- Application and public site → Document generation: offers document packs
- Application and public site → Store integrations: mounts integration routes (evidence: `src/integrations/routes.py`)
- Store integrations → Application database: persists integration state
