# jakirulislamhakim/s-book-social-backend architecture

> Architecture diagram of the GitHub repository jakirulislamhakim/s-book-social-backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jakirulislamhakim/s-book-social-backend
- Repository: https://github.com/jakirulislamhakim/s-book-social-backend

## Overview

1. **Overall shape**
   - This is a TypeScript Node.js/Express API organized as a feature-based backend for a social media product. The application is split into a small core shell plus versioned modules under `src/app/v1`.

2. **Process entrypoints**
   - `src/server.ts` is the runtime entrypoint, and `src/app.ts` likely builds the Express app.
   - Request handling is versioned through `src/app/v1/routes`, which aggregates all feature routes into the API surface.

3. **Feature-module boundary**
   - Each domain area is isolated into its own module folder with a consistent internal structure: controller, service, route, model, validation, interface, and sometimes constants/utils.
   - The main modules are: Auth, User, Profile, Post, Comment, Reaction, Friend, Story, Block, Notification, and PostAppeal.

4. **Request lifecycle**
   - The common flow is: route → validation middleware → auth/role middleware when needed → controller → service → Mongoose model/query layer → standardized API response.
   - Validation is centralized with Zod-based schemas, and responses are standardized through shared utilities rather than being assembled ad hoc in controllers.

5. **Data layer**
   - MongoDB with Mongoose is the primary persistence boundary.
   - Models are feature-specific, which fits the social graph and content domains: users, posts, comments, reactions, friends, stories, blocks, notifications, and appeals.
   - `QueryBuilder` suggests a shared abstraction for filtering, pagination, sorting, and search across list endpoints.

6. **Social graph and content dependencies**
   - The system’s core business rules revolve around relationships between users: friendship, blocking, mentions, visibility rules, and feed generation.
   - Posts and stories depend on those graph rules to decide who can see content, while comments and reactions feed into notification events.

7. **Authentication and authorization**
   - Auth is JWT-based with access/refresh token handling, password lifecycle flows, and email verification.
   - Authorization is role-based, with at least `USER`, `ADMIN`, and `SUPER_ADMIN` boundaries enforced by middleware and route protection.

8. **Media and file-upload pipeline**
   - File upload handling is split into Multer and Cloudinary config, indicating multipart upload ingress plus cloud-hosted asset storage.
   - This is relevant for profile photos, cover photos, post images, and story media.

9. **Notifications and background work**
   - Notifications are a first-class subsystem, triggered by social actions and admin workflows such as friend requests, mentions, reactions, comments, appeals, and moderation events.
   - A cron job in `jobs/deleteUser.job.ts` handles delayed cleanup of soft-deleted users, showing a background-processing boundary separate from request/response flow.

10. **Moderation and admin workflows**
   - PostAppeal, Block, and administrative user/post actions form a moderation layer on top of the social product.
   - The readme indicates transactional/atomic operations for sensitive multi-step flows, which implies MongoDB transaction usage where state changes and notifications must stay consistent.

11. **Cross-cutting middleware and error handling**
   - `middlewares` contains the platform concerns: rate limiting, request tracing, health checks, text/JSON parsing, auth checks, not-found handling, and the global error handler.
   - Error normalization is explicit, with handlers for Zod errors, Mongoose cast/validation errors, and duplicate key errors, wrapped by a custom `AppError`.

12. **Shared utilities and infrastructure**
   - `utils` holds reusable infrastructure helpers: email sending, template compilation, base URL generation, mention parsing, seeding a super admin, Swagger helpers, and async error wrappers.
   - Logging is also centralized, with separate app and error log outputs.

13. **API docs, views, and static assets**
   - The repo includes `src/docs/v1/swagger.yaml` for API documentation, plus Handlebars templates for email/content rendering and a small public asset folder.
   - This means the backend is not just JSON APIs; it also supports templated outbound messages and documented endpoints.

14. **Operational focus**
   - The architecture is built for production concerns: validation, RBAC, pagination, indexing, rate limiting, structured logging, and scheduled cleanup.
   - External dependencies that materially affect the design are MongoDB, Cloudinary, and email providers (Nodemailer/SendGrid), all of which sit behind dedicated config/util layers rather than being embedded in feature code.

