How carlovich01/mapit works
Project Type & Purpose
• MapIT is a full-stack educational web application.
• It ingests PDF documents, uses AI to extract semantic structure, and offers three interactive learning modes: mind maps, flashcards (SM-2 spaced repetition), and connection games.
File Structure Analysis
• backend/
• FastAPI app with modular routers under app/api/ (auth, flashcards, game, mind_maps)
• Domain models under app/models/, Pydantic schemas under app/schemas/
• Business logic in app/services/ (AI service, PDF processing, auth, flashcards, mind maps, games)
• Utilities (app/utils/), DB config (database.py), DI (dependencies.py), middleware, Alembic migrations, Dockerfiles
• frontend/
• React+TypeScript single-page app built with Vite
• Components organized by feature (auth, flashcards, game, mindmap) and UI primitives
• State management via Zustand, HTTP via Axios, visualization via React Flow + d3
• Build & production config: Dockerfiles, Nginx, Tailwind, ESLint, TS configs
• Top-level
• docker-compose.dev.yml and docker-compose.prod.yml orchestrate backend, frontend, DB, Adminer, Nginx
Main Components
A. Client Browser (React/Vite SPA)
B. Reverse Proxy (Nginx in production)
C. Frontend Static Assets & Dev-Server
D. Backend API (FastAPI)
E. Database (PostgreSQL + Alembic migrations)
F. External AI Service (Google Gemini)
G. PDF Processor (PyMuPDF in-memory)
H. Optional Adminer DB GUI (dev)
Component Interactions & Data Flows
• User action in browser → frontend React router/component → Axios HTTP call to /api/...
• Nginx (prod) or Vite proxy (dev) routes API calls to FastAPI
• FastAPI authenticates (JWT), invokes service layer
• PDF uploads → PyMuPDF extracts text/structure → AI Service (Gemini) for mind-map hierarchy
• Flashcards generate via AI + SM-2 algorithm, store in DB
• Game sessions compare user’s reconstructed graph vs stored edges
• FastAPI persists & queries PostgreSQL (async SQLAlchemy)
• Responses flow back through API → frontend → UI updates
Architectural Patterns & Principles
• Layered Architecture in backend: routers → services → repositories/models → DB
• Dependency Injection via FastAPI’s Depends
• Modular Frontend by feature, fosters separation of concerns
• Event-Driven data flows (file upload → processing → persistence)
• Async Everywhere for non-blocking I/O (FastAPI + SQLAlchemy async + PyMuPDF in memory)
• Infrastructure as Code with Docker Compose for dev/prod parity