ahatasham5/islamic-gpt-frontend

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.