# nus-crisp/crisp architecture

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

- Interactive diagram: https://gitdiagram.com/nus-crisp/crisp
- Repository: https://github.com/nus-crisp/crisp

## Overview

##### Project Type and Purpose
- CRISP is a full-stack web application comprising:
- A React/Next.js frontend (“multi-git-dashboard”)
- A TypeScript/Express backend API (“backend”)
- A MongoDB datastore (“mongo”)
- Shared TypeScript types used by both frontend and backend
- Various scheduled background jobs to fetch and process data
- DevOps orchestration via Docker, NGINX, GitHub Actions and Jenkins

##### Key Architectural Components
a. Frontend (multi-git-dashboard)
- Next.js application serving UI routes and NextAuth API routes
- Components (pages/, components/) fetch data from the backend REST API
- Uses shared/types for DTOs and domain models
b. Backend API (backend/app.ts)
- Express app with controllers → services → models layers
- Clients for external integrations: GitHub, Jira, Google Sheets, email, Telegram
- Scheduled “jobs” (aiInsightsJob, githubJob, jiraJob, etc.) triggered by cron or a job scheduler
- Authentication middleware, error handling, metrics collection
c. Database
- MongoDB container storing domain data (Account, Course, Assessment, Submission, Team, etc.)
d. External Services
- GitHub REST/GraphQL APIs
- Jira API
- Google Sheets API
- Email & Telegram notification channels
- Trofos, public GitHub scanning, tutorial data sources
e. DevOps & Deployment
- Docker Compose orchestrates containers: nginx, frontend, backend, mongo
- NGINX reverse proxy routes “/api” to backend, “/” to frontend
- CI pipelines (GitHub Actions for frontend and backend tests; Jenkins for full-stack deploy)
- Load-test scripts (JMeter), devops/docker files, Jenkinsfile

