How health-it-club/qcmcalc works
Project Type and Purpose
• This is a front-end-centric, page-based web application built with Next.js (React + TypeScript) for calculating grades on QCM (Multiple Choice Questions) exams.
• There is no separate backend service—data comes from local JSON files and computations run in-browser using React components and utility logic.
File Structure
• app/ → Next.js “app router” pages and layouts
• AppComponents/ → Custom shared UI elements & business logic (calculator, checkboxGroup)
• components/ → Published UI component libraries (MagicUI, Shadcn-style “ui” widgets)
• data/ → TypeScript definitions and exam metadata (exams.ts)
• lib/ → Utility functions (utils.ts)
• public/ → Static assets and JSON templates
• .github/ → CI/CD workflows (deploy.yml)
• config files → next.config.mjs, postcss.config.mjs, tsconfig.json
Key Architecture Insights from README
• Presentation: Next.js + Tailwind CSS + Headless UI + React Hook Form
• State: Context API and Recoil
• Logic: calculator.tsx handles grading algorithms
• Deployment: Vercel / GitHub Pages via GitHub Actions
Main Components and Their Relationships
A. User Browser
• Sends HTTP(S) requests → Next.js host
• Renders HTML/CSS/JS UI; interacts via forms and buttons
B. Next.js Hosting Layer (Vercel / GitHub Pages)
• Serves pre-rendered pages (SSG/SSR) from app/
• Delivers static assets from public/
• Runs GitHub Actions CI/CD for build & deploy
C. Presentation Layer (app/ + AppComponents/UI + components/ui + components/magicui)
• Pages & Layouts (app/page.tsx, app/layout.tsx)
• Feature pages (ConstantineExams, HowDoesItWork, Home)
• Shared UI components (CustomButton, Accordion, dropdowns, interactive buttons)
D. State Management Layer (Context + Recoil)
• Global form state (number of questions, selected exam, correction type)
• Synchronizes user inputs across components
E. Business Logic Layer (AppComponents/logic + lib/utils.ts)
• calculator.tsx: grading algorithms for different QCM scoring methods
• checkboxGroup.tsx: selection grouping logic
• utils.ts: helper functions (e.g., normalization, scoring helpers)
F. Data Layer
• data/exams.ts & public/data/exams.json
• Type definitions (data/types.ts)
• Static data read at build time or runtime (import or fetch)
G. External Libraries & Tools
• Tailwind CSS for styling (postcss.config.mjs)
• Headless UI, React Hook Form for accessible components and validation
• MagicUI & Shadcn pattern libraries for custom-themed widgets
H. CI/CD & Infrastructure
• GitHub Actions workflow (.github/workflows/deploy.yml)
• Vercel deployment (automatic on push to main)
• Optional GitHub Pages via package.json scripts
Architectural Patterns & Design Principles
• Component-Based Architecture: small reusable UI blocks in AppComponents/UI and components/ui
• File-Based Routing: Next.js app router organizes pages under app/
• Separation of Concerns: clear layers for Presentation → State → Logic → Data
• Static-First Deployment: leverage SSG/ISR for performance, minimal runtime backend
• Context + Recoil for predictable state across nested components