# health-it-club/qcmcalc architecture

> Architecture diagram of the GitHub repository health-it-club/qcmcalc, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/health-it-club/qcmcalc
- Repository: https://github.com/health-it-club/qcmcalc

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "User Browser"
        Browser["User Browser"]:::infra
    end

    subgraph "Next.js Hosting Layer"
        NextServer["Next.js Server (Vercel/GH Pages)"]:::infra
        StaticAssets["Static Assets (public/)"]:::infra
    end

    subgraph "Presentation Layer"
        Layout["Root Layout"]:::presentation
        GlobalsCSS["Global Styles"]:::presentation

        subgraph "Home Feature"
            HomePage["Home Page"]:::presentation
            MainSection["Main Section"]:::presentation
            NumQuestions["NumberOfQuestions Input"]:::presentation
            TypeCorrection["TypeOfCorrection Selector"]:::presentation
        end

        subgraph "ConstantineExams Feature"
            ConstExamsPage["ConstantineExams Page"]:::presentation
            ExamPage["Page Content"]:::presentation
            ExamForm["Exam Form"]:::presentation
            ExamSelector["Exam Selector"]:::presentation
            GradeSelector["Grade Selector"]:::presentation
            SpecSelector["Speciality Selector"]:::presentation
            YearSelector["Year Selector"]:::presentation
        end

        subgraph "HowDoesItWork Feature"
            HowPage["HowDoesItWork Page"]:::presentation
            HowLanding["Landing Section"]:::presentation
        end

        subgraph "UI Libraries"
            CustomButton["CustomButton"]:::presentation
            CustomAccordion["CustomAccordion"]:::presentation
            IconButton["IconButton"]:::presentation
            Background["Background"]:::presentation
            NavBar["NavigationBar"]:::presentation
            FlickerGrid["FlickeringGrid"]:::presentation
            HoverButton["InteractiveHoverButton"]:::presentation
            SparklesText["SparklesText"]:::presentation
            UIAccordion["UI Accordion"]:::presentation
            UIButton["UI Button"]:::presentation
            UIDropdown["UI Dropdown"]:::presentation
            UIInput["UI Input"]:::presentation
            UILabel["UI Label"]:::presentation
        end
    end

    subgraph "State Management Layer"
        StateMgr["Context & Recoil Store"]:::stateLogic
    end

    subgraph "Business Logic Layer"
        Calculator["Grading Algorithms"]:::stateLogic
        CheckboxGroup["Checkbox Group Logic"]:::stateLogic
        Utils["Utility Functions"]:::stateLogic
    end

    subgraph "Data Layer"
        ExamsJSON["exams.json"]:::data
        ExamsTS["exams.ts"]:::data
        TypesTS["types.ts"]:::data
    end

    subgraph "CI/CD & Infrastructure"
        GitHub["GitHub Repo"]:::infra
        DeployYML["deploy.yml"]:::infra
        NextConfig["next.config.mjs"]:::infra
        PostCSS["postcss.config.mjs"]:::infra
        TSConfig["tsconfig.json"]:::infra
        Vercel["Vercel"]:::infra
    end

    Browser -->|Request Pages| NextServer
    NextServer -->|Serve Pages| Layout
    NextServer -->|Serve Static| StaticAssets

    Layout --> GlobalsCSS
    Layout --> HomePage
    Layout --> ConstExamsPage
    Layout --> HowPage
    HomePage --> MainSection
    MainSection --> NumQuestions
    MainSection --> TypeCorrection

    ConstExamsPage --> ExamPage
    ExamPage --> ExamForm
    ExamPage --> ExamSelector
    ExamPage --> GradeSelector
    ExamPage --> SpecSelector
    ExamPage --> YearSelector

    HowPage --> HowLanding

    HomePage --> StateMgr
    ConstExamsPage --> StateMgr

    StateMgr --> Calculator
    StateMgr --> CheckboxGroup

    Calculator --> Utils
    Calculator --> ExamsTS
    ExamsTS --> ExamsJSON
    ExamsTS --> TypesTS

    GitHub --> DeployYML
    DeployYML --> NextServer
    DeployYML --> Vercel

    click Layout "https://github.com/health-it-club/qcmcalc/blob/main/app/layout.tsx"
    click GlobalsCSS "https://github.com/health-it-club/qcmcalc/blob/main/app/globals.css"
    click HomePage "https://github.com/health-it-club/qcmcalc/blob/main/app/page.tsx"
    click ConstExamsPage "https://github.com/health-it-club/qcmcalc/blob/main/app/ConstantineExams/page.tsx"
    click ExamForm "https://github.com/health-it-club/qcmcalc/blob/main/app/ConstantineExams/examForm.tsx"
    click ExamSelector "https://github.com/health-it-club/qcmcalc/blob/main/app/ConstantineExams/examSelector.tsx"
    click GradeSelector "https://github.com/health-it-club/qcmcalc/blob/main/app/ConstantineExams/gradeSelector.tsx"
    click SpecSelector "https://github.com/health-it-club/qcmcalc/blob/main/app/ConstantineExams/specialitySelector.tsx"
    click YearSelector "https://github.com/health-it-club/qcmcalc/blob/main/app/ConstantineExams/yearSelector.tsx"
    click ExamPage "https://github.com/health-it-club/qcmcalc/blob/main/app/ConstantineExams/examPageContent.tsx"
    click HowPage "https://github.com/health-it-club/qcmcalc/blob/main/app/HowDoesItWork/page.tsx"
    click HowLanding "https://github.com/health-it-club/qcmcalc/blob/main/app/HowDoesItWork/HowDoesItWorkLanding.tsx"
    click MainSection "https://github.com/health-it-club/qcmcalc/blob/main/app/home/MainSection.tsx"
    click NumQuestions "https://github.com/health-it-club/qcmcalc/blob/main/app/home/numbreOfQuestions.tsx"
    click TypeCorrection "https://github.com/health-it-club/qcmcalc/blob/main/app/home/typeOfCorrection.tsx"
    click CustomButton "https://github.com/health-it-club/qcmcalc/blob/main/AppComponents/UI/CustomButton.tsx"
    click CustomAccordion "https://github.com/health-it-club/qcmcalc/blob/main/AppComponents/UI/CustomAccordion.tsx"
    click IconButton "https://github.com/health-it-club/qcmcalc/blob/main/AppComponents/UI/IconButton.tsx"
    click Background "https://github.com/health-it-club/qcmcalc/blob/main/AppComponents/UI/background.tsx"
    click NavBar "https://github.com/health-it-club/qcmcalc/blob/main/AppComponents/navigation/navigationBar.tsx"
    click FlickerGrid "https://github.com/health-it-club/qcmcalc/blob/main/components/magicui/flickering-grid.tsx"
    click HoverButton "https://github.com/health-it-club/qcmcalc/blob/main/components/magicui/interactive-hover-button.tsx"
    click SparklesText "https://github.com/health-it-club/qcmcalc/blob/main/components/magicui/sparkles-text.tsx"
    click UIAccordion "https://github.com/health-it-club/qcmcalc/blob/main/components/ui/accordion.tsx"
    click UIButton "https://github.com/health-it-club/qcmcalc/blob/main/components/ui/button.tsx"
    click UIDropdown "https://github.com/health-it-club/qcmcalc/blob/main/components/ui/dropdown-menu.tsx"
    click UIInput "https://github.com/health-it-club/qcmcalc/blob/main/components/ui/input.tsx"
    click UILabel "https://github.com/health-it-club/qcmcalc/blob/main/components/ui/label.tsx"
    click Calculator "https://github.com/health-it-club/qcmcalc/blob/main/AppComponents/logic/calculator.tsx"
    click CheckboxGroup "https://github.com/health-it-club/qcmcalc/blob/main/AppComponents/logic/checkboxGroup.tsx"
    click Utils "https://github.com/health-it-club/qcmcalc/blob/main/lib/utils.ts"
    click ExamsTS "https://github.com/health-it-club/qcmcalc/blob/main/data/exams.ts"
    click TypesTS "https://github.com/health-it-club/qcmcalc/blob/main/data/types.ts"
    click ExamsJSON "https://github.com/health-it-club/qcmcalc/blob/main/public/data/exams.json"
    click DeployYML "https://github.com/health-it-club/qcmcalc/blob/main/.github/workflows/deploy.yml"
    click NextConfig "https://github.com/health-it-club/qcmcalc/blob/main/next.config.mjs"
    click PostCSS "https://github.com/health-it-club/qcmcalc/blob/main/postcss.config.mjs"
    click TSConfig "https://github.com/health-it-club/qcmcalc/blob/main/tsconfig.json"

    classDef presentation fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef stateLogic fill:#90EE90,stroke:#333,stroke-width:1px
    classDef data fill:#FFFFE0,stroke:#333,stroke-width:1px
    classDef infra fill:#D3D33,stroke:#333,stroke-width:1px
```
