How jakirulislamhakim/s-book-social-backend works
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: v1Routes.ts V1 routes · sendApiResponse.ts API response · app.ts App · auth.route.ts Auth
Components 19
Runtime shell
Process entrypoint and app bootstrap.
HTTP platform
Versioned routing, middleware, and request lifecycle concerns.
- V1 routes · Composes the versioned API surface.
src/app/v1/routes/v1Routes.ts - App middleware · Wires shared HTTP middleware into the app.
src/app/v1/middlewares/appMiddleware.ts - Auth guard · Protects routes and enforces authenticated access.
src/app/v1/middlewares/auth.ts - Error handler · Normalizes and formats application errors.
src/app/v1/middlewares/globalErrorHandler.ts
Domain modules
Feature-based API modules for social content and relationships.
- Auth · JWT login, refresh, verification, and password flows.
src/app/v1/modules/Auth/auth.route.ts - User · User lifecycle, profile ownership, and account state.
src/app/v1/modules/User/user.route.ts - Post · Core post creation, listing, and visibility logic.
src/app/v1/modules/Post/post.route.ts - Social graph · Friend, block, comment, reaction, and story relationships.
src/app/v1/modules/Friend/friend.route.ts - Notifications · Notification creation and delivery for social actions.
src/app/v1/modules/Notification/notification.route.ts - Post appeals · 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 · Shared filtering, sorting, pagination, and search helper.
src/app/v1/builder/QueryBuilder.ts - Config · Loads shared environment and service configuration.
src/app/v1/config/index.ts - Upload storage · Multipart ingress and Cloudinary asset configuration.
src/app/v1/config/multer.config.ts - API response · Standardized success and payload formatting.
src/app/v1/utils/sendApiResponse.ts
Ops and assets
Background jobs, docs, templates, and public assets.
- Cleanup job · Delayed cleanup for soft-deleted users.
src/app/v1/jobs/deleteUser.job.ts - Email templates · Handlebars templates for outbound emails and documents.
src/app/v1/views/reset-password.hbs - API docs · Versioned Swagger documentation.
src/docs/v1/swagger.yaml
Connections 21
- 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.