Repository docs from .qoder/repowiki

Backend Architecture

Referenced Files in This Document

• server.ts
• app.ts
• index.ts
• controller.ts
• error.ts
• logger.ts
• security.ts
• rbac.ts
• auth.controller.ts
• auth.service.ts
• auth.repo.ts
• db/index.ts
• mail.service.ts
• socket/index.ts
• rate-limit.middleware.ts
• request-logging.middleware.ts
• error.middleware.ts
• context.middleware.ts
• inject-user.middleware.ts
• require-auth.middleware.ts
• require-permission.middleware.ts
• require-roles.middleware.ts
• stop-banned-user.middleware.ts
• require-user.middleware.ts
• require-terms.middleware.ts
• pipelines.ts
• multipart-upload.middleware.ts
• health.routes.ts

Table of Contents

1. Introduction
2. Project Structure
3. Core Components
4. Architecture Overview
5. Detailed Component Analysis
6. Dependency Analysis
7. Performance Considerations
8. Troubleshooting Guide
9. Conclusion

Introduction

This document describes the backend architecture of the Flick platform. It focuses on the Express.js application structure, the layered architecture pattern (controllers, services, repositories), the middleware pipeline, request/response flow, error handling, logging, security (authentication, authorization, rate limiting), and integration points with external systems such as Redis, PostgreSQL, and email providers. The backend is organized into modular business domains (e.g., auth, user, post, moderation, admin) that align with the routing structure.

Project Structure

The backend is implemented as a TypeScript/Express application bootstrapped in the server directory. The application initializes HTTP server, applies security and logging middleware, registers routes, and wires up domain modules. Routing is centralized and mounts domain-specific routers under API prefixes.

graph TB
A["server.ts<br/>Bootstrap server"] --> B["app.ts<br/>Create Express app"]
B --> C["config/security.ts<br/>Helmet + CORS"]
B --> D["core/middlewares/request-logging.middleware.ts<br/>Request logging"]
B --> E["routes/index.ts<br/>Register routes"]
E --> F["modules/*/route.ts<br/>Domain routers"]
B --> G["core/middlewares/error/error.middleware.ts<br/>Error handlers"]
B --> H["core/logger/logger.ts<br/>Winston logger"]

Diagram sources

• server.ts
• app.ts
• security.ts
• request-logging.middleware.ts
• index.ts
• logger.ts

Section sources

• server.ts
• app.ts
• index.ts

Core Components

• Express bootstrap and server lifecycle:
  • The server entry creates the Express app, initializes sockets, sets JSON/URL encoding, cookies, and registers middleware and routes.
• HTTP layer:
  • Controllers enforce a consistent return type via a decorator and handler that ensures HttpResponse instances are returned and sent to clients.
  • Centralized HttpError class encapsulates structured error responses with status codes, error codes, and optional metadata.
• Logging:
  • Winston-based logger configured for development vs production with colored output in dev and stack traces included.
• Security:
  • Helmet hardening, CORS configuration, and RBAC utilities for role-to-permission resolution.
• Middleware pipeline:
  • Context injection, request logging, authentication, authorization, rate limiting, multipart upload, and error handling.

Section sources

• server.ts
• app.ts
• controller.ts
• error.ts
• logger.ts
• security.ts
• rbac.ts

Architecture Overview

The backend follows a layered architecture:

• Presentation Layer: Express routes and controllers
• Application Layer: Services orchestrate business logic
• Domain Layer: Repositories abstract persistence
• Infrastructure Layer: DB, cache, mail, and socket integrations

graph TB
subgraph "Presentation"
R["routes/index.ts"]
C["modules/*/controller.ts"]
end
subgraph "Application"
S["modules/*/service.ts"]
end
subgraph "Domain"
Repo["modules/*/repo.ts"]
Adapters["infra/db/adapters/*"]
end
subgraph "Infrastructure"
DB["infra/db/index.ts<br/>PostgreSQL via Drizzle"]
Cache["Redis via cache service"]
Mail["infra/services/mail/*"]
Socket["infra/services/socket/*"]
end
R --> C
C --> S
S --> Repo
Repo --> Adapters
Adapters --> DB
S --> Cache
S --> Mail
S --> Socket

Diagram sources

• index.ts
• auth.controller.ts
• auth.service.ts
• auth.repo.ts
• db/index.ts
• mail.service.ts
• socket/index.ts

Detailed Component Analysis

Express Application Bootstrap and Middleware Pipeline

• Bootstrap:
  • server.ts initializes the HTTP server and logs startup.
  • app.ts configures Express, cookies, static files, security, logging, and routes.
