# slantie/reflectify-backend architecture

> Architecture diagram of the GitHub repository slantie/reflectify-backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/slantie/reflectify-backend
- Repository: https://github.com/slantie/reflectify-backend

## Overview

##### Project type and purpose
- Reflectify is a Node.js/TypeScript monolithic backend API for managing feedback in educational institutions.
- It exposes REST endpoints under `/api/v1` for academic structures, authentication, feedback forms, analytics, email queuing, and uploads.
- Key features: role-based JWT auth, service-to-service API keys, Prisma ORM with PostgreSQL, Redis+BullMQ email queue, Gmail SMTP fallback, Zod validation, and rate limiting.

##### File structure
- `src/api/v1/routes` → Express route definitions, organized by resource (auth, academicYear, feedbackForm, analytics, etc.)
- `src/controllers/*` → HTTP handlers invoking business logic
- `src/services/*` → Core application logic, database access via `PrismaService` plus integrations (email queue, Redis, SMTP)
- `src/middlewares` → Authentication (JWT and service-API-key), error handling, request validation
- `src/utils` → Shared utilities (error wrapper, async handler, JWT helper, hashing, templates, scheduler, validators)
- `prisma/schema.prisma` → Data model for PostgreSQL, including `OverrideStudent` replacing legacy `Student`
- Config folder → Environment and CORS settings
- Build/deploy files: `tsconfig.json`, `package.json`, `.env.example`, `server.ts`

