# mehedi-bit/journey-with-quran architecture

> Architecture diagram of the GitHub repository mehedi-bit/journey-with-quran, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mehedi-bit/journey-with-quran
- Repository: https://github.com/mehedi-bit/journey-with-quran

## Overview

1. **Overall shape**
   This is a two-tier application: a **React + TypeScript SPA** in `frontend-v2/` and an **Express + Node.js API** in `backend/`, with **MongoDB/Mongoose** as the persistent store. The product mixes a community journaling/social layer with Quran study content.

2. **Frontend boundary**
   The frontend is a Vite-based client app (`main.tsx`, `App.tsx`) organized as routed page components under `src/components/pages`. It is the primary user-facing boundary for authentication, profile management, posts, users, and Quran/tafsir/hadith browsing.

3. **Frontend state model**
   Client state is centralized with small “atom” stores in `src/atoms/` (`authAtom`, `userAtom`, `postsAtom`, `feedAtom`, `currentPostAtom`). That suggests the app shares auth/session state, current user data, and post/feed data across many pages without prop-drilling.

4. **Frontend feature clusters**
   The UI is split into clear domains:
   - `components/auth` for login/signup/logout/profile update
   - `components/post` for creating, viewing, commenting, and post menus
   - `components/user` and `components/suggestedUser` for profile/social interactions
   - `components/surah`, `components/tafsir`, `components/Hadith` for Quran study content
   - `components/common` for global layout and modals like navbar, sidebar, theme switcher, report popup, welcome modal

5. **Frontend UI foundation**
   There is a reusable UI toolkit under `src/components/ui/` and a theme provider. This implies a design-system style setup, likely with modal/dialog, tabs, sheet, dropdown, form, and input primitives reused across pages. The frontend also includes `usePreviewImage`, indicating image upload/preview UX for profile or post media.

6. **Backend entry and routing**
   The backend is structured conventionally around `server.js` as the entrypoint, `routes/` for HTTP endpoints, `controllers/` for request logic, `middlewares/` for auth protection, and `models/` for Mongoose schemas. `connectDB.js` establishes the MongoDB connection before the API serves traffic.

7. **Backend domain model**
   The visible database model boundary is small and focused: `userModel.js` and `postModel.js`. That means the backend’s persistent core is the social layer—accounts, profiles, follows, posts, comments/replies, and associated metadata—rather than Quran content storage.

8. **Authentication and authorization**
   Auth is cookie/JWT-based. `generateTokenAndSetCookie.js` issues auth tokens, and `protectRoute.js` guards protected endpoints. So the request path is: client submits credentials or session-changing actions → backend validates → sets token cookie → protected controllers read the authenticated user context.

9. **Social data flows**
   The README’s “atomic updates” and “auto propagation” show that profile changes and follow/unfollow actions are treated as cross-document operations. In architecture terms, this means a user update may cascade to many posts/comments, and follow relationships likely touch multiple user records or arrays, with MongoDB transactions used to keep those writes consistent.

10. **Content and external-service considerations**
   The frontend contains dedicated Quran/tafsir/hadith views, but the backend tree does not show models/routes for those domains. That suggests those experiences are either client-side/static or sourced externally, while the backend remains centered on social journaling. Environment variables mention **Cloudinary**, so image upload/storage is part of the backend’s infrastructure boundary even though its integration code is not shown here.

11. **Deployment/tooling boundary**
   The frontend has Vite, Tailwind, and a `vercel.json`, so it is likely deployed independently from the backend. The backend uses environment-based configuration (`.env.example`) and is designed for local development with separate frontend/backend servers.

12. **Diagram takeaway**
   For an architecture diagram, model:
   - a **browser SPA** with shared atom-based client state
   - an **Express API** with auth, user, and post controllers
   - a **MongoDB/Mongoose** persistence layer
   - **Cloudinary** as an external media service
   - a **content browsing frontend** for Quran/tafsir/hadith that sits alongside the community journaling features rather than inside the backend domain.

