# i-maged/egyptian-legislation-rag architecture

> Architecture diagram of the GitHub repository i-maged/egyptian-legislation-rag, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/i-maged/egyptian-legislation-rag
- Repository: https://github.com/i-maged/egyptian-legislation-rag

## Overview

Egyptian Legislation RAG is an Arabic legal-question-answering application backed by a searchable corpus of Egyptian laws. Users sign in, submit a question, and receive an answer with citations; chat requests retrieve legal chunks, pass them to generation, and persist the exchange. The repository also includes law administration, conversation history and feedback, corpus parsing/canonicalization and embedding, and evaluation. Several subsystem paths come from the file tree and SOURCE INDEX rather than inspected excerpts, so only documented or indexed relationships are connected.

Main entry points: [`apps/web/app/api/chat/route.ts`](https://github.com/i-maged/egyptian-legislation-rag/blob/main/apps/web/app/api/chat/route.ts) (Chat endpoint), [`packages/rag/src/service.ts`](https://github.com/i-maged/egyptian-legislation-rag/blob/main/packages/rag/src/service.ts) (RAG service), [`packages/db/src/client.ts`](https://github.com/i-maged/egyptian-legislation-rag/blob/main/packages/db/src/client.ts) (Database client), [`packages/rag/src/retriever.ts`](https://github.com/i-maged/egyptian-legislation-rag/blob/main/packages/rag/src/retriever.ts) (RAG retriever)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_chat_ui["Chat interface<br/>[chat.tsx]"]
  node_chat_api["Chat endpoint<br/>[route.ts]"]
  node_auth["Authentication"]
  node_conversation_api["Conversation API"]
  node_feedback_api["Message feedback<br/>[route.ts]"]
  node_admin["Law administration"]
end

subgraph group_rag["Answer pipeline"]
  node_rag_service["RAG service<br/>[service.ts]"]
  node_rag_retriever["RAG retriever<br/>[retriever.ts]"]
  node_hybrid["Hybrid retrieval"]
  node_vector["Vector retrieval"]
  node_bm25["BM25 retrieval<br/>[bm25-retriever.ts]"]
  node_db_vector["Database vector search"]
  node_generation["Answer generation<br/>[generate.ts]"]
  node_generation_context["Citation context<br/>[context.ts]"]
end

subgraph group_corpus["Corpus preparation"]
  node_parser["Law document parsing"]
  node_canonical["Corpus canonicalization"]
  node_embedding["Embedding preparation"]
end

subgraph group_storage["Persistence"]
  node_conversation_store[("Conversation storage")]
  node_feedback_store[("Feedback storage")]
  node_law_store[("Law and corpus storage<br/>[law.repository.ts]")]
  node_embedding_store[("Embedding storage")]
  node_db_client["Database client<br/>[client.ts]"]
end

subgraph group_evaluation["Evaluation"]
  node_evaluation["RAG evaluation"]
  node_gold_data["Retrieval gold data"]
end

node_user(("User"))

node_user -->|"asks question"| node_chat_ui
node_chat_ui -->|"submits query"| node_chat_api
node_chat_api -->|"checks identity"| node_auth
node_chat_api -->|"loads and saves"| node_conversation_store
node_chat_api -->|"requests answer"| node_rag_service
node_rag_service -->|"retrieves chunks"| node_rag_retriever
node_rag_service -->|"generates response"| node_generation
node_rag_service -.->|"formats citations"| node_generation_context
node_rag_retriever -.->|"dispatches retrieval"| node_hybrid
node_hybrid -->|"searches vectors"| node_vector
node_hybrid -->|"searches terms"| node_bm25
node_rag_retriever -.->|"supports database search"| node_db_vector
node_conversation_api -->|"checks identity"| node_auth
node_conversation_api -->|"reads conversations"| node_conversation_store
node_feedback_api -->|"checks identity"| node_auth
node_feedback_api -->|"writes feedback"| node_feedback_store
node_admin -->|"manages laws"| node_law_store
node_parser -.->|"supplies parsed laws"| node_canonical
node_canonical -.->|"prepares corpus"| node_embedding
node_embedding -.->|"stores vectors"| node_embedding_store
node_law_store -->|"uses client"| node_db_client
node_embedding_store -->|"writes vectors"| node_db_client
node_conversation_store -.->|"uses client"| node_db_client
node_feedback_store -.->|"uses client"| node_db_client
node_evaluation -.->|"evaluates against"| node_gold_data

click node_chat_ui "https://github.com/i-maged/egyptian-legislation-rag/blob/main/apps/web/app/components/chat.tsx"
click node_chat_api "https://github.com/i-maged/egyptian-legislation-rag/blob/main/apps/web/app/api/chat/route.ts"
click node_auth "https://github.com/i-maged/egyptian-legislation-rag/tree/main/apps/web/lib/auth"
click node_conversation_api "https://github.com/i-maged/egyptian-legislation-rag/tree/main/apps/web/app/api/conversations"
click node_feedback_api "https://github.com/i-maged/egyptian-legislation-rag/blob/main/apps/web/app/api/messages/%5Bid%5D/feedback/route.ts"
click node_admin "https://github.com/i-maged/egyptian-legislation-rag/tree/main/apps/web/app/admin/laws"
click node_rag_service "https://github.com/i-maged/egyptian-legislation-rag/blob/main/packages/rag/src/service.ts"
click node_rag_retriever "https://github.com/i-maged/egyptian-legislation-rag/blob/main/packages/rag/src/retriever.ts"
click node_hybrid "https://github.com/i-maged/egyptian-legislation-rag/blob/main/packages/ingestion/src/retrieval/hybrid-retriever.ts"
click node_vector "https://github.com/i-maged/egyptian-legislation-rag/blob/main/packages/ingestion/src/retrieval/vector-retriever.ts"
click node_bm25 "https://github.com/i-maged/egyptian-legislation-rag/blob/main/packages/ingestion/src/retrieval/bm25-retriever.ts"
click node_db_vector "https://github.com/i-maged/egyptian-legislation-rag/blob/main/packages/ingestion/src/retrieval/db-vector-retriever.ts"
click node_generation "https://github.com/i-maged/egyptian-legislation-rag/blob/main/packages/generation/src/generate.ts"
click node_generation_context "https://github.com/i-maged/egyptian-legislation-rag/blob/main/packages/generation/src/context.ts"
click node_parser "https://github.com/i-maged/egyptian-legislation-rag/tree/main/packages/ingestion/src/parser"
click node_canonical "https://github.com/i-maged/egyptian-legislation-rag/tree/main/packages/ingestion/src/canonical"
click node_embedding "https://github.com/i-maged/egyptian-legislation-rag/tree/main/packages/ingestion/src/embeddings"
click node_conversation_store "https://github.com/i-maged/egyptian-legislation-rag/blob/main/packages/db/src/repositories/conversation.repository.ts"
click node_feedback_store "https://github.com/i-maged/egyptian-legislation-rag/blob/main/packages/db/src/repositories/feedback.repository.ts"
click node_law_store "https://github.com/i-maged/egyptian-legislation-rag/blob/main/packages/db/src/repositories/law.repository.ts"
click node_embedding_store "https://github.com/i-maged/egyptian-legislation-rag/blob/main/packages/db/src/repositories/embedding.repository.ts"
click node_db_client "https://github.com/i-maged/egyptian-legislation-rag/blob/main/packages/db/src/client.ts"
click node_evaluation "https://github.com/i-maged/egyptian-legislation-rag/tree/main/packages/evaluation/src"
click node_gold_data "https://github.com/i-maged/egyptian-legislation-rag/blob/main/packages/evaluation/src/datasets/retrieval-dataset.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_chat_ui,node_chat_api,node_auth,node_conversation_api,node_feedback_api,node_admin,node_user toneBlue
class node_rag_service,node_rag_retriever,node_hybrid,node_vector,node_bm25,node_db_vector,node_generation,node_generation_context toneAmber
class node_parser,node_canonical,node_embedding toneMint
class node_conversation_store,node_feedback_store,node_law_store,node_embedding_store,node_db_client toneRose
class node_evaluation,node_gold_data toneIndigo
```

## Components

### Web application

- [Chat interface](https://github.com/i-maged/egyptian-legislation-rag/blob/main/apps/web/app/components/chat.tsx): `apps/web/app/components/chat.tsx`
- [Chat endpoint](https://github.com/i-maged/egyptian-legislation-rag/blob/main/apps/web/app/api/chat/route.ts): `apps/web/app/api/chat/route.ts`
- [Authentication](https://github.com/i-maged/egyptian-legislation-rag/tree/main/apps/web/lib/auth): `apps/web/lib/auth`
- [Conversation API](https://github.com/i-maged/egyptian-legislation-rag/tree/main/apps/web/app/api/conversations): `apps/web/app/api/conversations`
- [Message feedback](https://github.com/i-maged/egyptian-legislation-rag/blob/main/apps/web/app/api/messages/%5Bid%5D/feedback/route.ts): `apps/web/app/api/messages/[id]/feedback/route.ts`
- [Law administration](https://github.com/i-maged/egyptian-legislation-rag/tree/main/apps/web/app/admin/laws): `apps/web/app/admin/laws`

### Answer pipeline

- [RAG service](https://github.com/i-maged/egyptian-legislation-rag/blob/main/packages/rag/src/service.ts): `packages/rag/src/service.ts`
- [RAG retriever](https://github.com/i-maged/egyptian-legislation-rag/blob/main/packages/rag/src/retriever.ts): `packages/rag/src/retriever.ts`
- [Hybrid retrieval](https://github.com/i-maged/egyptian-legislation-rag/blob/main/packages/ingestion/src/retrieval/hybrid-retriever.ts): `packages/ingestion/src/retrieval/hybrid-retriever.ts`
- [Vector retrieval](https://github.com/i-maged/egyptian-legislation-rag/blob/main/packages/ingestion/src/retrieval/vector-retriever.ts): `packages/ingestion/src/retrieval/vector-retriever.ts`
- [BM25 retrieval](https://github.com/i-maged/egyptian-legislation-rag/blob/main/packages/ingestion/src/retrieval/bm25-retriever.ts): `packages/ingestion/src/retrieval/bm25-retriever.ts`
- [Database vector search](https://github.com/i-maged/egyptian-legislation-rag/blob/main/packages/ingestion/src/retrieval/db-vector-retriever.ts): `packages/ingestion/src/retrieval/db-vector-retriever.ts`
- [Answer generation](https://github.com/i-maged/egyptian-legislation-rag/blob/main/packages/generation/src/generate.ts): `packages/generation/src/generate.ts`
- [Citation context](https://github.com/i-maged/egyptian-legislation-rag/blob/main/packages/generation/src/context.ts): `packages/generation/src/context.ts`

### Corpus preparation

- [Law document parsing](https://github.com/i-maged/egyptian-legislation-rag/tree/main/packages/ingestion/src/parser): `packages/ingestion/src/parser`
- [Corpus canonicalization](https://github.com/i-maged/egyptian-legislation-rag/tree/main/packages/ingestion/src/canonical): `packages/ingestion/src/canonical`
- [Embedding preparation](https://github.com/i-maged/egyptian-legislation-rag/tree/main/packages/ingestion/src/embeddings): `packages/ingestion/src/embeddings`

### Persistence

- [Conversation storage](https://github.com/i-maged/egyptian-legislation-rag/blob/main/packages/db/src/repositories/conversation.repository.ts): `packages/db/src/repositories/conversation.repository.ts`
- [Feedback storage](https://github.com/i-maged/egyptian-legislation-rag/blob/main/packages/db/src/repositories/feedback.repository.ts): `packages/db/src/repositories/feedback.repository.ts`
- [Law and corpus storage](https://github.com/i-maged/egyptian-legislation-rag/blob/main/packages/db/src/repositories/law.repository.ts): `packages/db/src/repositories/law.repository.ts`
- [Embedding storage](https://github.com/i-maged/egyptian-legislation-rag/blob/main/packages/db/src/repositories/embedding.repository.ts): `packages/db/src/repositories/embedding.repository.ts`
- [Database client](https://github.com/i-maged/egyptian-legislation-rag/blob/main/packages/db/src/client.ts): `packages/db/src/client.ts`

### Evaluation

- [RAG evaluation](https://github.com/i-maged/egyptian-legislation-rag/tree/main/packages/evaluation/src): `packages/evaluation/src`
- [Retrieval gold data](https://github.com/i-maged/egyptian-legislation-rag/blob/main/packages/evaluation/src/datasets/retrieval-dataset.ts): `packages/evaluation/src/datasets/retrieval-dataset.ts`

### Other components

- **User**

## Connections

- User → Chat interface: asks question
- Chat interface → Chat endpoint: submits query (evidence: `apps/web/app/api/chat/route.ts`)
- Chat endpoint → Authentication: checks identity (evidence: `apps/web/app/api/chat/route.ts`)
- Chat endpoint → Conversation storage: loads and saves (evidence: `apps/web/app/api/chat/route.ts`)
- Chat endpoint → RAG service: requests answer (evidence: `apps/web/app/api/chat/route.ts`)
- RAG service → RAG retriever: retrieves chunks (evidence: `packages/rag/src/service.ts`)
- RAG service → Answer generation: generates response (evidence: `packages/rag/src/service.ts`)
- RAG service → Citation context: formats citations
- RAG retriever → Hybrid retrieval: dispatches retrieval
- Hybrid retrieval → Vector retrieval: searches vectors (evidence: `packages/ingestion/src/retrieval/hybrid-retriever.ts`)
- Hybrid retrieval → BM25 retrieval: searches terms (evidence: `packages/ingestion/src/retrieval/hybrid-retriever.ts`)
- RAG retriever → Database vector search: supports database search
- Conversation API → Authentication: checks identity (evidence: `apps/web/app/api/conversations/route.ts`)
- Conversation API → Conversation storage: reads conversations (evidence: `apps/web/app/api/conversations/route.ts`)
- Message feedback → Authentication: checks identity (evidence: `apps/web/app/api/messages/[id]/feedback/route.ts`)
- Message feedback → Feedback storage: writes feedback (evidence: `apps/web/app/api/messages/[id]/feedback/route.ts`)
- Law administration → Law and corpus storage: manages laws (evidence: `apps/web/app/admin/laws/page.tsx`)
- Law document parsing → Corpus canonicalization: supplies parsed laws
- Corpus canonicalization → Embedding preparation: prepares corpus
- Embedding preparation → Embedding storage: stores vectors
- Law and corpus storage → Database client: uses client (evidence: `packages/db/src/repositories/law.repository.ts`)
- Embedding storage → Database client: writes vectors (evidence: `packages/db/src/repositories/embedding.repository.ts`)
- Conversation storage → Database client: uses client
- Feedback storage → Database client: uses client
- RAG evaluation → Retrieval gold data: evaluates against (evidence: `packages/evaluation/src/retrieval/retrieval-evaluator.ts`)
