# ahana1412/smart-campus-companion architecture

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

- Interactive diagram: https://gitdiagram.com/ahana1412/smart-campus-companion
- Repository: https://github.com/ahana1412/smart-campus-companion

## Overview

##### Project type and purpose
- This is a full-stack, demo-ready web application (“Smart Campus Companion”) for reporting campus issues, lost & found, and pushing awareness alerts.
- Frontend is a React single-page app (SPA). Backend is a Python service (venv present) exposing REST endpoints, which handles persistence, image uploads, and an ML-based auto-categorization.

##### Main components
a. Frontend (React SPA)
- Hosts components under frontend/src (forms, lists, dashboard, sidebar)
- Communicates via AJAX/Fetch to the backend API
b. Backend API Service
- Python application (Flask/Django/FastAPI implied by venv)
- Exposes endpoints for:
– ReportProblem (POST/GET)
– LostFound (POST/GET, image upload)
– Alerts (GET)
– Categorization trigger
c. Database
- Stores issues, lost-&-found records, alerts, user metadata, ML model outputs
- Likely PostgreSQL or MongoDB (select based on Python stack)
d. Object Storage / Blob Store
- Holds uploaded images (e.g., AWS S3 / Google Cloud Storage / local file store)
e. ML Categorization Service
- Could be embedded in the backend or a standalone microservice
- Takes incoming issue data, returns “IT/Hostel/Facilities” category
f. External Notification Channels (optional)
- Email / SMS / Push notifications for real-time campus alerts

##### Relationships & data flow
- Browser <–> Frontend React SPA
- SPA —(HTTP/HTTPS REST calls)→ Backend API
- Backend —(SQL/NoSQL queries)→ Database
- Backend —(PUT)→ Object Storage
- Backend —(RPC or in-process call)→ ML Categorization Service
- Backend —(triggers)→ Notification Channel

##### Architectural patterns & design principles
- Client-Server (React UI vs. REST API)
- Modular UI components for forms, lists, dashboard
- Separation of concerns:
- Presentation layer (React)
- Business logic + ML (Python)
- Data persistence (Database + Storage)
- Asynchronous handling of image uploads and ML classification
- Stateless API (scale horizontally)

## Diagram (Mermaid)

```mermaid
flowchart TD
    Browser["User Browser"]:::external
    subgraph "Frontend (React SPA)"
        direction TB
        App["App.js"]:::frontend
        Sidebar["Sidebar.js"]:::frontend
        Dashboard["dashboard.js"]:::frontend
        ReportForm["ReportProblemForm.js"]:::frontend
        ProblemList["ProblemList.js"]:::frontend
        LostFoundForm["LostFoundForm.js"]:::frontend
        LostFoundList["LostFoundList.js"]:::frontend
        APIUtil["api.js"]:::frontend
    end

    subgraph "Backend API Service"
        direction TB
        APISvc["Python API Service"]:::backend
        ReportEndpoint["ReportProblem Endpoint"]:::backend
        LostFoundEndpoint["LostFound Endpoint"]:::backend
        AlertsEndpoint["Alerts Endpoint"]:::backend
        MLTrigger["Categorization Trigger"]:::backend
    end

    subgraph "Data Layer"
        direction TB
        DB["Database"]:::datastore
        Storage["Object Storage"]:::datastore
    end

    ML["ML Categorization Service"]:::external
    Notif["Notification Channels"]:::external

    Browser -->|uses SPA| App
    App -->|renders UI| Sidebar
    App -->|renders UI| Dashboard
    App -->|renders UI| ReportForm
    App -->|renders UI| ProblemList
    App -->|renders UI| LostFoundForm
    App -->|renders UI| LostFoundList
    App -->|calls APIs| APIUtil
    APIUtil -->|"HTTP REST"| APISvc

    APISvc -->|handles| ReportEndpoint
    APISvc -->|handles| LostFoundEndpoint
    APISvc -->|handles| AlertsEndpoint
    APISvc -->|invokes| MLTrigger

    ReportEndpoint -->|"SQL/NoSQL"| DB
    LostFoundEndpoint -->|"SQL/NoSQL"| DB
    LostFoundEndpoint -->|"PUT"| Storage
    MLTrigger -->|RPC/Call| ML
    APISvc -->|triggers| Notif

    classDef frontend fill:#add8e6,stroke:#0000ff,color:#000
    classDef backend fill:#90ee90,stroke:#008000,color:#000
    classDef datastore fill:#ffa500,stroke:#cc8400,color:#000
    classDef external fill:#dda0dd,stroke:#aa77aa,color:#000

    click App "https://github.com/ahana1412/smart-campus-companion/blob/main/frontend/src/App.js"
    click Sidebar "https://github.com/ahana1412/smart-campus-companion/blob/main/frontend/src/components/Sidebar.js"
    click Dashboard "https://github.com/ahana1412/smart-campus-companion/blob/main/frontend/src/components/dashboard.js"
    click ReportForm "https://github.com/ahana1412/smart-campus-companion/blob/main/frontend/src/components/ReportProblemForm.js"
    click ProblemList "https://github.com/ahana1412/smart-campus-companion/blob/main/frontend/src/components/ProblemList.js"
    click LostFoundForm "https://github.com/ahana1412/smart-campus-companion/blob/main/frontend/src/components/LostFoundForm.js"
    click LostFoundList "https://github.com/ahana1412/smart-campus-companion/blob/main/frontend/src/components/LostFoundList.js"
    click APIUtil "https://github.com/ahana1412/smart-campus-companion/blob/main/frontend/src/api.js"
    click APISvc "https://github.com/ahana1412/smart-campus-companion/tree/main/backend/"
```
