# munsoc-mpstme/mundra architecture

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

- Interactive diagram: https://gitdiagram.com/munsoc-mpstme/mundra
- Repository: https://github.com/munsoc-mpstme/mundra

## Overview

##### Project type and purpose
- This is a RESTful backend service built with FastAPI (“MUNDRA – MUNSoc Delegate Resource Application”).
- It provides authentication, delegate management, event-specific routes (Mumbai MUN), email notifications (verification/reset), QR code generation, and backup capabilities.
- It serves mobile apps (iOS/Android “Delego”) and minimal HTML pages for QR scanning, food preferences, and password reset.

##### File structure
Top-level files
- app.py        – FastAPI app, route registration
- auth.py       – JWT and password-hashing logic
- database.py   – SQLite connection / CRUD abstractions
- models.py     – Pydantic schemas / domain models
- mails.py      – Email sending (FastMail)
- utils.py      – Helpers: QR code generation, etc.
- config.py     – Environment and secret configuration
- backups/      – Placeholder for backup archives
- databases/    – Placeholder for DB files
- qrcodes/      – Directory where generated QR images are stored
- email_templates/ – HTML templates for email bodies
- templates/    – HTML pages served by some routes
- static/       – Static assets (CSS, JS, images)
Config & env
- requirements.txt, sample.env, .python-version
- .gitignore

##### README
- Confirms FastAPI, SQLite (main and mm.db), JWT auth, bcrypt, email via FastMail
- Lists all routes: auth, admin, delegate, Mumbai MUN, QR-related
- Highlights key features: two databases, QR generation/storage, backup endpoint

##### Main components & interactions
A. External clients
1. Mobile apps (iOS/Android)
2. Admin scripts or HTTP tools (curl, Postman)
3. Browser (for minimal HTML pages)
B. API Gateway (FastAPI app in app.py)
- Receives HTTP(S) requests
- Applies middleware: CORS, request validation
- Routes to handlers (auth, delegate, admin, mm, qr, food)
C. Authentication & Authorization
- auth.py issues/verifies JWT tokens
- Dependencies in routes enforce user/auth checks (get_current_user, is_admin)
D. Business Logic Modules
- Delegate management (in app.py + database.py + models.py)
- Mumbai MUN module (separate DB “mm.db”)
- QR code generation (utils.py)
- Backup service (zips both DB files)
E. Persistence Layer
- SQLite databases (main.db, mm.db) via database.py
- File storage:
– qrcodes/ for QR image files
– backups/ for zipped DB backups
F. Email Service
- mails.py uses FastMail to send verification & reset emails
- email_templates/ holds HTML templates for message bodies
G. Presentation (minimal)
- templates/ – HTML pages (scan, food, reset) rendered by FastAPI
- static/ – served assets for HTML pages

##### Architectural patterns and design principles
- Modular layering:
1. API layer (FastAPI routes)
2. Service layer (auth, delegate, QR, backup logic)
3. Data access layer (database.py)
- Separation of concerns: Authentication logic separated from route definitions.
- Single process, monolithic backend (no microservices) with two distinct DB files.
- Dependency injection via FastAPI’s Depends().
- Pydantic models for request/response validation.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Clients
    MobileApp["Mobile App (iOS/Android)"]:::external
    AdminTool["Admin Tool (curl/Postman)"]:::external
    Browser["Browser"]:::external

    %% API Gateway
    subgraph "FastAPI Server"
        direction TB
        APIGateway["HTTP Router"]:::api
        AuthService["Authentication Service"]:::service
        DelegateService["Delegate Service"]:::service
        MMService["MM Delegate Service"]:::service
        QRService["QR Code Service"]:::service
        BackupService["Backup Service"]:::service
        EmailService["Email Service"]:::service
        APIGateway -->|"uses Depends() for auth"| AuthService
        APIGateway -->|"POST /delegate"| DelegateService
        APIGateway -->|"POST /mm/*"| MMService
        APIGateway -->|"GET /qr"| QRService
        APIGateway -->|"GET /backup"| BackupService
        APIGateway -->|"POST /email/*"| EmailService
    end

    %% Persistence Layer
    subgraph "Persistence" 
        direction TB
        MainDB[(main.db)]:::db
        MMDB[(mm.db)]:::db
        QRStorage[/"qrcodes/"/]:::storage
        BackupStorage[/"backups/"/]:::storage
        MainDB ---|reads/writes| DelegateService
        MMDB ---|reads/writes| MMService
        QRService -->|"writes images"| QRStorage
        BackupService -->|"zips DBs"| BackupStorage
    end

    %% Email Templates & SMTP
    subgraph "Email Infrastructure"
        direction TB
        EmailTemplates[/"email_templates/"/]:::storage
        SMTP["SMTP Provider"]:::external
        EmailService -->|"loads templates"| EmailTemplates
        EmailService -->|"sends email via SMTP"| SMTP
    end

    %% Presentation Assets
    subgraph "Browser UI Assets"
        direction TB
        Templates[/"templates/"/]:::storage
        StaticAssets[/"static/"/]:::storage
        Browser -->|"GET HTML pages"| APIGateway
        APIGateway -->|"renders"| Templates
        Templates -->|"loads assets"| StaticAssets
    end

    %% Configuration and Environment
    Config["config.py"]:::config
    Env["sample.env"]:::config
    Requirements["requirements.txt"]:::config
    PyVersion[".python-version"]:::config
    Gitignore[".gitignore"]:::config

    %% Clients to Router
    MobileApp -->|"REST API calls"| APIGateway
    AdminTool -->|"Admin routes"| APIGateway
    Browser -->|"UI routes"| APIGateway

    %% Click Events
    click APIGateway "https://github.com/munsoc-mpstme/mundra/blob/master/app.py"
    click AuthService "https://github.com/munsoc-mpstme/mundra/blob/master/auth.py"
    click DAL "https://github.com/munsoc-mpstme/mundra/blob/master/database.py"
    click Models "https://github.com/munsoc-mpstme/mundra/blob/master/models.py"
    click EmailService "https://github.com/munsoc-mpstme/mundra/blob/master/mails.py"
    click EmailTemplates "https://github.com/munsoc-mpstme/mundra/tree/master/email_templates/"
    click QRService "https://github.com/munsoc-mpstme/mundra/blob/master/utils.py"
    click QRStorage "https://github.com/munsoc-mpstme/mundra/tree/master/qrcodes/"
    click BackupStorage "https://github.com/munsoc-mpstme/mundra/tree/master/backups/"
    click Config "https://github.com/munsoc-mpstme/mundra/blob/master/config.py"
    click Env "https://github.com/munsoc-mpstme/mundra/blob/master/sample.env"
    click Requirements "https://github.com/munsoc-mpstme/mundra/blob/master/requirements.txt"
    click PyVersion "https://github.com/munsoc-mpstme/mundra/blob/master/.python-version"
    click Gitignore "https://github.com/munsoc-mpstme/mundra/blob/master/.gitignore"
    click Templates "https://github.com/munsoc-mpstme/mundra/tree/master/templates/"
    click StaticAssets "https://github.com/munsoc-mpstme/mundra/tree/master/static/"

    %% Styles
    classDef external fill:#ddd,stroke:#666,stroke-width:1px
    classDef api fill:#bbdefb,stroke:#347ab7,stroke-width:2px
    classDef service fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px
    classDef db fill:#ffe0b2,stroke:#ef6c00,stroke-width:2px
    classDef storage fill:#ffcc80,stroke:#e65100,stroke-width:2px
    classDef config fill:#e1bee7,stroke:#6a1b9a,stroke-width:2px
```
