# ahatasham5/islamic-gpt-frontend architecture

> Architecture diagram of the GitHub repository ahatasham5/islamic-gpt-frontend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ahatasham5/islamic-gpt-frontend
- Repository: https://github.com/ahatasham5/islamic-gpt-frontend

## Overview

1. **Overall shape**
   - This repository is a **Next.js frontend** for an “Islamic-Gpt” product.
   - It is organized as a **Pages Router app** (`pages/`) with one important App Router-style API edge: a catch-all backend proxy under `app/api/backend/[...path]/route.ts`.

2. **Main architectural boundary**
   - The frontend does **not appear to talk directly to a backend service from components**.
   - Instead, UI code calls local API helpers in `lib/api/*`, which use the shared HTTP layer in `lib/http.ts`.
   - Those requests are routed through `/api/backend/...`, which acts as a **proxy/adapter boundary** to the real backend API.

3. **Top-level user flows**
   - Public and authenticated entry points are split into route groups:
     - `pages/landing` for the marketing/entry page.
     - `pages/login`, `pages/reset-password`, `pages/accept-invite` for auth lifecycle.
     - `pages/user`, `pages/mufti`, and `pages/admin` for role-specific product areas.
   - `pages/index.tsx` likely serves as the main entry redirect or landing decision point.

4. **Role-based application areas**
   - The repo clearly separates different operational personas:
     - **User** experience: chat and personal usage.
     - **Mufti** workflow: likely content/review or answer-authoring oriented.
     - **Admin** console: user management and feedback review.
   - The corresponding component sets support this split: `chat-*`, `admin-*`, `book-manager`, `create-mufti-panel`, `sources-panel`, etc.

5. **Chat subsystem**
   - The chat experience is decomposed into focused UI pieces:
     - `chat-app.tsx`, `chat-main.tsx`, `chat-sidebar.tsx`
     - `streaming-answer.tsx` for incremental response rendering
     - `thinking-modal.tsx` for model processing state
     - `feedback-dialog.tsx` and `sources-panel.tsx` for post-answer actions and provenance
   - This suggests a conversational UI that supports **streamed model output**, **citation/source display**, and **feedback capture**.

6. **Data access layer**
   - `lib/api/` contains domain-specific clients:
     - `auth.ts`, `users.ts`, `admin.ts`, `chat.ts`, `books.ts`, `sessions.ts`, `health.ts`
   - `hooks/` wraps these API clients into React stateful hooks (`use-auth`, `use-chat`, `use-books`, `use-sessions`, `use-health`), which is the main bridge between UI and server data.

7. **Authentication and session handling**
   - `lib/auth-context.tsx` and `hooks/use-auth.ts` indicate a shared auth state provider.
   - `lib/with-auth.tsx` suggests route/component protection for authenticated pages.
   - Auth validation helpers live in `lib/validation/auth.ts`, and login/reset/invite pages imply a full credential lifecycle with invitations and password recovery.

8. **State and cross-cutting contexts**
   - `lib/language-context.tsx` suggests language/locale selection is managed globally.
   - `lib/types.ts` and `lib/app-types.ts` centralize domain types used across hooks, components, and API clients.
   - `lib/format.tsx` and `lib/utils.ts` provide shared formatting and utility behavior.

9. **Content and knowledge-management features**
   - Several components imply the product is not just chat, but also a **knowledge/source management system**:
     - `book-manager.tsx`
     - `rich-text-editor.tsx`
     - `create-mufti-panel.tsx`
     - `sources-panel.tsx`
   - This points to a workflow where curated books/sources feed into the chat or answer generation experience.

10. **Admin operations**
   - The admin UI is split into panel and page-level components:
     - `admin-users.tsx`, `admin-users-panel.tsx`
     - `admin-feedbacks.tsx`, `admin-feedbacks-panel.tsx`
   - This implies backend-managed moderation or operational tooling for user accounts and received feedback.

11. **UI composition**
   - The UI is built from reusable local primitives under `components/ui/`:
     - dialog, sheet, tabs, tooltip, dropdowns, inputs, textarea, etc.
   - `components.json`, `globals.css`, and the presence of many small UI primitives indicate a **design-system-style component layer** rather than ad hoc styling everywhere.

