# alamino8islam/ecosphere architecture

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

- Interactive diagram: https://gitdiagram.com/alamino8islam/ecosphere
- Repository: https://github.com/alamino8islam/ecosphere

## Overview

##### Project type and purpose
- EcoSphere is a full-stack web application built with Flask (Python) for the backend and HTML/CSS/JavaScript for the frontend.

##### File structure
Top-level:
- run.py: Flask application entry point
- config.py: configuration (DB URI, secret keys, API keys)
- ecosphere_schema.sql: database schema
- requirements.txt: Python dependencies
- instance/default.db: SQLite (dev) or MySQL in production
app/ directory (application package)
- __init__.py: application factory, blueprint registration, DB initialization
- models.py: SQLAlchemy ORM models representing Users, Activities, Logs, Badges, etc.
- routes/ subfolder: Flask blueprints grouped by feature (auth, carbon, dashboard, notes, notifications, vitamin, main)
- static/: CSS and JS assets (dashboard.css, dashboard.js)
- templates/: Jinja2 HTML templates for pages (dashboard.html, energy.html, food.html, index.html, transport.html)

##### Key insights from the README
- Uses MySQL (production) or SQLite dev instance
- Third-party integrations: geolocation API (browser), weather/Vitamin D estimations, emission factor lookups
- Data processing via Pandas/NumPy (for analytics calculations)
- Authentication with on-screen code verification (no email service)
- Gamified rank/badge system with avatar customization

##### Main components
a. Frontend (Client Browser)
- Pages: index (login/signup/guest), dashboard, energy, food, transport, notes
- Static assets: CSS, JS (handles modals, form submissions, geolocation calls)
- Interactions: HTTP(S) GET/POST to Flask endpoints; AJAX calls for real-time updates
b. Backend (Flask Application)
- Application Factory: configures app, registers blueprints, connects to DB
- Blueprints/Routes:
– auth: sign-up, login, guest-session, code verification
– carbon: log activities & compute emissions
– vitamin: fetch weather/UV data and compute Vitamin D
– dashboard: aggregate stats & progress data with Pandas/NumPy
– notes & notifications: user notes/alerts
– main: home/landing pages
- Models: ORM classes for Users, Logs, Emissions, Ranks, Badges
- Services Layer (implicit): computations for CO₂ impact, rank progression, Vitamin D estimation
c. Database (MySQL or SQLite)
- Tables: users, activity_logs, carbon_calculations, vitamin_estimations, badges, notifications, notes
- Schema defined in ecosphere_schema.sql and models.py
d. External Services & APIs
- Browser Geolocation API
- Weather/UV Index API (e.g., OpenWeatherMap)
- Emission factor data (publicly available tables)
e. Data Processing Libraries
- Pandas & NumPy for analytics and time-series aggregations

##### Relationships and data flows
- User Browser → (HTTP) → Flask Routes → (ORM) → Database
- Flask Routes → (internal call) → Pandas/NumPy processing → Metrics
- Flask Routes → (HTTP) → External Weather API → Vitamin D calculations
- Flask Routes → (render) → Jinja2 Templates → Browser
- Static JS → AJAX calls → selective endpoints (e.g., live updates on dashboard)

##### Architectural patterns & design principles
- MVC-like separation: Templates (View), Routes (Controller), Models (Model)
- Blueprint modularity: feature-based organization
- Service/utility functions for domain logic (CO₂ models, Vitamin D estimator)
- RESTful endpoints for CRUD operations (activities, notes, notifications)
- Client-side dynamic updates (AJAX) for real-time UX

