# lambdaiith/dashboard architecture

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

- Interactive diagram: https://gitdiagram.com/lambdaiith/dashboard
- Repository: https://github.com/lambdaiith/dashboard

## Overview

##### Project Purpose & Type
- The IITH Dashboard is an open-source campus management platform. It provides multiple services including cab sharing, mess menu, bus schedules, lost and found, timetable management, and more.
- The README and file tree indicate that it’s a full-stack application with a multi-component backend rather than a single monolithic backend. There are distinct implementations in Go (“backend-go”) and Python FastAPI (“backend/backend”), in addition to a Flutter-based frontend supporting Android, iOS, web, and desktop.

##### File Structure & Architectural Style
- Frontend: The “frontend” directory shows a well-structured Flutter project with platform-specific folders (android, ios, web, windows, macos, linux). It includes dart files (screens, models, widgets, services) suggesting an MVVM or MVC-inspired organization.
- Backend:
- The “backend-go” directory implements a Go-based API with components like controllers, routers, middleware, DB interactions, helpers, and email templates. This indicates an MVC-like pattern.
- The “backend/backend” directory seems to implement a Python FastAPI server with routes, controllers, models, queries, and utility scripts. This backend is explicitly mentioned in the README installation section.
- Additional Documentation: Backend-docs provides API usage details for features like Cabshare and Lost and Found.
- There are SQL initialization scripts and job scripts (clear_lost_found_data, menu_scraper, etc.) that hint at scheduled tasks and supporting DB operations.
- Configuration files, deployment scripts (.github workflows, etc.), and environment files indicate clear separation of concerns in development, testing, and deployment.

##### Main Components
A. Frontend:
- Flutter app which is cross-platform (Android, iOS, Web, Desktop).
- UI components (screens, widgets) that interface with backend APIs.
- Service layers for analytics, API communications, notifications, etc.
B. Backend Services:
- Python FastAPI Server:
- Routes handling incoming REST API requests (authentication, cab sharing, lost and found, mess menus, etc.).
- Controllers and business logic for user management and campus features.
- External service integration endpoints (notifications, external data scraping, possibly Firebase as indicated in configuration).
- Go-based API Service:
- Controllers, routers, and database helpers for similar functionalities.
- Middleware (authentication protection) and templating features for notification emails.
C. Database & Persistence:
- SQL database (not explicitly named but referenced by SQL init scripts and DB helper files).
- Possibly cloud storage (AWS S3 is indicated via S3 helper in Go).
D. External Services & Utilities:
- External authentication (token management, cookie handling).
- Notification services (FCM and email templates).
- Scheduled job scripts (scraping, clear-lost_found data).
- Other integrations like Firebase (based on frontend Firebase config).

##### Relationships and Interactions
- The Flutter frontend communicates with backend API endpoints (over HTTP/REST).
- Both backend implementations expose endpoints that the client apps call.
- The backend services interact with the database for persistence.
- Utility modules in the backend interact with external services (email systems, AWS S3, Firebase notifications, etc.).
- Scheduled job scripts and external services periodically interact with the database and backend services to keep data updated.
- Client requests flow from frontend to backend.
- Backend-to-database interactions.
- Backend-to-external services integrations.

##### Architectural Patterns / Design Principles
- Separation of Concerns: Clearly separated layers for UI (frontend), API (backend with controllers/routes), and data persistence (database).
- Use of MVC-like patterns in both Go and Python backends.
- Microservice-like segmentation if both backend implementations provide similar but independent functionality.
- Clear middleware for security (authentication, cookies, JWT) and helpers for code reuse.

##### Technology Stack to Highlight
- Flutter (for cross-platform mobile/web/desktop development).
- Python (FastAPI) and Go (with an MVC-like organization) for backend services.
- SQL Database for persistence.
- External services: AWS S3 (for storage), Firebase (for notifications), and FCM.
- DevOps: GitHub workflows for CI/CD, configuration management.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Frontend
    subgraph "Frontend"
        FE["Flutter Frontend"]:::frontend
    end

    %% Backend Services
    subgraph "Backend Services"
        PF["Python FastAPI Backend"]:::backendPython
        GB["Go Backend Service"]:::backendGo
    end

    %% Database & Persistence
    subgraph "Database & Persistence"
        DBS["SQL Database"]:::database
        PYS["Python SQL Scripts"]:::database
        GOS["Go SQL Init Script"]:::database
    end

    %% External Services & Utilities
    subgraph "External Services & Utilities"
        AWS["AWS S3"]:::external
        EMAIL["Email Service"]:::external
        FB["FCM/Firebase"]:::external
        EXTS["External Service Integration (Python)"]:::external
        ET_PY["Email Templates (Python)"]:::external
        ET_GO["Email Templates (Go)"]:::external
    end

    %% Scheduled Job Scripts
    subgraph "Scheduled Job Scripts"
        PYJ["Python Job Scripts"]:::jobs
        GOJ["Go Utility Script"]:::jobs
    end

    %% Connections
    FE -->|"HTTP/REST"| PF
    FE -->|"HTTP/REST"| GB

    PF -->|"DBOperation"| DBS
    GB -->|"DBOperation"| DBS
    PYJ -->|"cleanup"| DBS

    PF -->|"calls"| EXTS
    PF -->|"notifies"| EMAIL
    GB -->|"notifies"| EMAIL
    PF -->|"sendsNotif"| FB
    GB -->|"sendsNotif"| FB

    GB -->|"integrates"| AWS

    PF -->|"usesET"| ET_PY
    GB -->|"usesET"| ET_GO

    PYJ -->|"triggers"| PF
    GOJ -->|"supports"| GB

    %% Click Events
    click FE "https://github.com/lambdaiith/dashboard/tree/develop/frontend"
    click PF "https://github.com/lambdaiith/dashboard/tree/develop/backend/backend"
    click GB "https://github.com/lambdaiith/dashboard/tree/develop/backend-go"
    click DBS "https://github.com/lambdaiith/dashboard/tree/develop/backend/backend/sql"
    click PYS "https://github.com/lambdaiith/dashboard/blob/develop/backend/backend/tables.sql"
    click GOS "https://github.com/lambdaiith/dashboard/blob/develop/backend-go/sql/init.sql"
    click AWS "https://github.com/lambdaiith/dashboard/blob/develop/backend-go/internal/helpers/s3helper.go"
    click EXTS "https://github.com/lambdaiith/dashboard/blob/develop/backend/backend/external_services.py"
    click ET_PY "https://github.com/lambdaiith/dashboard/tree/develop/backend/backend/templates"
    click ET_GO "https://github.com/lambdaiith/dashboard/tree/develop/backend-go/internal/templates"
    click PYJ "https://github.com/lambdaiith/dashboard/tree/develop/backend/backend/job_scripts"
    click GOJ "https://github.com/lambdaiith/dashboard/blob/develop/backend-go/makeAnAnnouncement.sh"

    %% Styles
    classDef frontend fill:#a2d9ce,stroke:#2e86c1,stroke-width:2px;
    classDef backendPython fill:#f7dc6f,stroke:#d4ac0d,stroke-width:2px;
    classDef backendGo fill:#f5b7b1,stroke:#c0392b,stroke-width:2px;
    classDef database fill:#d5f5e3,stroke:#27ae60,stroke-width:2px;
    classDef external fill:#d6eaf8,stroke:#3498db,stroke-width:2px;
    classDef jobs fill:#fad7a0,stroke:#e67e22,stroke-width:2px;
```
