How nus-crisp/crisp works
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