##### Detailed capture of essential elements
- Blueprint modules and their responsibilities
- ORM models and their corresponding tables
- Data processing flow: raw inputs → Pandas/NumPy → aggregated metrics
- Gamification engine: rank progression & badge assignment
- Geolocation & external API integration points

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend (Client Browser)"
        direction TB
        IndexHTML["index.html"]:::frontend
        DashboardHTML["dashboard.html"]:::frontend
        EnergyHTML["energy.html"]:::frontend
        FoodHTML["food.html"]:::frontend
        TransportHTML["transport.html"]:::frontend
        DashboardCSS["dashboard.css"]:::static
        DashboardJS["dashboard.js"]:::static
    end

    %% Backend Layer
    subgraph "Backend (Flask Application)"
        direction TB
        RunPY["run.py"]:::backend
        ConfigPY["config.py"]:::config
        SchemaSQL["ecosphere_schema.sql"]:::config
        InitPY["__init__.py"]:::backend
        ModelsPY["models.py"]:::model

        subgraph "Blueprints / Routes"
            direction TB
            AuthPY["auth.py"]:::blueprint
            CarbonPY["carbon.py"]:::blueprint
            DashboardPY["dashboard.py"]:::blueprint
            VitaminPY["vitamin.py"]:::blueprint
            NotesPY["notes.py"]:::blueprint
            NotificationsPY["notifications.py"]:::blueprint
            MainPY["main.py"]:::blueprint
            EnvPY["env.py"]:::blueprint
        end

        Pandas["Pandas/NumPy Services"]:::service
    end

    %% Database Layer
    subgraph "Database"
        direction TB
        SQLiteDB["default.db"]:::database
        MySQL["MySQL (prod)"]:::database
        Tables["Tables: users, logs, emissions, etc."]:::database
    end

    %% External Services
    subgraph "External APIs"
        direction TB
        GeoAPI["Browser Geolocation API"]:::external
        WeatherAPI["Weather/UV API"]:::external
        EmissionData["Emission Factor Data"]:::external
    end

    %% Connections
    IndexHTML -->|GET /| RunPY
    DashboardHTML -->|GET /dashboard| DashboardPY
    EnergyHTML -->|GET /energy| CarbonPY
    FoodHTML -->|GET /food| CarbonPY
    TransportHTML -->|GET /transport| CarbonPY
    DashboardJS -->|AJAX| DashboardPY
    DashboardCSS -->|loads| DashboardHTML

    RunPY --> InitPY
    InitPY --> ConfigPY
    InitPY --> ModelsPY
    InitPY --> AuthPY
    InitPY --> CarbonPY
    InitPY --> DashboardPY
    InitPY --> VitaminPY
    InitPY --> NotesPY
    InitPY --> NotificationsPY
    InitPY --> MainPY
    InitPY --> EnvPY

    AuthPY -->|SQLAlchemy query| ModelsPY
    CarbonPY -->|SQLAlchemy query| ModelsPY
    DashboardPY -->|SQLAlchemy query| ModelsPY
    VitaminPY -->|SQLAlchemy query| ModelsPY
    NotesPY -->|SQLAlchemy query| ModelsPY
    NotificationsPY -->|SQLAlchemy query| ModelsPY

    ModelsPY --> SQLiteDB
    ModelsPY --> MySQL
    SQLiteDB --> Tables
    MySQL --> Tables

    CarbonPY --> Pandas
    DashboardPY --> Pandas
    VitaminPY --> WeatherAPI
    CarbonPY --> EmissionData
    IndexHTML --> GeoAPI

    %% Click Events
    click DashboardCSS "https://github.com/alamino8islam/ecosphere/blob/main/app/static/css/dashboard.css"
    click DashboardJS "https://github.com/alamino8islam/ecosphere/blob/main/app/static/js/dashboard.js"
    click IndexHTML "https://github.com/alamino8islam/ecosphere/blob/main/app/templates/index.html"
    click DashboardHTML "https://github.com/alamino8islam/ecosphere/blob/main/app/templates/dashboard.html"
    click EnergyHTML "https://github.com/alamino8islam/ecosphere/blob/main/app/templates/energy.html"
    click FoodHTML "https://github.com/alamino8islam/ecosphere/blob/main/app/templates/food.html"
    click TransportHTML "https://github.com/alamino8islam/ecosphere/blob/main/app/templates/transport.html"
    click RunPY "https://github.com/alamino8islam/ecosphere/blob/main/run.py"
    click ConfigPY "https://github.com/alamino8islam/ecosphere/blob/main/config.py"
    click SchemaSQL "https://github.com/alamino8islam/ecosphere/blob/main/ecosphere_schema.sql"
    click InitPY "https://github.com/alamino8islam/ecosphere/blob/main/app/__init__.py"
    click ModelsPY "https://github.com/alamino8islam/ecosphere/blob/main/app/models.py"
    click AuthPY "https://github.com/alamino8islam/ecosphere/blob/main/app/routes/auth.py"
    click CarbonPY "https://github.com/alamino8islam/ecosphere/blob/main/app/routes/carbon.py"
    click DashboardPY "https://github.com/alamino8islam/ecosphere/blob/main/app/routes/dashboard.py"
    click VitaminPY "https://github.com/alamino8islam/ecosphere/blob/main/app/routes/vitamin.py"
    click NotesPY "https://github.com/alamino8islam/ecosphere/blob/main/app/routes/notes.py"
    click NotificationsPY "https://github.com/alamino8islam/ecosphere/blob/main/app/routes/notifications.py"
    click MainPY "https://github.com/alamino8islam/ecosphere/blob/main/app/routes/main.py"
    click EnvPY "https://github.com/alamino8islam/ecosphere/blob/main/app/routes/env.py"
    click SQLiteDB "https://github.com/alamino8islam/ecosphere/blob/main/instance/default.db"
    click Tables "https://github.com/alamino8islam/ecosphere/blob/main/ecosphere_schema.sql"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef static fill:#B0E0E6,stroke:#000,stroke-width:1px
    classDef backend fill:#90EE90,stroke:#000,stroke-width:1px
    classDef config fill:#98FB98,stroke:#000,stroke-width:1px
    classDef model fill:#7CFC00,stroke:#000,stroke-width:1px
    classDef blueprint fill:#32CD32,stroke:#000,stroke-width:1px
    classDef service fill:#66CDAA,stroke:#000,stroke-width:1px
    classDef database fill:#FFA500,stroke:#000,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:1px
```