Main entry points: [`src/app/v1/routes/v1Routes.ts`](https://github.com/jakirulislamhakim/s-book-social-backend/blob/main/src/app/v1/routes/v1Routes.ts) (V1 routes), [`src/app/v1/utils/sendApiResponse.ts`](https://github.com/jakirulislamhakim/s-book-social-backend/blob/main/src/app/v1/utils/sendApiResponse.ts) (API response), [`src/app.ts`](https://github.com/jakirulislamhakim/s-book-social-backend/blob/main/src/app.ts) (App), [`src/app/v1/modules/Auth/auth.route.ts`](https://github.com/jakirulislamhakim/s-book-social-backend/blob/main/src/app/v1/modules/Auth/auth.route.ts) (Auth)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime shell"]
  node_server["Server<br/>entrypoint<br/>[server.ts]"]
  node_app["App<br/>express bootstrap<br/>[app.ts]"]
end

subgraph group_http["HTTP platform"]
  node_v1routes["V1 routes<br/>route aggregator<br/>[v1Routes.ts]"]
  node_appmw["App middleware<br/>middleware stack<br/>[appMiddleware.ts]"]
  node_authmw["Auth guard<br/>rbac middleware<br/>[auth.ts]"]
  node_errorhandler["Error handler<br/>error middleware"]
end

subgraph group_domain["Domain modules"]
  node_auth["Auth<br/>feature module<br/>[auth.route.ts]"]
  node_user["User<br/>feature module<br/>[user.route.ts]"]
  node_post["Post<br/>content module<br/>[post.route.ts]"]
  node_social["Social graph<br/>relationship module<br/>[friend.route.ts]"]
  node_notify["Notifications<br/>event module"]
  node_appeal["Post appeals<br/>moderation module"]
end

subgraph group_infra["Shared infra"]
  node_querybuilder["Query builder<br/>list abstraction<br/>[QueryBuilder.ts]"]
  node_config["Config<br/>[index.ts]"]
  node_storage["Upload storage<br/>file pipeline<br/>[multer.config.ts]"]
  node_response["API response<br/>response helper<br/>[sendApiResponse.ts]"]
end

subgraph group_ops["Ops and assets"]
  node_jobs["Cleanup job<br/>background job<br/>[deleteUser.job.ts]"]
  node_templates["Email templates<br/>rendering assets<br/>[reset-password.hbs]"]
  node_docs["API docs<br/>openapi spec<br/>[swagger.yaml]"]
end

node_server -->|"boots"| node_app
node_app -->|"uses"| node_appmw
node_app -->|"mounts"| node_v1routes
node_v1routes -->|"routes"| node_auth
node_v1routes -->|"routes"| node_user
node_v1routes -->|"routes"| node_post
node_v1routes -->|"routes"| node_social
node_v1routes -->|"routes"| node_notify
node_v1routes -->|"routes"| node_appeal
node_auth -->|"protected by"| node_authmw
node_auth -->|"returns"| node_response
node_user -->|"lists with"| node_querybuilder
node_post -->|"lists with"| node_querybuilder
node_social -->|"protected by"| node_authmw
node_notify -->|"returns"| node_response
node_appeal -->|"returns"| node_response
node_appmw -->|"delegates"| node_errorhandler
node_config -->|"provides"| node_storage
node_jobs -->|"uses"| node_config
node_templates -.->|"supports"| node_response
node_docs -.->|"documents"| node_v1routes

click node_server "https://github.com/jakirulislamhakim/s-book-social-backend/blob/main/src/server.ts"
click node_app "https://github.com/jakirulislamhakim/s-book-social-backend/blob/main/src/app.ts"
click node_v1routes "https://github.com/jakirulislamhakim/s-book-social-backend/blob/main/src/app/v1/routes/v1Routes.ts"
click node_appmw "https://github.com/jakirulislamhakim/s-book-social-backend/blob/main/src/app/v1/middlewares/appMiddleware.ts"
click node_authmw "https://github.com/jakirulislamhakim/s-book-social-backend/blob/main/src/app/v1/middlewares/auth.ts"
click node_errorhandler "https://github.com/jakirulislamhakim/s-book-social-backend/blob/main/src/app/v1/middlewares/globalErrorHandler.ts"
click node_querybuilder "https://github.com/jakirulislamhakim/s-book-social-backend/blob/main/src/app/v1/builder/QueryBuilder.ts"
click node_config "https://github.com/jakirulislamhakim/s-book-social-backend/blob/main/src/app/v1/config/index.ts"
click node_storage "https://github.com/jakirulislamhakim/s-book-social-backend/blob/main/src/app/v1/config/multer.config.ts"
click node_response "https://github.com/jakirulislamhakim/s-book-social-backend/blob/main/src/app/v1/utils/sendApiResponse.ts"
click node_auth "https://github.com/jakirulislamhakim/s-book-social-backend/blob/main/src/app/v1/modules/Auth/auth.route.ts"
click node_user "https://github.com/jakirulislamhakim/s-book-social-backend/blob/main/src/app/v1/modules/User/user.route.ts"
click node_post "https://github.com/jakirulislamhakim/s-book-social-backend/blob/main/src/app/v1/modules/Post/post.route.ts"
click node_social "https://github.com/jakirulislamhakim/s-book-social-backend/blob/main/src/app/v1/modules/Friend/friend.route.ts"
click node_notify "https://github.com/jakirulislamhakim/s-book-social-backend/blob/main/src/app/v1/modules/Notification/notification.route.ts"
click node_appeal "https://github.com/jakirulislamhakim/s-book-social-backend/blob/main/src/app/v1/modules/PostAppeal/postAppeal.route.ts"
click node_jobs "https://github.com/jakirulislamhakim/s-book-social-backend/blob/main/src/app/v1/jobs/deleteUser.job.ts"
click node_templates "https://github.com/jakirulislamhakim/s-book-social-backend/blob/main/src/app/v1/views/reset-password.hbs"
click node_docs "https://github.com/jakirulislamhakim/s-book-social-backend/blob/main/src/docs/v1/swagger.yaml"

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_server,node_app toneBlue
class node_v1routes,node_appmw,node_authmw,node_errorhandler toneAmber
class node_auth,node_user,node_post,node_social,node_notify,node_appeal toneMint
class node_querybuilder,node_config,node_storage,node_response toneRose
class node_jobs,node_templates,node_docs toneIndigo
```

## Components

### Runtime shell

Process entrypoint and app bootstrap.

- [Server](https://github.com/jakirulislamhakim/s-book-social-backend/blob/main/src/server.ts): entrypoint · Starts the Node.js process. · `src/server.ts`
- [App](https://github.com/jakirulislamhakim/s-book-social-backend/blob/main/src/app.ts): express bootstrap · Builds the Express application shell. · `src/app.ts`

### HTTP platform

Versioned routing, middleware, and request lifecycle concerns.

- [V1 routes](https://github.com/jakirulislamhakim/s-book-social-backend/blob/main/src/app/v1/routes/v1Routes.ts): route aggregator · Composes the versioned API surface. · `src/app/v1/routes/v1Routes.ts`
- [App middleware](https://github.com/jakirulislamhakim/s-book-social-backend/blob/main/src/app/v1/middlewares/appMiddleware.ts): middleware stack · Wires shared HTTP middleware into the app. · `src/app/v1/middlewares/appMiddleware.ts`
- [Auth guard](https://github.com/jakirulislamhakim/s-book-social-backend/blob/main/src/app/v1/middlewares/auth.ts): rbac middleware · Protects routes and enforces authenticated access. · `src/app/v1/middlewares/auth.ts`
- [Error handler](https://github.com/jakirulislamhakim/s-book-social-backend/blob/main/src/app/v1/middlewares/globalErrorHandler.ts): error middleware · Normalizes and formats application errors. · `src/app/v1/middlewares/globalErrorHandler.ts`

### Domain modules

Feature-based API modules for social content and relationships.

- [Auth](https://github.com/jakirulislamhakim/s-book-social-backend/blob/main/src/app/v1/modules/Auth/auth.route.ts): feature module · JWT login, refresh, verification, and password flows. · `src/app/v1/modules/Auth/auth.route.ts`
- [User](https://github.com/jakirulislamhakim/s-book-social-backend/blob/main/src/app/v1/modules/User/user.route.ts): feature module · User lifecycle, profile ownership, and account state. · `src/app/v1/modules/User/user.route.ts`
- [Post](https://github.com/jakirulislamhakim/s-book-social-backend/blob/main/src/app/v1/modules/Post/post.route.ts): content module · Core post creation, listing, and visibility logic. · `src/app/v1/modules/Post/post.route.ts`
- [Social graph](https://github.com/jakirulislamhakim/s-book-social-backend/blob/main/src/app/v1/modules/Friend/friend.route.ts): relationship module · Friend, block, comment, reaction, and story relationships. · `src/app/v1/modules/Friend/friend.route.ts`
- [Notifications](https://github.com/jakirulislamhakim/s-book-social-backend/blob/main/src/app/v1/modules/Notification/notification.route.ts): event module · Notification creation and delivery for social actions. · `src/app/v1/modules/Notification/notification.route.ts`
- [Post appeals](https://github.com/jakirulislamhakim/s-book-social-backend/blob/main/src/app/v1/modules/PostAppeal/postAppeal.route.ts): moderation module · Post dispute and moderation appeal workflow. · `src/app/v1/modules/PostAppeal/postAppeal.route.ts`

### Shared infra

Cross-cutting configuration, utilities, and persistence helpers.

- [Query builder](https://github.com/jakirulislamhakim/s-book-social-backend/blob/main/src/app/v1/builder/QueryBuilder.ts): list abstraction · Shared filtering, sorting, pagination, and search helper. · `src/app/v1/builder/QueryBuilder.ts`
- [Config](https://github.com/jakirulislamhakim/s-book-social-backend/blob/main/src/app/v1/config/index.ts): runtime config · Loads shared environment and service configuration. · `src/app/v1/config/index.ts`
- [Upload storage](https://github.com/jakirulislamhakim/s-book-social-backend/blob/main/src/app/v1/config/multer.config.ts): file pipeline · Multipart ingress and Cloudinary asset configuration. · `src/app/v1/config/multer.config.ts`
- [API response](https://github.com/jakirulislamhakim/s-book-social-backend/blob/main/src/app/v1/utils/sendApiResponse.ts): response helper · Standardized success and payload formatting. · `src/app/v1/utils/sendApiResponse.ts`

### Ops and assets

Background jobs, docs, templates, and public assets.

- [Cleanup job](https://github.com/jakirulislamhakim/s-book-social-backend/blob/main/src/app/v1/jobs/deleteUser.job.ts): background job · Delayed cleanup for soft-deleted users. · `src/app/v1/jobs/deleteUser.job.ts`
- [Email templates](https://github.com/jakirulislamhakim/s-book-social-backend/blob/main/src/app/v1/views/reset-password.hbs): rendering assets · Handlebars templates for outbound emails and documents. · `src/app/v1/views/reset-password.hbs`
- [API docs](https://github.com/jakirulislamhakim/s-book-social-backend/blob/main/src/docs/v1/swagger.yaml): openapi spec · Versioned Swagger documentation. · `src/docs/v1/swagger.yaml`

## Connections

- Server → App: boots · Process entrypoint initializes the app.
- App → App middleware: uses · App installs shared middleware.
- App → V1 routes: mounts · App exposes the versioned API router.
- V1 routes → Auth: routes · API router aggregates auth endpoints.
- V1 routes → User: routes · API router aggregates user endpoints.
- V1 routes → Post: routes · API router aggregates post endpoints.
- V1 routes → Social graph: routes · API router aggregates relationship/content-social endpoints.
- V1 routes → Notifications: routes · API router aggregates notification endpoints.
- V1 routes → Post appeals: routes · API router aggregates moderation appeal endpoints.
- Auth → Auth guard: protected by · Sensitive auth routes rely on authorization middleware where needed.
- Auth → API response: returns · Controllers emit standardized API responses.
- User → Query builder: lists with · User listings and search rely on the shared query abstraction.
- Post → Query builder: lists with · Post feeds and filtered queries use the shared query abstraction.
- Social graph → Auth guard: protected by · Relationship and content actions are access-controlled.
- Notifications → API response: returns · Notification endpoints use standardized responses.
- Post appeals → API response: returns · Moderation flows use standardized responses.
- App middleware → Error handler: delegates · Middleware stack funnels failures to global handling.
- Config → Upload storage: provides · Shared config feeds upload and storage setup.
- Cleanup job → Config: uses · Background cleanup depends on shared runtime configuration.
- Email templates → API response: supports · Rendered outbound content complements API delivery.
- API docs → V1 routes: documents · OpenAPI spec mirrors the versioned API surface.