12. **Runtime and integration points**
   - The app runs in a **Node/Next.js/React/TypeScript** stack.
   - The only explicit server-side integration in this repo is the `/api/backend/[...path]` route, which is the key infrastructure boundary to show in an architecture diagram.
   - The rest of the repository is client-side UI, state, and API orchestration around that backend.

13. **What to show in an architecture diagram**
   - A useful diagram would show:
     - Browser/UI pages → React components
     - Components → hooks
     - Hooks → `lib/api/*` clients → shared HTTP layer
     - HTTP layer → local `/api/backend/...` proxy route
     - Proxy route → external backend services
   - Then add side lanes for **auth/session**, **chat streaming**, **admin panels**, and **book/source management** as feature subsystems.

Main entry points: [`components/chat-main.tsx`](https://github.com/ahatasham5/islamic-gpt-frontend/blob/main/components/chat-main.tsx) (Chat main), [`lib/api/auth.ts`](https://github.com/ahatasham5/islamic-gpt-frontend/blob/main/lib/api/auth.ts) (Auth API), [`lib/http.ts`](https://github.com/ahatasham5/islamic-gpt-frontend/blob/main/lib/http.ts) (HTTP client), [`pages/admin/index.tsx`](https://github.com/ahatasham5/islamic-gpt-frontend/blob/main/pages/admin/index.tsx) (Admin area)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_routes["Routes"]
  node_pages_app["App shell<br/>next app<br/>[_app.tsx]"]
  node_pages_index["Entry<br/>route<br/>[index.tsx]"]
  node_pages_landing["Landing<br/>route<br/>[index.tsx]"]
  node_pages_login["Login<br/>route<br/>[index.tsx]"]
  node_pages_reset["Reset password<br/>route<br/>[index.tsx]"]
  node_pages_invite["Accept invite<br/>route<br/>[index.tsx]"]
  node_pages_user["User area<br/>route<br/>[index.tsx]"]
  node_pages_mufti["Mufti area<br/>route<br/>[index.tsx]"]
  node_pages_admin["Admin area<br/>route<br/>[index.tsx]"]
end

subgraph group_features["Features"]
  node_chat_app["Chat app<br/>feature ui<br/>[chat-app.tsx]"]
  node_chat_main["Chat main<br/>feature ui<br/>[chat-main.tsx]"]
  node_chat_sidebar["Sidebar<br/>feature ui<br/>[chat-sidebar.tsx]"]
  node_streaming_answer["Streaming answer<br/>renderer"]
  node_sources_panel["Sources panel<br/>feature ui<br/>[sources-panel.tsx]"]
  node_admin_users["Admin users<br/>admin ui<br/>[admin-users.tsx]"]
  node_admin_feedbacks["Admin feedbacks<br/>admin ui"]
  node_book_manager["Book manager<br/>knowledge ui<br/>[book-manager.tsx]"]
end

subgraph group_state["State & Data"]
  node_use_auth["Auth hook<br/>react hook<br/>[use-auth.ts]"]
  node_use_chat["Chat hook<br/>react hook<br/>[use-chat.ts]"]
  node_use_books["Books hook<br/>react hook<br/>[use-books.ts]"]
  node_api_auth["Auth API<br/>api client<br/>[auth.ts]"]
  node_api_chat["Chat API<br/>api client<br/>[chat.ts]"]
  node_api_books["Books API<br/>api client<br/>[books.ts]"]
end

subgraph group_core["Core"]
  node_auth_context["Auth context<br/>state provider<br/>[auth-context.tsx]"]
  node_language_context["Language context<br/>state provider"]
  node_with_auth["Auth guard<br/>route guard<br/>[with-auth.tsx]"]
end

subgraph group_backend["Backend Boundary"]
  node_http_client["HTTP client<br/>shared client<br/>[http.ts]"]
  node_backend_proxy["Backend proxy<br/>next api route<br/>[route.ts]"]
  node_external_backend[("Backend services<br/>external api")]
end

node_pages_app -->|"provides"| node_auth_context
node_pages_app -->|"provides"| node_language_context
node_pages_index -->|"routes to"| node_pages_landing
node_pages_login -->|"uses"| node_use_auth
node_pages_reset -->|"uses"| node_api_auth
node_pages_invite -->|"uses"| node_api_auth
node_pages_user -->|"protected by"| node_with_auth
node_pages_user -->|"renders"| node_chat_app
node_pages_mufti -->|"protected by"| node_with_auth
node_pages_mufti -->|"renders"| node_book_manager
node_pages_admin -->|"protected by"| node_with_auth
node_pages_admin -->|"renders"| node_admin_users
node_pages_admin -->|"renders"| node_admin_feedbacks
node_chat_app -->|"composes"| node_chat_main
node_chat_app -->|"composes"| node_chat_sidebar
node_chat_main -->|"uses"| node_use_chat
node_chat_main -->|"renders"| node_streaming_answer
node_chat_main -->|"uses"| node_sources_panel
node_use_auth -->|"calls"| node_api_auth
node_use_chat -->|"calls"| node_api_chat
node_use_books -->|"calls"| node_api_books
node_api_auth -->|"uses"| node_http_client
node_api_chat -->|"uses"| node_http_client
node_api_books -->|"uses"| node_http_client
node_http_client -->|"targets"| node_backend_proxy
node_backend_proxy -->|"forwards to"| node_external_backend

click node_pages_app "https://github.com/ahatasham5/islamic-gpt-frontend/blob/main/pages/_app.tsx"
click node_pages_index "https://github.com/ahatasham5/islamic-gpt-frontend/blob/main/pages/index.tsx"
click node_pages_landing "https://github.com/ahatasham5/islamic-gpt-frontend/blob/main/pages/landing/index.tsx"
click node_pages_login "https://github.com/ahatasham5/islamic-gpt-frontend/blob/main/pages/login/index.tsx"
click node_pages_reset "https://github.com/ahatasham5/islamic-gpt-frontend/blob/main/pages/reset-password/index.tsx"
click node_pages_invite "https://github.com/ahatasham5/islamic-gpt-frontend/blob/main/pages/accept-invite/index.tsx"
click node_pages_user "https://github.com/ahatasham5/islamic-gpt-frontend/blob/main/pages/user/index.tsx"
click node_pages_mufti "https://github.com/ahatasham5/islamic-gpt-frontend/blob/main/pages/mufti/index.tsx"
click node_pages_admin "https://github.com/ahatasham5/islamic-gpt-frontend/blob/main/pages/admin/index.tsx"
click node_chat_app "https://github.com/ahatasham5/islamic-gpt-frontend/blob/main/components/chat-app.tsx"
click node_chat_main "https://github.com/ahatasham5/islamic-gpt-frontend/blob/main/components/chat-main.tsx"
click node_chat_sidebar "https://github.com/ahatasham5/islamic-gpt-frontend/blob/main/components/chat-sidebar.tsx"
click node_streaming_answer "https://github.com/ahatasham5/islamic-gpt-frontend/blob/main/components/streaming-answer.tsx"
click node_sources_panel "https://github.com/ahatasham5/islamic-gpt-frontend/blob/main/components/sources-panel.tsx"
click node_admin_users "https://github.com/ahatasham5/islamic-gpt-frontend/blob/main/components/admin-users.tsx"
click node_admin_feedbacks "https://github.com/ahatasham5/islamic-gpt-frontend/blob/main/components/admin-feedbacks.tsx"
click node_book_manager "https://github.com/ahatasham5/islamic-gpt-frontend/blob/main/components/book-manager.tsx"
click node_auth_context "https://github.com/ahatasham5/islamic-gpt-frontend/blob/main/lib/auth-context.tsx"
click node_language_context "https://github.com/ahatasham5/islamic-gpt-frontend/blob/main/lib/language-context.tsx"
click node_with_auth "https://github.com/ahatasham5/islamic-gpt-frontend/blob/main/lib/with-auth.tsx"
click node_use_auth "https://github.com/ahatasham5/islamic-gpt-frontend/blob/main/hooks/use-auth.ts"
click node_use_chat "https://github.com/ahatasham5/islamic-gpt-frontend/blob/main/hooks/use-chat.ts"
click node_use_books "https://github.com/ahatasham5/islamic-gpt-frontend/blob/main/hooks/use-books.ts"
click node_api_auth "https://github.com/ahatasham5/islamic-gpt-frontend/blob/main/lib/api/auth.ts"
click node_api_chat "https://github.com/ahatasham5/islamic-gpt-frontend/blob/main/lib/api/chat.ts"
click node_api_books "https://github.com/ahatasham5/islamic-gpt-frontend/blob/main/lib/api/books.ts"
click node_http_client "https://github.com/ahatasham5/islamic-gpt-frontend/blob/main/lib/http.ts"
click node_backend_proxy "https://github.com/ahatasham5/islamic-gpt-frontend/blob/main/app/api/backend/[...path]/route.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_pages_app,node_pages_index,node_pages_landing,node_pages_login,node_pages_reset,node_pages_invite,node_pages_user,node_pages_mufti,node_pages_admin toneBlue
class node_chat_app,node_chat_main,node_chat_sidebar,node_streaming_answer,node_sources_panel,node_admin_users,node_admin_feedbacks,node_book_manager toneAmber
class node_use_auth,node_use_chat,node_use_books,node_api_auth,node_api_chat,node_api_books toneMint
class node_auth_context,node_language_context,node_with_auth toneRose
class node_http_client,node_backend_proxy,node_external_backend toneIndigo
```

## Components

### Routes

Pages Router entrypoints and role-based screens

- [App shell](https://github.com/ahatasham5/islamic-gpt-frontend/blob/main/pages/_app.tsx): next app · Global Next.js app wrapper · `pages/_app.tsx`
- [Entry](https://github.com/ahatasham5/islamic-gpt-frontend/blob/main/pages/index.tsx): route · Top-level landing or redirect decision · `pages/index.tsx`
- [Landing](https://github.com/ahatasham5/islamic-gpt-frontend/blob/main/pages/landing/index.tsx): route · Public marketing and entry page · `pages/landing/index.tsx`
- [Login](https://github.com/ahatasham5/islamic-gpt-frontend/blob/main/pages/login/index.tsx): route · Authentication sign-in page · `pages/login/index.tsx`
- [Reset password](https://github.com/ahatasham5/islamic-gpt-frontend/blob/main/pages/reset-password/index.tsx): route · Password recovery page · `pages/reset-password/index.tsx`
- [Accept invite](https://github.com/ahatasham5/islamic-gpt-frontend/blob/main/pages/accept-invite/index.tsx): route · Invitation acceptance page · `pages/accept-invite/index.tsx`
- [User area](https://github.com/ahatasham5/islamic-gpt-frontend/blob/main/pages/user/index.tsx): route · Authenticated user workspace · `pages/user/index.tsx`
- [Mufti area](https://github.com/ahatasham5/islamic-gpt-frontend/blob/main/pages/mufti/index.tsx): route · Role-specific mufti workspace · `pages/mufti/index.tsx`
- [Admin area](https://github.com/ahatasham5/islamic-gpt-frontend/blob/main/pages/admin/index.tsx): route · Administrative console · `pages/admin/index.tsx`

### Features

Feature-specific UI composition and panels

- [Chat app](https://github.com/ahatasham5/islamic-gpt-frontend/blob/main/components/chat-app.tsx): feature ui · Top-level conversational experience · `components/chat-app.tsx`
- [Chat main](https://github.com/ahatasham5/islamic-gpt-frontend/blob/main/components/chat-main.tsx): feature ui · Primary chat workspace and message flow · `components/chat-main.tsx`
- [Sidebar](https://github.com/ahatasham5/islamic-gpt-frontend/blob/main/components/chat-sidebar.tsx): feature ui · Chat navigation and contextual controls · `components/chat-sidebar.tsx`
- [Streaming answer](https://github.com/ahatasham5/islamic-gpt-frontend/blob/main/components/streaming-answer.tsx): renderer · Incremental model response rendering · `components/streaming-answer.tsx`
- [Sources panel](https://github.com/ahatasham5/islamic-gpt-frontend/blob/main/components/sources-panel.tsx): feature ui · Citation and provenance display · `components/sources-panel.tsx`
- [Admin users](https://github.com/ahatasham5/islamic-gpt-frontend/blob/main/components/admin-users.tsx): admin ui · User administration surface · `components/admin-users.tsx`
- [Admin feedbacks](https://github.com/ahatasham5/islamic-gpt-frontend/blob/main/components/admin-feedbacks.tsx): admin ui · Feedback review surface · `components/admin-feedbacks.tsx`
- [Book manager](https://github.com/ahatasham5/islamic-gpt-frontend/blob/main/components/book-manager.tsx): knowledge ui · Curated source and book management · `components/book-manager.tsx`

### State & Data

Auth, hooks, and API client layers

- [Auth hook](https://github.com/ahatasham5/islamic-gpt-frontend/blob/main/hooks/use-auth.ts): react hook · Auth state and actions bridge · `hooks/use-auth.ts`
- [Chat hook](https://github.com/ahatasham5/islamic-gpt-frontend/blob/main/hooks/use-chat.ts): react hook · Chat state and operations bridge · `hooks/use-chat.ts`
- [Books hook](https://github.com/ahatasham5/islamic-gpt-frontend/blob/main/hooks/use-books.ts): react hook · Book and source management bridge · `hooks/use-books.ts`
- [Auth API](https://github.com/ahatasham5/islamic-gpt-frontend/blob/main/lib/api/auth.ts): api client · Auth domain HTTP client · `lib/api/auth.ts`
- [Chat API](https://github.com/ahatasham5/islamic-gpt-frontend/blob/main/lib/api/chat.ts): api client · Chat and conversation HTTP client · `lib/api/chat.ts`
- [Books API](https://github.com/ahatasham5/islamic-gpt-frontend/blob/main/lib/api/books.ts): api client · Books and knowledge HTTP client · `lib/api/books.ts`

### Core

Shared runtime utilities and global providers

- [Auth context](https://github.com/ahatasham5/islamic-gpt-frontend/blob/main/lib/auth-context.tsx): state provider · Shared authentication session state · `lib/auth-context.tsx`
- [Language context](https://github.com/ahatasham5/islamic-gpt-frontend/blob/main/lib/language-context.tsx): state provider · Global language or locale state · `lib/language-context.tsx`
- [Auth guard](https://github.com/ahatasham5/islamic-gpt-frontend/blob/main/lib/with-auth.tsx): route guard · Protection wrapper for authenticated areas · `lib/with-auth.tsx`

### Backend Boundary

Local proxy and external service boundary

- [HTTP client](https://github.com/ahatasham5/islamic-gpt-frontend/blob/main/lib/http.ts): shared client · Common request layer for local API calls · `lib/http.ts`
- [Backend proxy](https://github.com/ahatasham5/islamic-gpt-frontend/blob/main/app/api/backend/[...path]/route.ts): next api route · Catch-all proxy under /api/backend · `app/api/backend/[...path]/route.ts`
- **Backend services**: external api · Upstream application backend outside this repo

## Connections

- App shell → Auth context: provides · Wraps the app with auth state
- App shell → Language context: provides · Wraps the app with locale state
- Entry → Landing: routes to · Entry point leads into public landing
- Login → Auth hook: uses · Login screen drives auth actions
- Reset password → Auth API: uses · Password recovery uses auth client
- Accept invite → Auth API: uses · Invite acceptance uses auth client
- User area → Auth guard: protected by · Authenticated user area is guarded
- User area → Chat app: renders · User area centers on chat UI
- Mufti area → Auth guard: protected by · Mufti area is guarded
- Mufti area → Book manager: renders · Mufti workflows include source management
- Admin area → Auth guard: protected by · Admin area is guarded
- Admin area → Admin users: renders · Admin console includes user management
- Admin area → Admin feedbacks: renders · Admin console includes feedback review
- Chat app → Chat main: composes · Chat shell delegates to main workspace
- Chat app → Sidebar: composes · Chat shell includes navigation sidebar
- Chat main → Chat hook: uses · Main chat UI is driven by chat hook
- Chat main → Streaming answer: renders · Streams model responses into the view
- Chat main → Sources panel: uses · Shows citations and sources for answers
- Auth hook → Auth API: calls · Auth hook wraps auth API
- Chat hook → Chat API: calls · Chat hook wraps chat API
- Books hook → Books API: calls · Books hook wraps books API
- Auth API → HTTP client: uses · Auth requests go through shared HTTP layer
- Chat API → HTTP client: uses · Chat requests go through shared HTTP layer
- Books API → HTTP client: uses · Books requests go through shared HTTP layer
- HTTP client → Backend proxy: targets · Local API calls are routed through proxy endpoint
- Backend proxy → Backend services: forwards to · Proxy adapts requests to the upstream backend