Main entry points: [`frontend-v2/src/components/pages`](https://github.com/mehedi-bit/journey-with-quran/tree/main/frontend-v2/src/components/pages) (Pages), [`frontend-v2/src/main.tsx`](https://github.com/mehedi-bit/journey-with-quran/blob/main/frontend-v2/src/main.tsx) (App shell), [`backend/routes`](https://github.com/mehedi-bit/journey-with-quran/tree/main/backend/routes) (Routes), [`frontend-v2/src/components/post`](https://github.com/mehedi-bit/journey-with-quran/tree/main/frontend-v2/src/components/post) (Posts UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend SPA"]
  node_frontend_app["App shell<br/>Vite/React entry<br/>[main.tsx]"]
  node_frontend_routes["Pages"]
  node_frontend_state(("Atoms<br/>Client state"))
  node_frontend_auth["Auth UI<br/>Auth components"]
  node_frontend_posts["Posts UI<br/>Social components"]
  node_frontend_users["Users UI<br/>Profile components"]
  node_frontend_suggested["Suggestions<br/>Social discovery"]
  node_frontend_quran["Quran views<br/>Study components"]
  node_frontend_common["Layout UI<br/>Shell components"]
  node_frontend_ui["UI kit<br/>Design system"]
  node_frontend_theme(("Theme<br/>Provider<br/>[theme-provider.tsx]"))
  node_frontend_hook(("Image preview<br/>Hook<br/>[usePreviewImage.ts]"))
end

subgraph group_backend["Backend API"]
  node_backend_server["Server<br/>Express entry<br/>[server.js]"]
  node_backend_routes["Routes"]
  node_backend_ctrl_users["User ctrl<br/>Request handlers<br/>[userController.js]"]
  node_backend_ctrl_posts["Post ctrl<br/>Request handlers<br/>[postController.js]"]
  node_backend_auth{{"Protect route<br/>Middleware<br/>[protectRoute.js]"}}
  node_backend_models[("Models<br/>Mongoose schemas")]
  node_backend_db(("DB connect<br/>Mongo bootstrap<br/>[connectDB.js]"))
  node_backend_token(("Token helper<br/>JWT cookie helper"))
end

subgraph group_external["External Services"]
  node_mongo[("MongoDB<br/>Database")]
  node_cloudinary(("Cloudinary<br/>Media service"))
end

node_frontend_app -->|"renders"| node_frontend_routes
node_frontend_app -->|"shares state"| node_frontend_state
node_frontend_app -->|"uses chrome"| node_frontend_common
node_frontend_routes -->|"auth screens"| node_frontend_auth
node_frontend_routes -->|"social screens"| node_frontend_posts
node_frontend_routes -->|"profile screens"| node_frontend_users
node_frontend_routes -->|"discovery"| node_frontend_suggested
node_frontend_routes -->|"study screens"| node_frontend_quran
node_frontend_common -->|"built on"| node_frontend_ui
node_frontend_common -->|"theme"| node_frontend_theme
node_frontend_posts -->|"uploads"| node_frontend_hook
node_backend_server -->|"mounts"| node_backend_routes
node_backend_server -->|"connects"| node_backend_db
node_backend_routes -->|"user endpoints"| node_backend_ctrl_users
node_backend_routes -->|"post endpoints"| node_backend_ctrl_posts
node_backend_routes -->|"protects"| node_backend_auth
node_backend_ctrl_users -->|"issues token"| node_backend_token
node_backend_ctrl_users -->|"reads/writes"| node_backend_models
node_backend_ctrl_posts -->|"reads/writes"| node_backend_models
node_backend_models -->|"stores"| node_mongo
node_frontend_app -.->|"API calls"| node_backend_server
node_frontend_posts -.->|"media upload"| node_cloudinary
node_frontend_users -.->|"avatar upload"| node_cloudinary

click node_frontend_app "https://github.com/mehedi-bit/journey-with-quran/blob/main/frontend-v2/src/main.tsx"
click node_frontend_routes "https://github.com/mehedi-bit/journey-with-quran/tree/main/frontend-v2/src/components/pages"
click node_frontend_state "https://github.com/mehedi-bit/journey-with-quran/tree/main/frontend-v2/src/atoms"
click node_frontend_auth "https://github.com/mehedi-bit/journey-with-quran/tree/main/frontend-v2/src/components/auth"
click node_frontend_posts "https://github.com/mehedi-bit/journey-with-quran/tree/main/frontend-v2/src/components/post"
click node_frontend_users "https://github.com/mehedi-bit/journey-with-quran/tree/main/frontend-v2/src/components/user"
click node_frontend_suggested "https://github.com/mehedi-bit/journey-with-quran/tree/main/frontend-v2/src/components/suggestedUser"
click node_frontend_quran "https://github.com/mehedi-bit/journey-with-quran/tree/main/frontend-v2/src/components/surah"
click node_frontend_common "https://github.com/mehedi-bit/journey-with-quran/tree/main/frontend-v2/src/components/common"
click node_frontend_ui "https://github.com/mehedi-bit/journey-with-quran/tree/main/frontend-v2/src/components/ui"
click node_frontend_theme "https://github.com/mehedi-bit/journey-with-quran/blob/main/frontend-v2/src/components/theme-provider.tsx"
click node_frontend_hook "https://github.com/mehedi-bit/journey-with-quran/blob/main/frontend-v2/src/hooks/usePreviewImage.ts"
click node_backend_server "https://github.com/mehedi-bit/journey-with-quran/blob/main/backend/server.js"
click node_backend_routes "https://github.com/mehedi-bit/journey-with-quran/tree/main/backend/routes"
click node_backend_ctrl_users "https://github.com/mehedi-bit/journey-with-quran/blob/main/backend/controllers/userController.js"
click node_backend_ctrl_posts "https://github.com/mehedi-bit/journey-with-quran/blob/main/backend/controllers/postController.js"
click node_backend_auth "https://github.com/mehedi-bit/journey-with-quran/blob/main/backend/middlewares/protectRoute.js"
click node_backend_models "https://github.com/mehedi-bit/journey-with-quran/tree/main/backend/models"
click node_backend_db "https://github.com/mehedi-bit/journey-with-quran/blob/main/backend/db/connectDB.js"
click node_backend_token "https://github.com/mehedi-bit/journey-with-quran/blob/main/backend/utils/helpers/generateTokenAndSetCookie.js"

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_frontend_app,node_frontend_routes,node_frontend_state,node_frontend_auth,node_frontend_posts,node_frontend_users,node_frontend_suggested,node_frontend_quran,node_frontend_common,node_frontend_ui,node_frontend_theme,node_frontend_hook toneBlue
class node_backend_server,node_backend_routes,node_backend_ctrl_users,node_backend_ctrl_posts,node_backend_auth,node_backend_models,node_backend_db,node_backend_token toneAmber
class node_mongo,node_cloudinary toneMint
```

## Components

### Frontend SPA

React + TypeScript client app and its feature domains

- [App shell](https://github.com/mehedi-bit/journey-with-quran/blob/main/frontend-v2/src/main.tsx): Vite/React entry · Top-level SPA bootstrapping and route composition · `frontend-v2/src/main.tsx`
- [Pages](https://github.com/mehedi-bit/journey-with-quran/tree/main/frontend-v2/src/components/pages): Route pages · Primary routed screens for auth, social, and Quran study views · `frontend-v2/src/components/pages`
- [Atoms](https://github.com/mehedi-bit/journey-with-quran/tree/main/frontend-v2/src/atoms): Client state · Shared atom stores for auth, user, feed, and post state · `frontend-v2/src/atoms`
- [Auth UI](https://github.com/mehedi-bit/journey-with-quran/tree/main/frontend-v2/src/components/auth): Auth components · Login, signup, logout, and profile update UI · `frontend-v2/src/components/auth`
- [Posts UI](https://github.com/mehedi-bit/journey-with-quran/tree/main/frontend-v2/src/components/post): Social components · Post creation, viewing, commenting, and menus · `frontend-v2/src/components/post`
- [Users UI](https://github.com/mehedi-bit/journey-with-quran/tree/main/frontend-v2/src/components/user): Profile components · Profile headers, user controls, and post/reply tabs · `frontend-v2/src/components/user`
- [Suggestions](https://github.com/mehedi-bit/journey-with-quran/tree/main/frontend-v2/src/components/suggestedUser): Social discovery · Suggested user modal and follow entry points · `frontend-v2/src/components/suggestedUser`
- [Quran views](https://github.com/mehedi-bit/journey-with-quran/tree/main/frontend-v2/src/components/surah): Study components · Surah, tafsir, and hadith browsing UI · `frontend-v2/src/components/surah`
- [Layout UI](https://github.com/mehedi-bit/journey-with-quran/tree/main/frontend-v2/src/components/common): Shell components · Navbar, sidebar, modals, theme switcher, and app-wide chrome · `frontend-v2/src/components/common`
- [UI kit](https://github.com/mehedi-bit/journey-with-quran/tree/main/frontend-v2/src/components/ui): Design system · Reusable primitive components for forms, dialogs, inputs, tabs, and sheets · `frontend-v2/src/components/ui`
- [Theme](https://github.com/mehedi-bit/journey-with-quran/blob/main/frontend-v2/src/components/theme-provider.tsx): Provider · Theme provider used by the client shell · `frontend-v2/src/components/theme-provider.tsx`
- [Image preview](https://github.com/mehedi-bit/journey-with-quran/blob/main/frontend-v2/src/hooks/usePreviewImage.ts): Hook · Client-side image preview helper for uploads · `frontend-v2/src/hooks/usePreviewImage.ts`

### Backend API

Express + Node.js service, auth, controllers, and MongoDB models

- [Server](https://github.com/mehedi-bit/journey-with-quran/blob/main/backend/server.js): Express entry · API bootstrap and server startup · `backend/server.js`
- [Routes](https://github.com/mehedi-bit/journey-with-quran/tree/main/backend/routes): HTTP routes · User and post endpoint definitions · `backend/routes`
- [User ctrl](https://github.com/mehedi-bit/journey-with-quran/blob/main/backend/controllers/userController.js): Request handlers · User profile, auth, and social action controllers · `backend/controllers/userController.js`
- [Post ctrl](https://github.com/mehedi-bit/journey-with-quran/blob/main/backend/controllers/postController.js): Request handlers · Post and comment controller logic · `backend/controllers/postController.js`
- [Protect route](https://github.com/mehedi-bit/journey-with-quran/blob/main/backend/middlewares/protectRoute.js): Middleware · Authenticated-request guard for protected endpoints · `backend/middlewares/protectRoute.js`
- [Models](https://github.com/mehedi-bit/journey-with-quran/tree/main/backend/models): Mongoose schemas · Persistent user and post schemas · `backend/models`
- [DB connect](https://github.com/mehedi-bit/journey-with-quran/blob/main/backend/db/connectDB.js): Mongo bootstrap · MongoDB connection setup before serving requests · `backend/db/connectDB.js`
- [Token helper](https://github.com/mehedi-bit/journey-with-quran/blob/main/backend/utils/helpers/generateTokenAndSetCookie.js): JWT cookie helper · Creates auth tokens and sets session cookies · `backend/utils/helpers/generateTokenAndSetCookie.js`

### External Services

Persistent store and media hosting boundary

- **MongoDB**: Database · Primary persistent store for users and posts
- **Cloudinary**: Media service · External image storage and upload boundary

## Connections

- App shell → Pages: renders · App shell mounts the routed page layer
- App shell → Atoms: shares state · Pages consume shared atom stores
- App shell → Layout UI: uses chrome · Global layout and modal components wrap the app
- Pages → Auth UI: auth screens · Auth-related pages use the auth component cluster
- Pages → Posts UI: social screens · Post and comment pages compose post widgets
- Pages → Users UI: profile screens · User pages use profile components
- Pages → Suggestions: discovery · Suggested users pages use discovery components
- Pages → Quran views: study screens · Quran study pages compose surah, tafsir, and hadith views
- Layout UI → UI kit: built on · Shell components reuse the shared UI primitive kit
- Layout UI → Theme: theme · Theme provider supports global appearance switching
- Posts UI → Image preview: uploads · Post and profile flows can preview selected images
- Server → Routes: mounts · Server exposes API routes
- Server → DB connect: connects · Server initializes MongoDB connection
- Routes → User ctrl: user endpoints · User routes delegate to user controller handlers
- Routes → Post ctrl: post endpoints · Post routes delegate to post controller handlers
- Routes → Protect route: protects · Protected endpoints use auth middleware
- User ctrl → Token helper: issues token · Auth flows generate session cookies
- User ctrl → Models: reads/writes · User operations persist through Mongoose models
- Post ctrl → Models: reads/writes · Post and comment operations persist through Mongoose models
- Models → MongoDB: stores · Mongoose schemas persist to MongoDB
- App shell → Server: API calls · SPA talks to the Express backend
- Posts UI → Cloudinary: media upload · Image-bearing post flows rely on external media storage
- Users UI → Cloudinary: avatar upload · Profile image flows can use external media storage