How alamino8islam/ecosphere works
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