# omaridop/tamweel_ai_expo architecture

> Architecture diagram of the GitHub repository omaridop/tamweel_ai_expo, 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/omaridop/tamweel_ai_expo
- Repository: https://github.com/omaridop/tamweel_ai_expo

## Overview

Tamweel is a full-stack credit-decision platform: applicants use the web portal to request assessments, the backend produces a model score and applies business rules, and an LLM provides a text-only explanation. Separate product branches support financial dashboards, authenticated access, and a bilingual policy-grounded chat assistant with sponsor policy uploads. The README documents portfolio analytics, simulation, disputes, and audit governance; tree paths identify these capabilities, but their detailed wiring is not shown in the sampled source.

Main entry points: [`backend/app/main.py`](https://github.com/omaridop/tamweel_ai_expo/blob/main/backend/app/main.py) (FastAPI App), [`backend/app/routes/chat.py`](https://github.com/omaridop/tamweel_ai_expo/blob/main/backend/app/routes/chat.py) (Chat Routes), [`frontend/src/routes/AppRoutes.jsx`](https://github.com/omaridop/tamweel_ai_expo/blob/main/frontend/src/routes/AppRoutes.jsx) (Portal Routes), [`backend/app/ml/hybrid_engine.py`](https://github.com/omaridop/tamweel_ai_expo/blob/main/backend/app/ml/hybrid_engine.py) (Hybrid Score Engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_portal["User and Sponsor Portal"]
  node_web["Web App<br/>[App.jsx]"]
  node_routes_ui["Portal Routes<br/>[AppRoutes.jsx]"]
  node_dashboard["User Dashboard<br/>[UserDashboard.jsx]"]
  node_score_sim["Score Simulator<br/>[ScoreSimulator.jsx]"]
  node_sponsor_dash["Sponsor Dashboard"]
  node_disputes["Dispute Resolution"]
end

subgraph group_access["Identity and API"]
  node_api["FastAPI App<br/>[main.py]"]
  node_auth_routes["Authentication Routes<br/>[auth.py]"]
end

subgraph group_decision["Credit Decisioning"]
  node_score_routes["Scoring Routes<br/>[score.py]"]
  node_engine["Hybrid Score Engine<br/>[hybrid_engine.py]"]
  node_explanation["Score Explanation<br/>[rag_engine.py]"]
  node_audit_store[("Decision and Audit Records")]
end

subgraph group_intelligence["Financial Intelligence"]
  node_financial["Financial Intelligence"]
  node_user_routes["User Routes<br/>[users.py]"]
end

subgraph group_knowledge["Policy Assistant"]
  node_chat_widget["RAG Chat Widget<br/>[RAGChatWidget.tsx]"]
  node_chat_routes["Chat Routes<br/>[chat.py]"]
  node_query_rewriter["Query Rewriter<br/>[query_rewriter.py]"]
  node_chat_context["Chat Context Services"]
  node_policy_store[("Policy Chunk Store")]
  node_ingester["Policy Ingestion"]
  node_upload_routes["Admin Upload Routes<br/>[admin.py]"]
end

node_applicant(("Applicant"))
node_sponsor(("Sponsor / Admin"))
node_llm{{"LLM Provider"}}
node_supabase[("Supabase")]

node_applicant -->|"uses portal"| node_web
node_sponsor -->|"uses portal"| node_web
node_web -->|"renders routes"| node_routes_ui
node_routes_ui -->|"routes to"| node_dashboard
node_routes_ui -->|"routes to"| node_score_sim
node_routes_ui -->|"routes to"| node_disputes
node_routes_ui -->|"routes to"| node_sponsor_dash
node_web -->|"API requests"| node_api
node_api -->|"registers router"| node_auth_routes
node_api -->|"registers router"| node_score_routes
node_api -->|"registers router"| node_user_routes
node_api -->|"registers router"| node_chat_routes
node_api -->|"registers router"| node_upload_routes
node_score_routes -->|"assessment call"| node_engine
node_engine -->|"requests narrative"| node_explanation
node_explanation -->|"generates explanation"| node_llm
node_engine -->|"writes decisions"| node_audit_store
node_engine -->|"persists records"| node_supabase
node_dashboard -->|"requests profile"| node_user_routes
node_user_routes -->|"gets insights"| node_financial
node_chat_widget -->|"sends turns"| node_chat_routes
node_chat_routes -->|"rewrites follow-ups"| node_query_rewriter
node_chat_routes -->|"assembles context"| node_chat_context
node_chat_routes -->|"hybrid search"| node_policy_store
node_chat_routes -->|"generates answer"| node_llm
node_upload_routes -->|"starts ingestion"| node_ingester
node_ingester -->|"embeds and stores"| node_policy_store
node_ingester -->|"generates retrieval text"| node_llm

click node_web "https://github.com/omaridop/tamweel_ai_expo/blob/main/frontend/src/App.jsx"
click node_routes_ui "https://github.com/omaridop/tamweel_ai_expo/blob/main/frontend/src/routes/AppRoutes.jsx"
click node_dashboard "https://github.com/omaridop/tamweel_ai_expo/blob/main/frontend/src/features/dashboard/UserDashboard.jsx"
click node_score_sim "https://github.com/omaridop/tamweel_ai_expo/blob/main/frontend/src/features/dashboard/ScoreSimulator.jsx"
click node_sponsor_dash "https://github.com/omaridop/tamweel_ai_expo/blob/main/frontend/src/features/dashboard/SponsorDashboard.jsx"
click node_disputes "https://github.com/omaridop/tamweel_ai_expo/blob/main/frontend/src/features/disputes/DisputeResolutionPage.jsx"
click node_api "https://github.com/omaridop/tamweel_ai_expo/blob/main/backend/app/main.py"
click node_auth_routes "https://github.com/omaridop/tamweel_ai_expo/blob/main/backend/app/routes/auth.py"
click node_score_routes "https://github.com/omaridop/tamweel_ai_expo/blob/main/backend/app/routes/score.py"
click node_engine "https://github.com/omaridop/tamweel_ai_expo/blob/main/backend/app/ml/hybrid_engine.py"
click node_explanation "https://github.com/omaridop/tamweel_ai_expo/blob/main/ml_pipeline/rag_engine.py"
click node_financial "https://github.com/omaridop/tamweel_ai_expo/blob/main/backend/app/services/financial_intelligence.py"
click node_user_routes "https://github.com/omaridop/tamweel_ai_expo/blob/main/backend/app/routes/users.py"
click node_chat_widget "https://github.com/omaridop/tamweel_ai_expo/blob/main/frontend/src/components/chat/RAGChatWidget.tsx"
click node_chat_routes "https://github.com/omaridop/tamweel_ai_expo/blob/main/backend/app/routes/chat.py"
click node_query_rewriter "https://github.com/omaridop/tamweel_ai_expo/blob/main/backend/app/pipeline/query_rewriter.py"
click node_chat_context "https://github.com/omaridop/tamweel_ai_expo/blob/main/backend/app/services/context_assembler.py"
click node_ingester "https://github.com/omaridop/tamweel_ai_expo/blob/main/backend/app/knowledge_ingester.py"
click node_upload_routes "https://github.com/omaridop/tamweel_ai_expo/blob/main/backend/app/routes/admin.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_web,node_routes_ui,node_dashboard,node_score_sim,node_sponsor_dash,node_disputes toneBlue
class node_api,node_auth_routes,node_supabase toneAmber
class node_score_routes,node_engine,node_explanation,node_audit_store toneMint
class node_financial,node_user_routes toneRose
class node_chat_widget,node_chat_routes,node_query_rewriter,node_chat_context,node_policy_store,node_ingester,node_upload_routes,node_applicant,node_sponsor,node_llm toneIndigo
```

## Components

### User and Sponsor Portal

- [Web App](https://github.com/omaridop/tamweel_ai_expo/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Portal Routes](https://github.com/omaridop/tamweel_ai_expo/blob/main/frontend/src/routes/AppRoutes.jsx): `frontend/src/routes/AppRoutes.jsx`
- [User Dashboard](https://github.com/omaridop/tamweel_ai_expo/blob/main/frontend/src/features/dashboard/UserDashboard.jsx): `frontend/src/features/dashboard/UserDashboard.jsx`
- [Score Simulator](https://github.com/omaridop/tamweel_ai_expo/blob/main/frontend/src/features/dashboard/ScoreSimulator.jsx): `frontend/src/features/dashboard/ScoreSimulator.jsx`
- [Sponsor Dashboard](https://github.com/omaridop/tamweel_ai_expo/blob/main/frontend/src/features/dashboard/SponsorDashboard.jsx): `frontend/src/features/dashboard/SponsorDashboard.jsx`
- [Dispute Resolution](https://github.com/omaridop/tamweel_ai_expo/blob/main/frontend/src/features/disputes/DisputeResolutionPage.jsx): `frontend/src/features/disputes/DisputeResolutionPage.jsx`

### Identity and API

- [FastAPI App](https://github.com/omaridop/tamweel_ai_expo/blob/main/backend/app/main.py): `backend/app/main.py`
- [Authentication Routes](https://github.com/omaridop/tamweel_ai_expo/blob/main/backend/app/routes/auth.py): `backend/app/routes/auth.py`

### Credit Decisioning

- [Scoring Routes](https://github.com/omaridop/tamweel_ai_expo/blob/main/backend/app/routes/score.py): `backend/app/routes/score.py`
- [Hybrid Score Engine](https://github.com/omaridop/tamweel_ai_expo/blob/main/backend/app/ml/hybrid_engine.py): `backend/app/ml/hybrid_engine.py`
- [Score Explanation](https://github.com/omaridop/tamweel_ai_expo/blob/main/ml_pipeline/rag_engine.py): `ml_pipeline/rag_engine.py`
- **Decision and Audit Records**

### Financial Intelligence

- [Financial Intelligence](https://github.com/omaridop/tamweel_ai_expo/blob/main/backend/app/services/financial_intelligence.py): `backend/app/services/financial_intelligence.py`
- [User Routes](https://github.com/omaridop/tamweel_ai_expo/blob/main/backend/app/routes/users.py): `backend/app/routes/users.py`

### Policy Assistant

- [RAG Chat Widget](https://github.com/omaridop/tamweel_ai_expo/blob/main/frontend/src/components/chat/RAGChatWidget.tsx): `frontend/src/components/chat/RAGChatWidget.tsx`
- [Chat Routes](https://github.com/omaridop/tamweel_ai_expo/blob/main/backend/app/routes/chat.py): `backend/app/routes/chat.py`
- [Query Rewriter](https://github.com/omaridop/tamweel_ai_expo/blob/main/backend/app/pipeline/query_rewriter.py): `backend/app/pipeline/query_rewriter.py`
- [Chat Context Services](https://github.com/omaridop/tamweel_ai_expo/blob/main/backend/app/services/context_assembler.py): `backend/app/services/context_assembler.py`
- **Policy Chunk Store**
- [Policy Ingestion](https://github.com/omaridop/tamweel_ai_expo/blob/main/backend/app/knowledge_ingester.py): `backend/app/knowledge_ingester.py`
- [Admin Upload Routes](https://github.com/omaridop/tamweel_ai_expo/blob/main/backend/app/routes/admin.py): `backend/app/routes/admin.py`

### Other components

- **Applicant**
- **Sponsor / Admin**
- **LLM Provider**
- **Supabase**

## Connections

- Applicant → Web App: uses portal
- Sponsor / Admin → Web App: uses portal
- Web App → Portal Routes: renders routes
- Portal Routes → User Dashboard: routes to
- Portal Routes → Score Simulator: routes to
- Portal Routes → Dispute Resolution: routes to
- Portal Routes → Sponsor Dashboard: routes to
- Web App → FastAPI App: API requests
- FastAPI App → Authentication Routes: registers router
- FastAPI App → Scoring Routes: registers router
- FastAPI App → User Routes: registers router
- FastAPI App → Chat Routes: registers router
- FastAPI App → Admin Upload Routes: registers router
- Scoring Routes → Hybrid Score Engine: assessment call
- Hybrid Score Engine → Score Explanation: requests narrative
- Score Explanation → LLM Provider: generates explanation
- Hybrid Score Engine → Decision and Audit Records: writes decisions
- Hybrid Score Engine → Supabase: persists records
- User Dashboard → User Routes: requests profile
- User Routes → Financial Intelligence: gets insights
- RAG Chat Widget → Chat Routes: sends turns
- Chat Routes → Query Rewriter: rewrites follow-ups
- Chat Routes → Chat Context Services: assembles context
- Chat Routes → Policy Chunk Store: hybrid search
- Chat Routes → LLM Provider: generates answer
- Admin Upload Routes → Policy Ingestion: starts ingestion
- Policy Ingestion → Policy Chunk Store: embeds and stores
- Policy Ingestion → LLM Provider: generates retrieval text