# ndyabagye/quiz-app architecture

> Architecture diagram of the GitHub repository ndyabagye/quiz-app, 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/ndyabagye/quiz-app
- Repository: https://github.com/ndyabagye/quiz-app

## Overview

##### Project type and purpose
- This is a full-stack quiz application.
- Frontend: React + TypeScript + Vite
- Backend: FastAPI (Python) + SQLAlchemy + Alembic migrations
- Purpose: Allow guests to sign up/log in, view quizzes by subject, take quizzes, and save progress.

##### Main components
a. Frontend (Client)
- React components (src/components)
- UI modules (common, modules, ui)
- Routing layer (src/routes + routeTree.gen.ts)
- State & side-effect hooks (src/hooks/use-theme, local state in components)
- HTTP service layer (src/services/apiService.ts, authService.ts)
b. Backend (API Server)
- FastAPI app (backend/src/main.py)
- Routers (auth_router.py, user_router.py, plus quiz routers)
- Dependency injection (auth_dependencies.py)
- Business logic / CRUD layer (backend/src/crud)
- Schemas (Pydantic models in backend/src/schemas)
- Database models (SQLAlchemy in backend/src/models)
- Migration tool (Alembic / backend/alembic)
- Utilities (auth utils, database connection in backend/src/utils)
c. Database
- Relational DB (e.g., PostgreSQL/MySQL) behind SQLAlchemy
- Migration scripts (alembic/versions)
d. External Services
- Any 3rd-party integrations configured in backend/src/external_services (e.g., email, analytics)

##### Relationships & data flows
- User interacts with the Browser → React UI (HTTP over port 5173)
- React UI uses APIService/AuthService → sends GET/POST to FastAPI endpoints
- FastAPI routers depend on auth dependencies → validate JWT/session
- Routers invoke CRUD functions → SQLAlchemy ORM → read/write to Database
- Alembic maintains schema migrations → synchronizes models ↔ database
- Optional: FastAPI calls external services modules for notifications or analytics

##### Architectural patterns & design principles
- Clear separation of concerns:
- Presentation (React) ↔ API layer (FastAPI) ↔ Data layer (SQLAlchemy + DB)
- Dependency injection in FastAPI for auth and database sessions
- Layered architecture: Router → Service/CRUD → Model → DB
- React: Component hierarchy by feature (common vs modules vs ui) and hook-based state

##### Technologies & frameworks
- Frontend:
- React 18 + TypeScript
- Vite as build tool
- React Router (file-based under src/routes)
- Axios for HTTP calls (src/lib/axios.ts)
- Context or custom hooks for theme, auth state
- Backend:
- FastAPI for REST endpoints
- SQLAlchemy ORM + Alembic for migrations
- Pydantic for data validation (schemas)
- Uvicorn/Gunicorn for server
- Database: PostgreSQL (or any SQL DB)
- DevOps: .env for secrets, Docker-compose (if present), CI/CD pipeline (not shown)

##### Checklist before finalizing
[ ] All major components are present and labeled
[ ] File-based routers (frontend) and directory-based modules (backend) are reflected
[ ] DB schema entities (User, Quiz, Question, Answer) are noted

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Web Client Layer
    subgraph "Web Client"
        direction TB
        RC["React Components"]:::frontend
        CM["Common Modules"]:::frontend
        FM["Feature Modules"]:::frontend
        UI["UI Elements"]:::frontend
        RL["Routing Layer"]:::frontend
        RT["Generated Route Tree"]:::frontend
        TH["use-theme Hook"]:::frontend
        AS["apiService (Axios)"]:::frontend
        AH["authService"]:::frontend
    end

    %% API Server Layer
    subgraph "API Server"
        direction TB
        FE["FastAPI App"]:::backend
        AR["Auth Router"]:::backend
        UR["User Router"]:::backend
        CD["Auth Dependencies"]:::backend
        CR["CRUD Layer"]:::backend
        SC["Pydantic Schemas"]:::backend
        MD["SQLAlchemy Models"]:::backend
        AM["Alembic Config"]:::backend
        VM["Alembic Migrations"]:::backend
        ES_Backend["External Services Integrations"]:::backend
        UT["Utility Modules"]:::backend
    end

    %% Database
    DB["Database"]:::database

    %% External Services
    ext["3rd-Party Services"]:::external

    %% Data Flows
    RC -->|UI Rendering| CM
    CM --> FM
    FM --> UI
    UI --> RL
    RL --> RT
    RT --> AS
    TH --> AS
    AS --> AH
    AH -->|HTTP/HTTPS| FE

    %% Server Internal Flows
    FE -->|routes to| AR
    FE -->|routes to| UR
    AR -->|uses| CD
    UR -->|uses| CD
    AR -->|calls| CR
    UR -->|calls| CR
    CR -->|reads/writes| MD
    CR -->|validates| SC
    MD -->|persist| DB
    AM --> VM
    VM --> DB
    AR -.-> ES_Backend
    UR -.-> ES_Backend
    ES_Backend --> ext

    %% Click Events for Frontend
    click RC "https://github.com/ndyabagye/quiz-app/tree/main/src/components"
    click CM "https://github.com/ndyabagye/quiz-app/tree/main/src/components/common"
    click FM "https://github.com/ndyabagye/quiz-app/tree/main/src/components/modules"
    click UI "https://github.com/ndyabagye/quiz-app/tree/main/src/components/ui"
    click RL "https://github.com/ndyabagye/quiz-app/tree/main/src/routes"
    click RT "https://github.com/ndyabagye/quiz-app/blob/main/src/routeTree.gen.ts"
    click TH "https://github.com/ndyabagye/quiz-app/blob/main/src/hooks/use-theme.ts"
    click AS "https://github.com/ndyabagye/quiz-app/blob/main/src/services/apiService.ts"
    click AH "https://github.com/ndyabagye/quiz-app/blob/main/src/services/authService.ts"

    %% Click Events for Backend
    click FE "https://github.com/ndyabagye/quiz-app/blob/main/backend/src/main.py"
    click AR "https://github.com/ndyabagye/quiz-app/blob/main/backend/src/routers/auth_router.py"
    click UR "https://github.com/ndyabagye/quiz-app/blob/main/backend/src/routers/user_router.py"
    click CD "https://github.com/ndyabagye/quiz-app/blob/main/backend/src/dependencies/auth_dependecies.py"
    click CR "https://github.com/ndyabagye/quiz-app/tree/main/backend/src/crud"
    click SC "https://github.com/ndyabagye/quiz-app/tree/main/backend/src/schemas"
    click MD "https://github.com/ndyabagye/quiz-app/tree/main/backend/src/models"
    click AM "https://github.com/ndyabagye/quiz-app/blob/main/backend/alembic.ini"
    click VM "https://github.com/ndyabagye/quiz-app/tree/main/backend/alembic/versions"
    click ES_Backend "https://github.com/ndyabagye/quiz-app/tree/main/backend/src/external_services"
    click UT "https://github.com/ndyabagye/quiz-app/tree/main/backend/src/utils"

    %% Styles
    classDef frontend fill:#BBDEFB,stroke:#1E88E5,color:#0D47A1;
    classDef backend fill:#C8E6C9,stroke:#388E3C,color:#1B5E20;
    classDef database fill:#FFE0B2,stroke:#FB8C00,color:#E65100,shape:cylinder;
    classDef external fill:#E0E0E0,stroke:#9E9E9E,color:#424242,stroke-dasharray:5 5;
```
