# csb-218/mathtastic architecture

> Architecture diagram of the GitHub repository csb-218/mathtastic, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/csb-218/mathtastic
- Repository: https://github.com/csb-218/mathtastic

## Overview

##### Project type and purpose
- This is a full-stack educational game application (“Balance Scale Game”) with a Vue.js/Pinia/TailwindCSS frontend and a Python/FastAPI backend.
- It provides user authentication via Firebase, real-time game updates, and persistence in MongoDB (and Firestore).

##### File structure
- Top-level directories:
- backend/ – contains the FastAPI service, models, routers, schemas, utilities, Dockerfile and tests
- frontend/ – contains the Vue 3 application, components, services, store (Pinia), router, assets, Dockerfile, E2E & unit tests
- Key patterns:
- Frontend is component + service + store-driven (MVVM-ish)
- Backend follows a router/model/schema pattern (FastAPI’s flavor of MVC)
- Infrastructure as code: two Dockerfiles, .dockerignore, deployment config (vercel.json)

##### Extract additional insights from the README
- Tech stack: Vue.js, Pinia, TailwindCSS, FastAPI, MongoDB, Firestore, Firebase Auth, JWT
- Features highlight protected routes, JWT sessions, real-time updates
- Roadmap mentions Dockerization (already partially in place)

- Web Browser (client)
- Frontend SPA (Vue.js + Pinia + Tailwind)
- Backend API (FastAPI)
- Data stores: MongoDB cluster, Firebase Firestore
- Auth service: Firebase Authentication / JWT verification
- External services: Firebase Realtime updates (if used), static file hosting (e.g., Vercel)
- Browser ↔ Frontend (static assets served from CDN/Vercel)
- Frontend → Backend API (Axios HTTP calls, protected routes using JWT in headers)
- Backend → MongoDB (via db.py wrapper)
- Backend → Firestore (via firebase_admin.py)
- Backend ↔ Firebase Auth (JWT verification on each request)
c. Architectural patterns and principles:
- Separation of concerns: UI / state management / API services / persistence
- RESTful API endpoints organized by resource (users, games, activities, badges)
- Model-Schema mapping in backend for validation and serialization
- Pinia stores centralize client state, Services layer encapsulates API calls
d. Key technologies and frameworks:
- Vue 3 + Pinia + TailwindCSS + Vite (frontend build)
- FastAPI + Pydantic Schemas (backend)
- MongoDB (primary database), Firestore (supplementary, realtime), Firebase Auth (OAuth + JWT)
- Docker containers for frontend & backend