• Middleware order and responsibilities:
  • Context middleware: enriches requests with runtime context.
  • Request logging: records request metadata.
  • Security: Helmet and CORS applied globally.
  • Routes: mounted under /api/v1/* and special auth passthrough.
  • Error handlers: 404 and general error middleware registered last.

sequenceDiagram
participant Client as "Client"
participant Express as "Express App"
participant Ctx as "Context Middleware"
participant Log as "Request Logger"
participant Sec as "Security (Helmet/CORS)"
participant Router as "Routes"
participant Ctrl as "Controller"
participant Svc as "Service"
participant DB as "DB/Cache/Mail"
Client->>Express : HTTP Request
Express->>Ctx : Inject context
Express->>Log : Log request
Express->>Sec : Apply security headers
Express->>Router : Match route
Router->>Ctrl : Invoke controller
Ctrl->>Svc : Business logic
Svc->>DB : Read/Write
DB-->>Svc : Result
Svc-->>Ctrl : Response
Ctrl-->>Express : HttpResponse
Express-->>Client : HTTP Response

Diagram sources

• server.ts
• app.ts
• context.middleware.ts
• request-logging.middleware.ts
• security.ts
• index.ts
• controller.ts
• auth.service.ts
• db/index.ts

Section sources

• server.ts
• app.ts
• index.ts

Authentication and Authorization Layer

• Authentication:
  • Uses Better Auth for session management, sign-up/sign-in, password reset, and OAuth callbacks.
  • OTP flows for initialization and login are integrated with Redis-backed caching and email provider.
• Authorization:
  • Role-based permission extraction utility computes effective permissions for a user’s roles.
  • Middleware guards enforce authentication, roles, permissions, terms acceptance, and banned user checks.

sequenceDiagram
participant Client as "Client"
participant Ctrl as "AuthController"
participant Svc as "AuthService"
participant BA as "Better Auth"
participant Cache as "Redis Cache"
participant Mail as "Mail Service"
participant DB as "PostgreSQL"
Client->>Ctrl : POST /api/v1/auth/login
Ctrl->>Svc : loginAuth(email, password)
Svc->>BA : signInEmail(...)
BA-->>Svc : Session headers
Svc->>Cache : Invalidate user caches
Svc->>DB : Load user profile
DB-->>Svc : Profile
Svc-->>Ctrl : {user, session}
Ctrl-->>Client : HttpResponse
Client->>Ctrl : POST /api/v1/auth/send-login-otp
Ctrl->>Svc : sendLoginOtp(email)
Svc->>Cache : Rate limit check
Svc->>Mail : Send OTP
Mail-->>Svc : Status
Svc->>Cache : Store hashed OTP
Svc-->>Ctrl : {success}
Ctrl-->>Client : HttpResponse

Diagram sources

• auth.controller.ts
• auth.service.ts
• rbac.ts
• inject-user.middleware.ts
• require-auth.middleware.ts
• require-permission.middleware.ts
• require-roles.middleware.ts
• stop-banned-user.middleware.ts
• require-user.middleware.ts
• require-terms.middleware.ts

Section sources

• auth.controller.ts
• auth.service.ts
• auth.repo.ts
• rbac.ts

Request/Response Flow and Error Handling

• Controllers:
  • Enforce HttpResponse return type via decorator and handler to prevent inconsistent responses.
• Services:
  • Perform business logic, interact with repositories, cache, DB, and external services.
  • Throw HttpError with structured metadata for client-friendly error payloads.
• Error middleware:
  • Converts HttpError to standardized JSON responses and handles non-HTTP exceptions.

flowchart TD
Start(["Controller invoked"]) --> Parse["Parse and validate input"]
Parse --> Valid{"Validation OK?"}
Valid --> |No| Err["Throw HttpError"]
Valid --> |Yes| CallSvc["Call Service"]
CallSvc --> OpOK{"Operation OK?"}
OpOK --> |No| Err
OpOK --> |Yes| BuildResp["Build HttpResponse"]
BuildResp --> Send["Send to client"]
Err --> ToJSON["Serialize to JSON"]
ToJSON --> Send

Diagram sources

• controller.ts
• error.ts
• error.middleware.ts

Section sources

• controller.ts
• error.ts

Logging System

• Winston logger:
  • Configured with timestamps, colored output in development, stack traces, and console transport.
  • Used across services for warnings, errors, and audit events.

Section sources

• logger.ts
• auth.service.ts

Security Architecture

• Transport and HTTP hardening:
  • Helmet and trusted proxy settings applied globally.
  • CORS configured via centralized options.
• Authentication:
  • Better Auth manages sessions, cookies, and OAuth.
  • OTP flows validated against cached tokens and rate-limited.
• Authorization:
  • RBAC resolves permissions from roles; middleware enforces roles and permissions.
• Rate limiting:
  • Dedicated middleware module provides rate-limit enforcement.

Section sources

• security.ts
• rbac.ts
• rate-limit.middleware.ts

Modular Design and Domain Modules

• Routing:
  • Central route registry mounts domain routers under /api/v1/* and exposes Better Auth passthrough.
• Examples:
  • Auth module: controllers, services, repositories, schemas, and cache keys.
  • Other modules (user, post, vote, bookmark, comment, feedback, moderation, admin) follow the same pattern.

graph LR
R["routes/index.ts"] --> A["/api/v1/auth"]
R --> U["/api/v1/users"]
R --> P["/api/v1/posts"]
R --> V["/api/v1/votes"]
R --> B["/api/v1/bookmarks"]
R --> C["/api/v1/comments"]
R --> F["/api/v1/feedbacks"]
R --> M["/api/v1/moderation/*"]
R --> AD["/api/v1/admin/*"]
R --> OA["/api/auth/*"]

Diagram sources

• index.ts

Section sources

• index.ts

Data Flow Patterns and Integrations

• Database:
  • Drizzle ORM connects to PostgreSQL; schema includes tables for auth, users, posts, comments, votes, bookmarks, feedbacks, notifications, audit logs, colleges, branches, and college requests.
• Cache:
  • Redis-backed cache used for OTP, pending signups, user profiles, and session data.
• Email:
  • Mail service abstraction integrates with external providers for OTP delivery.
• Socket:
  • Socket service initialization on server startup.

graph TB
Svc["AuthService"] --> Cache["Redis Cache"]
Svc --> DB["PostgreSQL via Drizzle"]
Svc --> Mail["Mail Service"]
Svc --> BA["Better Auth"]
Sock["Socket Service"] --> |init| Server["HTTP Server"]

Diagram sources

• auth.service.ts
• db/index.ts
• mail.service.ts
• socket/index.ts

Section sources

• db/index.ts
• auth.service.ts

Dependency Analysis

• Internal dependencies:
  • Controllers depend on Services.
  • Services depend on Repositories and Infra (DB, Cache, Mail).
  • Repositories depend on DB adapters.
• External dependencies:
  • Express, Helmet, CORS, Drizzle, Better Auth, Winston, Redis, and mail provider SDKs.
• Coupling:
  • Modules are loosely coupled via clear boundaries (controller -> service -> repo -> adapter -> DB).
  • Middleware composition enables cross-cutting concerns without tight coupling.

graph TB
Ctrl["AuthController"] --> Svc["AuthService"]
Svc --> Repo["AuthRepo"]
Repo --> Adapters["DB Adapters"]
Adapters --> DB["PostgreSQL"]
Svc --> Cache["Redis"]
Svc --> Mail["Mail Service"]
Svc --> BA["Better Auth"]

Diagram sources

• auth.controller.ts
• auth.service.ts
• auth.repo.ts
• db/index.ts

Section sources

• auth.controller.ts
• auth.service.ts
• auth.repo.ts
• db/index.ts

Performance Considerations

• Caching:
  • Use Redis for OTP, pending signups, and user profiles to reduce DB load and latency.
• DB:
  • Prefer indexed lookups and batched operations where applicable; leverage Drizzle’s query builder for correctness and performance.
• Logging:
  • Keep log levels appropriate to environment; avoid excessive debug logs in production.
• Middleware:
  • Place fast-fail middleware early (e.g., rate limiting) to minimize downstream work.

Troubleshooting Guide

• Startup failures:
  • Check server bootstrap logs and error event handling.
• Authentication issues:
  • Verify Better Auth configuration, session cookies, and OTP cache TTLs.
• Database connectivity:
  • Confirm DATABASE_URL and Drizzle schema registration.
• Logging:
  • Ensure Winston transports and format match environment expectations.
• Health checks:
  • Use health routes to validate service readiness.

Section sources

• server.ts
• auth.service.ts
• db/index.ts
• logger.ts
• health.routes.ts

Conclusion

The Flick backend employs a clean, layered architecture with explicit separation of concerns. Express serves as the presentation layer, controllers enforce consistent responses, services encapsulate business logic, and repositories abstract persistence. Security is enforced via Helmet, CORS, RBAC, and middleware guards. Redis, PostgreSQL, and email providers integrate seamlessly through dedicated infrastructure services. The modular routing structure supports scalable growth across business domains while maintaining a cohesive middleware pipeline for logging, rate limiting, and error handling.