##### Relationships & Data Flow
- Browser → (HTTPS) → NGINX
- “/” → Next.js Frontend
- “/api/*” → Express Backend
- Frontend ↔ Backend
- REST calls (GET/POST) using shared type definitions
- Backend ↔ MongoDB
- Mongoose or native driver reads/writes domain collections
- Backend ↔ External Services
- On-demand via controllers/services
- Periodic via background jobs
- Notifications
- Backend → EmailClient / TelegramClient
- CI/CD
- Code push → GitHub Actions → build/test containers → deploy via Jenkins → Docker Compose

##### Architectural Patterns & Principles
- Layered architecture (Controller → Service → Data Model) in backend
- Containerization for isolation (Docker for each component)
- Reverse proxy pattern (NGINX routing)
- Shared-code approach (shared/types package) to enforce type safety end-to-end
- Cron-style background jobs for asynchronous data ingestion

##### Final Checklist
- Notation for background job pipelines separately from request/response flows

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global entities
    Browser["Browser"]:::external
    NGINX["NGINX\nReverse Proxy"]:::proxy
    subgraph "Frontend (UI Layer)"
        direction TB
        FE["Next.js App\nmulti-git-dashboard/"]:::frontend
        FE_PAGES["Pages & API Routes\nsrc/pages/"]:::frontend
        FE_COMPONENTS["Components\nsrc/components/"]:::frontend
        FE_STYLES["Styles\nsrc/styles/"]:::frontend
        FE_LIB["Middleware & Lib\nsrc/middleware.ts\nsrc/lib/"]:::frontend
        FE_SHARED["Shared Types\nshared/types/"]:::frontend
    end
    subgraph "Backend (API Server)"
        direction TB
        BE_APP["Express App\nbackend/app.ts"]:::backend
        BE_CONTROLLERS["Controllers\nbackend/controllers/"]:::backend
        BE_SERVICES["Services\nbackend/services/"]:::backend
        BE_MODELS["Data Models\nbackend/models/"]:::backend
        BE_ROUTES["Routes\nbackend/routes/"]:::backend
        BE_MW["Middleware\nbackend/middleware/"]:::backend
        BE_JOBS["Background Jobs\nbackend/jobs/"]:::backend
        BE_CLIENTS["External Clients\nbackend/clients/"]:::backend
        BE_UTILS["Utilities\nbackend/utils/"]:::backend
        BE_SHARED["Shared Types\nshared/types/"]:::backend
    end
    MongoDB[("MongoDB\nData Store")]:::db
    subgraph "External Services"
        direction TB
        ES_GH["GitHub API"]:::external
        ES_JIRA["Jira API"]:::external
        ES_SHEETS["Google Sheets API"]:::external
        ES_EMAIL["Email Server"]:::external
        ES_TELEGRAM["Telegram"]:::external
        ES_OTHER["Other Sources"]:::external
    end

    %% Data Flows
    Browser -->|"HTTPS 443"| NGINX
    NGINX -->|"/"| FE
    NGINX -->|"/api/*"| BE_APP

    FE -->|"REST API 3001"| BE_APP
    FE --> FE_PAGES
    FE --> FE_COMPONENTS
    FE --> FE_STYLES
    FE --> FE_LIB
    FE --> FE_SHARED

    BE_APP --> BE_ROUTES
    BE_ROUTES --> BE_CONTROLLERS
    BE_CONTROLLERS --> BE_SERVICES
    BE_SERVICES --> BE_MODELS
    BE_MODELS --> MongoDB
    BE_SERVICES --> BE_CLIENTS
    BE_APP --> BE_MW
    BE_APP --> BE_UTILS
    BE_APP --> BE_SHARED

    BE_JOBS --> ES_GH
    BE_JOBS --> ES_JIRA
    BE_JOBS --> ES_SHEETS
    BE_JOBS --> ES_EMAIL
    BE_JOBS --> ES_TELEGRAM
    BE_JOBS --> ES_OTHER
    ES_GH --> BE_APP
    ES_JIRA --> BE_APP
    ES_SHEETS --> BE_APP
    ES_EMAIL --> BE_APP
    ES_TELEGRAM --> BE_APP
    ES_OTHER --> BE_APP
    BE_APP --> MongoDB

    %% Click Events
    click FE "https://github.com/nus-crisp/crisp/tree/main/multi-git-dashboard/"
    click FE_PAGES "https://github.com/nus-crisp/crisp/tree/main/multi-git-dashboard/src/pages/"
    click FE_COMPONENTS "https://github.com/nus-crisp/crisp/tree/main/multi-git-dashboard/src/components/"
    click FE_STYLES "https://github.com/nus-crisp/crisp/tree/main/multi-git-dashboard/src/styles/"
    click FE_LIB "https://github.com/nus-crisp/crisp/blob/main/multi-git-dashboard/src/middleware.ts"
    click FE_LIB "https://github.com/nus-crisp/crisp/tree/main/multi-git-dashboard/src/lib/"
    click BE_APP "https://github.com/nus-crisp/crisp/blob/main/backend/app.ts"
    click BE_CONTROLLERS "https://github.com/nus-crisp/crisp/tree/main/backend/controllers/"
    click BE_SERVICES "https://github.com/nus-crisp/crisp/tree/main/backend/services/"
    click BE_MODELS "https://github.com/nus-crisp/crisp/tree/main/backend/models/"
    click BE_ROUTES "https://github.com/nus-crisp/crisp/tree/main/backend/routes/"
    click BE_MW "https://github.com/nus-crisp/crisp/tree/main/backend/middleware/"
    click BE_JOBS "https://github.com/nus-crisp/crisp/tree/main/backend/jobs/"
    click BE_CLIENTS "https://github.com/nus-crisp/crisp/tree/main/backend/clients/"
    click BE_UTILS "https://github.com/nus-crisp/crisp/tree/main/backend/utils/"
    click BE_SHARED "https://github.com/nus-crisp/crisp/tree/main/shared/types/"
    click MongoDB "https://github.com/nus-crisp/crisp/tree/main/mongo/Dockerfile"
    click MongoDB "https://github.com/nus-crisp/crisp/blob/main/mongo/mongo-initdb.js"
    click NGINX "https://github.com/nus-crisp/crisp/tree/main/nginx/Dockerfile"
    click NGINX "https://github.com/nus-crisp/crisp/blob/main/nginx/default.conf"
    click .github "https://github.com/nus-crisp/crisp/blob/main/ .github/workflows/backend-ci.yml"
    click .github "https://github.com/nus-crisp/crisp/blob/main/ .github/workflows/frontend-ci.yml"
    click Jenkinsfile "https://github.com/nus-crisp/crisp/tree/main/devops/Jenkinsfile"
    click DC "https://github.com/nus-crisp/crisp/blob/main/docker-compose.yml"
    click DC "https://github.com/nus-crisp/crisp/blob/main/devops/docker-compose.yml"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef backend fill:#90EE90,stroke:#000,stroke-width:1px
    classDef db fill:#FFA500,stroke:#000,stroke-width:1px
    classDef proxy fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef external fill:#FFFF99,stroke:#000,stroke-width:1px
```
