# kapilbhadu0017/testrepo architecture

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

- Interactive diagram: https://gitdiagram.com/kapilbhadu0017/testrepo
- Repository: https://github.com/kapilbhadu0017/testrepo

## Overview

##### Project Type and Purpose
- This is a modern full-stack web application (“VayuCheck+”) that • monitors real-time air quality data, • stores it in MongoDB, and • uses Google Gemini AI to generate personalized health advice.
- The frontend (React + Vite + Tailwind + Leaflet) provides a UI and map visualization. The backend (FastAPI) exposes REST endpoints for data retrieval, AI suggestions, and map services. External APIs (WAQI, AirNow) and Google Gemini AI are key data sources.

##### File-Structure Analysis
- Top level:
- frontend/ – React app
- backend/ – FastAPI app + scripts
- README.md, package.json (root) – orchestrate install/run scripts
- Frontend:
- src/components – UI widgets (Map, Charts, Forms)
- config/api.js – base URL/endpoints
- public/index.html + Vite config – build/runtime
- Backend:
- app/routes – three route modules: aqi.py (air quality index), map.py (geodata), suggest.py (AI health advice)
- app/models/schemas.py – Pydantic schemas
- app/utils/db_utils.py – MongoDB helpers
- clear_data.py – optional data cleanup
- env.example – env var template (GEMINI_API_KEY, WAQI_TOKEN, AIRNOW_API_KEY, MONGODB_URL)

##### Extracted Architectural Patterns
- Layered architecture:
- Presentation (React SPA)
- API layer (FastAPI routes)
- Business logic (utils + AI integration)
- Persistence (MongoDB)
- Single-page-app communicates via REST to backend.
- No microservices: monolithic backend.

##### Main Components
a. Frontend (React + Vite)
– UI components: Home, HealthForm, DataCharts, Map, Sidebar, Navbar, LoadingSpinner, ErrorBoundary.
– Configuration: src/config/api.js points to FastAPI endpoints.
b. Backend (FastAPI)
– Route Modules:
- /aqi → fetch AQI from WAQI/AirNow, store/fetch in MongoDB
- /map → geospatial data for Leaflet
- /suggest → call Google Gemini AI with AQI + user data
– Models/Schemas: Pydantic for request/response validation
– Utilities: MongoDB connection & helpers
c. Database (MongoDB Atlas)
– Collections: air_quality_readings, user_suggestions (example tables)
d. External Services
– WAQI API
– AirNow API
– Google Gemini AI
e. Developer Scripts & Tools
– clear_data.py (data cleanup)
– npm run dev (concurrently launches Vite and Uvicorn)

##### Relationships & Data Flow
1. User interacts with React UI → submits a location/health form.
2. Frontend issues REST call to FastAPI `/aqi` endpoint.
3. Backend fetches AQI data from WAQI/AirNow → optionally cache/save in MongoDB → returns JSON to UI.
4. Frontend displays map/charts via Leaflet and DataCharts.
5. When user requests health advice, frontend calls `/suggest`.
6. Backend aggregates latest AQI + user data → sends payload to Google Gemini AI → receives suggestion → stores/retrieves in MongoDB → returns to UI.

##### Architectural Patterns & Principles
- Separation of concerns: UI vs API vs Data persistence vs AI integration
- Single responsibility: each route focuses on one external service or AI action
- Asynchronous I/O in FastAPI for low-latency external calls
- Stateless REST API – easy to horizontally scale

