# carlovich01/mapit architecture

> Architecture diagram of the GitHub repository carlovich01/mapit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/carlovich01/mapit
- Repository: https://github.com/carlovich01/mapit

## Overview

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

## Diagram (Mermaid)

```mermaid
graph TD
    %% Client Layer
    subgraph "Client (Browser)"
        Browser["Client Browser<br/>(React/Vite SPA)"]:::frontend
    end

    %% Edge / Proxy
    subgraph "Dev / Prod Proxy"
        Vite["Vite Dev Server<br/>(5173)"]:::frontend
        NginxProd["Nginx Reverse Proxy<br/>(80/443)"]:::proxy
    end

    %% Frontend Application
    subgraph "Frontend App" 
        App["App.tsx & Routing"]:::frontend
        AuthPages["Login.tsx<br/>Register.tsx"]:::frontend
        FlashPage["FlashcardsPage.tsx"]:::frontend
        GamePage["GamePage.tsx"]:::frontend
        MindPage["MindMapDetail.tsx"]:::frontend
        ServicesFE["Axios Services"]:::frontend
    end

    %% Backend API
    subgraph "Backend API (FastAPI)"
        MainAPI["main.py"]:::backend
        AuthAPI["auth.py"]:::backend
        FlashAPI["flashcards.py"]:::backend
        MindAPI["mind_maps.py"]:::backend
        GameAPI["game.py"]:::backend
        AuthService["auth_service.py"]:::backend
        FlashService["flashcard_service.py"]:::backend
        MindService["mind_map_service.py"]:::backend
        GameService["game_service.py"]:::backend
        AIService["ai_service.py"]:::external
        PDFService["pdf_service.py"]:::backend
    end

    %% Data Layer
    subgraph "Database & Migrations"
        Postgres["PostgreSQL"]:::db
        Alembic["Alembic Migrations"]:::db
    end

    %% Dev Tools & Infra
    subgraph "Development & Production Infra"
        Adminer["Adminer GUI"]:::db
        DockerDev["docker-compose.dev.yml"]:::infra
        DockerProd["docker-compose.prod.yml"]:::infra
        NginxConf["nginx.conf"]:::proxy
    end

    %% Flows
    Browser -->|interacts| App
    App -->|routes| AuthPages
    App -->|routes| FlashPage
    App -->|routes| GamePage
    App -->|routes| MindPage
    AuthPages -->|calls| ServicesFE
    FlashPage -->|calls| ServicesFE
    GamePage -->|calls| ServicesFE
    MindPage -->|calls| ServicesFE

    ServicesFE -->|HTTP /api| Vite
    ServicesFE -->|HTTP /api| NginxProd
    Vite -->|proxy→| MainAPI
    NginxProd -->|routes→| MainAPI

    MainAPI -->|includes| AuthAPI
    MainAPI -->|includes| FlashAPI
    MainAPI -->|includes| MindAPI
    MainAPI -->|includes| GameAPI

    AuthAPI -->|uses| AuthService
    FlashAPI -->|uses| FlashService
    MindAPI -->|uses| MindService
    GameAPI -->|uses| GameService

    PDFService -->|extracts| MindService
    AIService -->|enriches| MindService

    AuthService -->|CRUD| Postgres
    FlashService -->|CRUD| Postgres
    MindService -->|CRUD| Postgres
    GameService -->|CRUD| Postgres

    Alembic -->|migrates| Postgres
    Adminer -->|GUI→| Postgres

    DockerDev -->|orchestrates| Browser
    DockerDev -->|orchestrates| MainAPI
    DockerDev -->|orchestrates| Postgres
    DockerDev -->|orchestrates| Adminer

    DockerProd -->|orchestrates| NginxProd
    DockerProd -->|orchestrates| MainAPI
    DockerProd -->|orchestrates| Postgres

    %% Click Events
    click Browser "https://github.com/carlovich01/mapit/tree/main/frontend/"
    click App "https://github.com/carlovich01/mapit/blob/main/frontend/src/App.tsx"
    click AuthPages "https://github.com/carlovich01/mapit/blob/main/frontend/src/pages/Login.tsx"
    click AuthPages "https://github.com/carlovich01/mapit/blob/main/frontend/src/pages/Register.tsx"
    click FlashPage "https://github.com/carlovich01/mapit/blob/main/frontend/src/pages/FlashcardsPage.tsx"
    click GamePage "https://github.com/carlovich01/mapit/blob/main/frontend/src/pages/GamePage.tsx"
    click MindPage "https://github.com/carlovich01/mapit/blob/main/frontend/src/pages/MindMapDetail.tsx"
    click ServicesFE "https://github.com/carlovich01/mapit/blob/main/frontend/src/services/api.ts"
    click ServicesFE "https://github.com/carlovich01/mapit/blob/main/frontend/src/services/authService.ts"
    click ServicesFE "https://github.com/carlovich01/mapit/blob/main/frontend/src/services/flashcardService.ts"
    click ServicesFE "https://github.com/carlovich01/mapit/blob/main/frontend/src/services/gameService.ts"
    click ServicesFE "https://github.com/carlovich01/mapit/blob/main/frontend/src/services/mindMapService.ts"
    click NginxConf "https://github.com/carlovich01/mapit/blob/main/frontend/nginx.conf"
    click DockerDev "https://github.com/carlovich01/mapit/blob/main/docker-compose.dev.yml"
    click DockerProd "https://github.com/carlovich01/mapit/blob/main/docker-compose.prod.yml"
    click MainAPI "https://github.com/carlovich01/mapit/blob/main/backend/app/main.py"
    click AuthAPI "https://github.com/carlovich01/mapit/blob/main/backend/app/api/auth.py"
    click AuthService "https://github.com/carlovich01/mapit/blob/main/backend/app/services/auth_service.py"
    click FlashAPI "https://github.com/carlovich01/mapit/blob/main/backend/app/api/flashcards.py"
    click FlashService "https://github.com/carlovich01/mapit/blob/main/backend/app/services/flashcard_service.py"
    click MindAPI "https://github.com/carlovich01/mapit/blob/main/backend/app/api/mind_maps.py"
    click MindService "https://github.com/carlovich01/mapit/blob/main/backend/app/services/mind_map_service.py"
    click GameAPI "https://github.com/carlovich01/mapit/blob/main/backend/app/api/game.py"
    click GameService "https://github.com/carlovich01/mapit/blob/main/backend/app/services/game_service.py"
    click AIService "https://github.com/carlovich01/mapit/blob/main/backend/app/services/ai_service.py"
    click PDFService "https://github.com/carlovich01/mapit/blob/main/backend/app/services/pdf_service.py"
    click Alembic "https://github.com/carlovich01/mapit/blob/main/backend/alembic.ini"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#369,stroke-width:1px
    classDef backend fill:#DFFFD0,stroke:#396,stroke-width:1px
    classDef db fill:#FFE8CC,stroke:#d66,stroke-width:1px
    classDef external fill:#E8D0FF,stroke:#639,stroke-width:1px
    classDef proxy fill:#F0F0F0,stroke:#888,stroke-width:1px
    classDef infra fill:#F8F8F8,stroke:#555,stroke-width:1px
```
