How ndyabagye/quiz-app works
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