##### Detail
- `.env` configuration feeding into backend at startup.
- Developer workflow: “npm run dev” → concurrently starts Uvicorn and Vite dev server.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client (Browser)"
        direction TB
        ReactSPA["React SPA"]:::frontend
        subgraph "UI Components"
            direction TB
            Home["Home"]:::frontend
            HealthForm["HealthForm"]:::frontend
            DataCharts["DataCharts"]:::frontend
            MapComp["Map"]:::frontend
            Sidebar["Sidebar"]:::frontend
            Navbar["Navbar"]:::frontend
            LoadingSpinner["LoadingSpinner"]:::frontend
            ErrorBoundary["ErrorBoundary"]:::frontend
            ParticlesBG["ParticlesBackground"]:::frontend
            PerfMon["PerformanceMonitor"]:::frontend
        end
        Config["api.js"]:::frontend
        AppShell["App.jsx"]:::frontend
        Main["main.jsx"]:::frontend
        HTML["index.html"]:::frontend
        ViteConfig["vite.config.js"]:::frontend
    end

    %% API Server Layer
    subgraph "API Server (FastAPI)"
        direction TB
        MainAPI["main.py"]:::backend
        Aqi["Route /aqi"]:::backend
        MapRoute["Route /map"]:::backend
        Suggest["Route /suggest"]:::backend
        Schemas["schemas.py"]:::backend
        DBUtils["db_utils.py"]:::backend
        Env["env.example"]:::backend
    end

    %% Persistence
    subgraph "Persistence (MongoDB)"
        direction TB
        DB["MongoDB Atlas"]:::db
    end

    %% External Services
    subgraph "External Services"
        direction TB
        WAQI["WAQI API"]:::external
        AirNow["AirNow API"]:::external
        Gemini["Google Gemini AI"]:::external
    end

    %% Developer Scripts & Tools
    subgraph "Developer Tools & Scripts"
        direction TB
        Cleanup["clear_data.py"]:::script
        Package["package.json"]:::script
        Requirements["requirements.txt"]:::script
    end

    %% Connections
    ReactSPA --> Config
    ReactSPA --> AppShell
    ReactSPA --> Main
    ReactSPA --> HTML
    ReactSPA --> ViteConfig

    ReactSPA -->|"GET /aqi"| Aqi
    ReactSPA -->|"GET /map"| MapRoute
    ReactSPA -->|"POST /suggest"| Suggest

    MainAPI --> Aqi
    MainAPI --> MapRoute
    MainAPI --> Suggest
    Env --> MainAPI

    Aqi -->|fetch AQI data| WAQI
    Aqi -->|fetch AQI data| AirNow
    Aqi -->|store/retrieve| DB

    MapRoute -->|store/retrieve| DB

    Suggest -->|AI payload| Gemini
    Suggest -->|store/retrieve| DB

    Cleanup --> DB
    Package --> ReactSPA
    Package --> MainAPI
    Requirements --> MainAPI

    %% Click Events
    click ReactSPA "https://github.com/kapilbhadu0017/testrepo/tree/main/frontend/"
    click Home "https://github.com/kapilbhadu0017/testrepo/blob/main/frontend/src/components/Home.jsx"
    click HealthForm "https://github.com/kapilbhadu0017/testrepo/blob/main/frontend/src/components/HealthForm.jsx"
    click DataCharts "https://github.com/kapilbhadu0017/testrepo/blob/main/frontend/src/components/DataCharts.jsx"
    click MapComp "https://github.com/kapilbhadu0017/testrepo/blob/main/frontend/src/components/Map.jsx"
    click Sidebar "https://github.com/kapilbhadu0017/testrepo/blob/main/frontend/src/components/Sidebar.jsx"
    click Navbar "https://github.com/kapilbhadu0017/testrepo/blob/main/frontend/src/components/Navbar.jsx"
    click LoadingSpinner "https://github.com/kapilbhadu0017/testrepo/blob/main/frontend/src/components/LoadingSpinner.jsx"
    click ErrorBoundary "https://github.com/kapilbhadu0017/testrepo/blob/main/frontend/src/components/ErrorBoundary.jsx"
    click ParticlesBG "https://github.com/kapilbhadu0017/testrepo/blob/main/frontend/src/components/ParticlesBackground.jsx"
    click PerfMon "https://github.com/kapilbhadu0017/testrepo/blob/main/frontend/src/components/PerformanceMonitor.jsx"
    click Config "https://github.com/kapilbhadu0017/testrepo/blob/main/frontend/src/config/api.js"
    click AppShell "https://github.com/kapilbhadu0017/testrepo/blob/main/frontend/src/App.jsx"
    click Main "https://github.com/kapilbhadu0017/testrepo/blob/main/frontend/src/main.jsx"
    click HTML "https://github.com/kapilbhadu0017/testrepo/blob/main/frontend/index.html"
    click ViteConfig "https://github.com/kapilbhadu0017/testrepo/blob/main/frontend/vite.config.js"
    click MainAPI "https://github.com/kapilbhadu0017/testrepo/blob/main/backend/app/main.py"
    click Aqi "https://github.com/kapilbhadu0017/testrepo/blob/main/backend/app/routes/aqi.py"
    click MapRoute "https://github.com/kapilbhadu0017/testrepo/blob/main/backend/app/routes/map.py"
    click Suggest "https://github.com/kapilbhadu0017/testrepo/blob/main/backend/app/routes/suggest.py"
    click Schemas "https://github.com/kapilbhadu0017/testrepo/blob/main/backend/app/models/schemas.py"
    click DBUtils "https://github.com/kapilbhadu0017/testrepo/blob/main/backend/app/utils/db_utils.py"
    click Env "https://github.com/kapilbhadu0017/testrepo/blob/main/backend/env.example"
    click Cleanup "https://github.com/kapilbhadu0017/testrepo/blob/main/backend/clear_data.py"
    click Requirements "https://github.com/kapilbhadu0017/testrepo/blob/main/backend/requirements.txt"
    click Package "https://github.com/kapilbhadu0017/testrepo/blob/main/package.json"

    %% Styles
    classDef frontend fill:#bbdefb,stroke:#0d47a1,stroke-width:1px
    classDef backend fill:#90caf9,stroke:#1565c0,stroke-width:1px
    classDef db fill:#c8e6c9,stroke:#2e7d32,stroke-width:1px
    classDef external fill:#ffe0b2,stroke:#ef6c00,stroke-width:1px
    classDef script fill:#e0e0e0,stroke:#616161,stroke-width:1px
```