##### Detail without over-fragmentation
- Every major module: frontend’s Router, Pinia Store, API Services, backend routers/models/schemas.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    Browser["Web Browser"]:::external
    CDN["Static Hosting (Vercel/CDN)"]:::external
    Browser <-->|"serves SPA"| CDN
    CDN -->|"loads assets"| SPA

    %% Frontend Layer
    subgraph "Frontend (Vue.js + Pinia + Tailwind)" 
        direction TB
        SPA["Frontend SPA"]:::frontend
        Router["Frontend Router"]:::frontend
        subgraph "Stores (Pinia)"
            direction TB
            AuthStore["Authentication Store"]:::frontend
            AuthPageStore["Authentication Page Store"]:::frontend
            BalanceScaleStore["Gameplay BalanceScale Store"]:::frontend
            CounterStore["Counter Store"]:::frontend
        end
        subgraph "Services (API Wrappers)"
            direction TB
            AuthService["AuthService"]:::frontend
            GameService["GameService"]:::frontend
            FireStoreService["Firestore Service"]:::frontend
            SoundService["Sound Service"]:::frontend
        end
        subgraph "Config"
            direction TB
            AxiosConfig["Axios Config"]:::frontend
            FirebaseConfig["Firebase SDK Config"]:::frontend
        end
        subgraph "UI Components"
            direction TB
            LayoutNav["Core Layout & Navigation"]:::frontend
            AuthForm["Authentication Form"]:::frontend
            GameUI["Game UI Blocks"]:::frontend
            UIlib["Generic UI Library"]:::frontend
        end

        SPA -->|"uses router"| Router
        SPA -->|"binds state"| AuthStore
        SPA --> AuthPageStore
        SPA --> BalanceScaleStore
        SPA --> CounterStore
        SPA -->|"calls"| AuthService
        SPA --> GameService
        SPA --> FireStoreService
        SPA --> SoundService
        SPA --> AxiosConfig
        SPA --> FirebaseConfig
        SPA --> LayoutNav
        SPA --> AuthForm
        SPA --> GameUI
        SPA --> UIlib
    end

    %% Backend Layer
    subgraph "Backend (FastAPI Service)"
        direction TB
        FastAPI["FastAPI Service"]:::backend
        subgraph "API Routers"
            direction TB
            UsersRouter["Users API Router"]:::backend
            GamesRouter["Games API Router"]:::backend
            ActivitiesRouter["Activities API Router"]:::backend
            BadgesRouter["Badges API Router"]:::backend
        end
        subgraph "Models"
            direction TB
            UserModel["User Model"]:::backend
            GameModel["Game Model"]:::backend
            ActivityModel["Activity Model"]:::backend
            BadgeModel["Badge Model"]:::backend
        end
        subgraph "Schemas"
            direction TB
            UserSchema["User Schema"]:::backend
            GameSchema["Game Schema"]:::backend
            ActivitySchema["Activity Schema"]:::backend
            BadgeSchema["Badge Schema"]:::backend
        end
        DBWrapper["DB Wrapper (MongoDB)"]:::backend
        FirebaseAdmin["Firebase Admin Integration"]:::backend
        Helpers["Utilities"]:::backend

        FastAPI --> UsersRouter
        FastAPI --> GamesRouter
        FastAPI --> ActivitiesRouter
        FastAPI --> BadgesRouter
        UsersRouter --> UserModel
        GamesRouter --> GameModel
        ActivitiesRouter --> ActivityModel
        BadgesRouter --> BadgeModel
        UsersRouter --> UserSchema
        GamesRouter --> GameSchema
        ActivitiesRouter --> ActivitySchema
        BadgesRouter --> BadgeSchema
        UsersRouter --> DBWrapper
        GamesRouter --> DBWrapper
        ActivitiesRouter --> DBWrapper
        BadgesRouter --> DBWrapper
        FastAPI --> FirebaseAdmin
        FirebaseAdmin --> UserSchema
        FastAPI --> Helpers
    end

    %% Data & External Services
    MongoDB["MongoDB Atlas"]:::external
    Firestore["Firebase Firestore"]:::external
    FirebaseAuth["Firebase Authentication"]:::external

    DBWrapper -->|"CRUD operations"| MongoDB
    FirebaseAdmin --> Firestore
    FastAPI -->|'JWT verification'| FirebaseAuth

    SPA -->|"HTTP REST (Axios)"| FastAPI

    classDef frontend fill:#cce5ff,stroke:#000,stroke-width:1px;
    classDef backend fill:#d4edda,stroke:#000,stroke-width:1px;
    classDef external fill:#fff3cd,stroke:#000,stroke-width:1px;

    %% Click Events - Frontend
    click SPA "https://github.com/csb-218/mathtastic/blob/main/frontend/src/main.ts"
    click SPA "https://github.com/csb-218/mathtastic/blob/main/frontend/src/App.vue"
    click SPA "https://github.com/csb-218/mathtastic/blob/main/frontend/index.html"
    click Router "https://github.com/csb-218/mathtastic/blob/main/frontend/src/router/index.ts"
    click AuthStore "https://github.com/csb-218/mathtastic/blob/main/frontend/src/stores/Authentication/authStore.ts"
    click AuthPageStore "https://github.com/csb-218/mathtastic/blob/main/frontend/src/stores/Authentication/authPageStore.ts"
    click BalanceScaleStore "https://github.com/csb-218/mathtastic/blob/main/frontend/src/stores/Gameplay/BalanceScale/balanceScale.ts"
    click CounterStore "https://github.com/csb-218/mathtastic/blob/main/frontend/src/stores/counter.ts"
    click AuthService "https://github.com/csb-218/mathtastic/blob/main/frontend/src/services/AuthService.ts"
    click GameService "https://github.com/csb-218/mathtastic/blob/main/frontend/src/services/GameService.ts"
    click FireStoreService "https://github.com/csb-218/mathtastic/blob/main/frontend/src/services/FireStoreService.ts"
    click SoundService "https://github.com/csb-218/mathtastic/blob/main/frontend/src/services/SoundService.ts"
    click AxiosConfig "https://github.com/csb-218/mathtastic/blob/main/frontend/src/config/axiosConfig.ts"
    click FirebaseConfig "https://github.com/csb-218/mathtastic/blob/main/frontend/src/config/firebaseConfig.ts"
    click LayoutNav "https://github.com/csb-218/mathtastic/blob/main/frontend/src/components/AppSidebar.vue"
    click LayoutNav "https://github.com/csb-218/mathtastic/blob/main/frontend/src/components/NavMain.vue"
    click LayoutNav "https://github.com/csb-218/mathtastic/blob/main/frontend/src/components/NavUser.vue"
    click AuthForm "https://github.com/csb-218/mathtastic/blob/main/frontend/src/components/blocks/authentication/AuthForm.vue"
    click GameUI "https://github.com/csb-218/mathtastic/blob/main/frontend/src/components/blocks/game/LevelComplete.vue"
    click GameUI "https://github.com/csb-218/mathtastic/blob/main/frontend/src/components/blocks/game/OverLay.vue"
    click UIlib "https://github.com/csb-218/mathtastic/tree/main/frontend/src/components/ui/"

    %% Click Events - Backend
    click FastAPI "https://github.com/csb-218/mathtastic/blob/main/backend/main.py"
    click UsersRouter "https://github.com/csb-218/mathtastic/blob/main/backend/app/routers/users.py"
    click GamesRouter "https://github.com/csb-218/mathtastic/blob/main/backend/app/routers/games.py"
    click ActivitiesRouter "https://github.com/csb-218/mathtastic/blob/main/backend/app/routers/activities.py"
    click BadgesRouter "https://github.com/csb-218/mathtastic/blob/main/backend/app/routers/badges.py"
    click UserModel "https://github.com/csb-218/mathtastic/blob/main/backend/app/models/user.py"
    click GameModel "https://github.com/csb-218/mathtastic/blob/main/backend/app/models/game.py"
    click ActivityModel "https://github.com/csb-218/mathtastic/blob/main/backend/app/models/activity.py"
    click BadgeModel "https://github.com/csb-218/mathtastic/blob/main/backend/app/models/badge.py"
    click UserSchema "https://github.com/csb-218/mathtastic/blob/main/backend/app/schemas/user_schema.py"
    click GameSchema "https://github.com/csb-218/mathtastic/blob/main/backend/app/schemas/game_schema.py"
    click ActivitySchema "https://github.com/csb-218/mathtastic/blob/main/backend/app/schemas/activity_schema.py"
    click BadgeSchema "https://github.com/csb-218/mathtastic/blob/main/backend/app/schemas/badge_schema.py"
    click DBWrapper "https://github.com/csb-218/mathtastic/blob/main/backend/app/lib/db.py"
    click FirebaseAdmin "https://github.com/csb-218/mathtastic/blob/main/backend/app/firebase_admin.py"
    click Helpers "https://github.com/csb-218/mathtastic/blob/main/backend/app/utils/helpers.py"
```