##### README for additional insights
- Critical change: all student data now uses `OverrideStudent` model
- Email queue: Redis + BullMQ, rate-limit 1 mail/4s, 5 retries, fallback SMTP
- Auth: JWT for admins/faculty, token for student submissions, API-key for internal services
- External dependencies: PostgreSQL, Redis, Gmail SMTP
- Security: Helmet, CORS, Zod validation, Prisma (SQL injection protection), rate limiting

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    subgraph "Clients"
        direction TB
        AdminUI["Admin SPA"]:::ext
        StudentUI["Student Form"]:::ext
        ServiceClient["Service Client"]:::ext
    end

    %% API Layer
    subgraph "API Layer" 
        direction TB
        subgraph "Routes" 
            direction TB
            AuthRoutes["Auth Routes"]:::api
            AcadYearRoutes["AcademicYear Routes"]:::api
            FeedbackRoutes["FeedbackForm Routes"]:::api
            AnalyticsRoutes["Analytics Routes"]:::api
            EmailRoutes["Email Routes"]:::api
            UploadRoutes["Upload Routes"]:::api
        end

        subgraph "Middlewares"
            direction TB
            JWTAuth["JWT Authentication"]:::middleware
            APIKeyAuth["Service API-Key Auth"]:::middleware
            Validation["Request Validation"]:::middleware
            ErrorHandler["Error Handler"]:::middleware
            RateLimiter["Rate Limiter"]:::middleware
        end
    end

    %% Application Layer
    subgraph "Controllers" 
        direction TB
        AuthCtrl["Auth Controller"]:::app
        AcadCtrl["AcademicYear Controller"]:::app
        FeedbackCtrl["FeedbackForm Controller"]:::app
        AnalyticsCtrl["Analytics Controller"]:::app
        EmailCtrl["Email Controller"]:::app
        UploadCtrl["Upload Controller"]:::app
        OverrideCtrl["OverrideStudent Controller"]:::app
    end

    %% Domain Layer
    subgraph "Services"
        direction TB
        AuthSvc["Auth Service"]:::svc
        AcadSvc["AcademicYear Service"]:::svc
        FeedbackSvc["FeedbackForm Service"]:::svc
        AnalyticsSvc["Analytics Service"]:::svc
        QueueSvc["Email Queue Service"]:::svc
        WorkerSvc["Email Worker Service"]:::svc
        FallbackSvc["Email Fallback (SMTP)"]:::svc
        OverrideSvc["OverrideStudent Service"]:::svc
        PrismaSvc["PrismaService"]:::svc
    end

    %% Infrastructure Layer
    subgraph "Data Stores"
        direction TB
        PostgresDB["PostgreSQL"]:::db
        RedisQueue["Redis (BullMQ Queue)"]:::db
    end

    %% External Services
    subgraph "External"
        direction TB
        Gmail["Gmail SMTP"]:::ext
    end

    %% Connections
    AdminUI -->|calls| AuthRoutes
    StudentUI -->|calls| FeedbackRoutes
    ServiceClient -->|calls| AuthRoutes
    ServiceClient -->|calls| AnalyticsRoutes

    %% Routes to Middleware
    AuthRoutes -->|through| JWTAuth
    AcadYearRoutes -->|through| JWTAuth
    FeedbackRoutes -->|through| JWTAuth
    AnalyticsRoutes -->|through| APIKeyAuth
    EmailRoutes -->|through| JWTAuth
    UploadRoutes -->|through| JWTAuth

    %% Middleware chain
    JWTAuth --> Validation
    APIKeyAuth --> Validation
    Validation --> RateLimiter
    RateLimiter --> ErrorHandler

    %% Middleware to Controllers
    ErrorHandler --> AuthCtrl
    ErrorHandler --> AcadCtrl
    ErrorHandler --> FeedbackCtrl
    ErrorHandler --> AnalyticsCtrl
    ErrorHandler --> EmailCtrl
    ErrorHandler --> UploadCtrl
    ErrorHandler --> OverrideCtrl

    %% Controllers to Services
    AuthCtrl --> AuthSvc
    AcadCtrl --> AcadSvc
    FeedbackCtrl --> FeedbackSvc
    AnalyticsCtrl --> AnalyticsSvc
    EmailCtrl --> QueueSvc
    UploadCtrl --> OverrideSvc
    OverrideCtrl --> OverrideSvc

    %% Services to infra
    AuthSvc --> PrismaSvc
    AcadSvc --> PrismaSvc
    FeedbackSvc --> PrismaSvc
    AnalyticsSvc --> PrismaSvc
    OverrideSvc --> PrismaSvc

    QueueSvc --> RedisQueue
    WorkerSvc --> RedisQueue
    WorkerSvc -->|on failure| FallbackSvc

    PrismaSvc --> PostgresDB
    FallbackSvc -->|smtp| Gmail

    %% Click Events - Routes
    click AuthRoutes "https://github.com/slantie/reflectify-backend/blob/main/src/api/v1/routes/auth/auth.routes.ts"
    click AcadYearRoutes "https://github.com/slantie/reflectify-backend/blob/main/src/api/v1/routes/academicYear/academicYear.routes.ts"
    click FeedbackRoutes "https://github.com/slantie/reflectify-backend/blob/main/src/api/v1/routes/feedbackForm/feedbackForm.routes.ts"
    click AnalyticsRoutes "https://github.com/slantie/reflectify-backend/blob/main/src/api/v1/routes/analytics/analytics.routes.ts"
    click EmailRoutes "https://github.com/slantie/reflectify-backend/blob/main/src/api/v1/routes/email/email.routes.ts"
    click UploadRoutes "https://github.com/slantie/reflectify-backend/blob/main/src/api/v1/routes/upload/upload.routes.ts"
    click AcademicyearRoutes "https://github.com/slantie/reflectify-backend/blob/main/src/api/v1/routes/academicYear/academicYear.routes.ts"

    %% Click Events - Middlewares
    click JWTAuth "https://github.com/slantie/reflectify-backend/blob/main/src/middlewares/auth.middleware.ts"
    click APIKeyAuth "https://github.com/slantie/reflectify-backend/blob/main/src/middlewares/serviceAuth.middleware.ts"
    click ErrorHandler "https://github.com/slantie/reflectify-backend/blob/main/src/utils/asyncHandler.ts"

    %% Click Events - Controllers
    click AuthCtrl "https://github.com/slantie/reflectify-backend/blob/main/src/controllers/auth/auth.controller.ts"
    click AcadCtrl "https://github.com/slantie/reflectify-backend/blob/main/src/controllers/academicYear/academicYear.controller.ts"
    click FeedbackCtrl "https://github.com/slantie/reflectify-backend/blob/main/src/controllers/feedbackForm/feedbackForm.controller.ts"
    click AnalyticsCtrl "https://github.com/slantie/reflectify-backend/blob/main/src/controllers/analytics/analytics.controller.ts"
    click EmailCtrl "https://github.com/slantie/reflectify-backend/blob/main/src/controllers/email/email.controller.ts"
    click UploadCtrl "https://github.com/slantie/reflectify-backend/blob/main/src/controllers/upload/studentData.controller.ts"
    click OverrideCtrl "https://github.com/slantie/reflectify-backend/blob/main/src/controllers/overrideStudents/overrideStudents.controller.ts"

    %% Click Events - Services
    click AuthSvc "https://github.com/slantie/reflectify-backend/blob/main/src/services/auth/auth.service.ts"
    click AcadSvc "https://github.com/slantie/reflectify-backend/blob/main/src/services/academicYear/academicYear.service.ts"
    click FeedbackSvc "https://github.com/slantie/reflectify-backend/blob/main/src/services/feedbackForm/feedbackForm.service.ts"
    click AnalyticsSvc "https://github.com/slantie/reflectify-backend/blob/main/src/services/analytics/analytics.service.ts"
    click QueueSvc "https://github.com/slantie/reflectify-backend/blob/main/src/services/email/queue.ts"
    click WorkerSvc "https://github.com/slantie/reflectify-backend/blob/main/src/services/email/worker.ts"
    click FallbackSvc "https://github.com/slantie/reflectify-backend/blob/main/src/services/email/fallback.service.ts"
    click OverrideSvc "https://github.com/slantie/reflectify-backend/blob/main/src/services/overrideStudents/overrideStudents.service.ts"
    click PrismaSvc "https://github.com/slantie/reflectify-backend/blob/main/src/services/common/prisma.service.ts"

    %% Click Events - Data Model
    click PostgresDB "https://github.com/slantie/reflectify-backend/blob/main/prisma/schema.prisma"

    %% Click Events - Utils
    click Validation "https://github.com/slantie/reflectify-backend/blob/main/src/utils/validators/auth.validation.ts"
    click Validation "https://github.com/slantie/reflectify-backend/blob/main/src/utils/validators/feedbackForm.validation.ts"

    %% Styles
    classDef api fill:#A5D0E6,stroke:#333,stroke-width:1px
    classDef middleware fill:#E6D0A5,stroke:#333,stroke-width:1px
    classDef app fill:#D0E6A5,stroke:#333,stroke-width:1px
    classDef svc fill:#E6A5D0,stroke:#333,stroke-width:1px
    classDef db fill:#A5E6A5,stroke:#333,stroke-width:1px
    classDef ext fill:#E6A5A5,stroke:#333,stroke-width:1px
```
