# devaprasath4/ecodecide architecture

> Architecture diagram of the GitHub repository devaprasath4/ecodecide, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/devaprasath4/ecodecide
- Repository: https://github.com/devaprasath4/ecodecide

## Overview

#### Purpose and Runtime
EcoDecide is a sustainability decision assistant: users submit everyday choices and receive AI-generated, emissions-oriented guidance. It runs as a Node.js/Express server with a static vanilla-JS frontend, MongoDB persistence with an in-memory fallback, Google Gemini 2.5 Flash, and Chart.js visualizations. Primary backend entry point: `server.js`.

#### Client Application Surfaces
The static UI has separate landing, authentication, and authenticated dashboard pages:
- Landing and general interactions: `public/index.html`, `public/js/main.js`
- Login/authentication flow: `public/login.html`, `public/js/auth.js`
- Decision history, impact data, and charts: `public/dashboard.html`, `public/js/dashboard.js`

Shared presentation is delivered from `public/css/style.css`.

#### HTTP/API Boundary
`server.js` is the application boundary between browser clients, authentication, persistence, and Gemini. Express serves the `public/` assets and exposes API endpoints consumed by the frontend scripts. The browser remains a thin client: it collects user input, stores/uses session credentials, renders responses, and visualizes returned impact/history data.

#### Identity and Session Control
Authentication is handled across `public/js/auth.js` and `server.js`. The server requires `JWT_SECRET` at startup, signs/verifies JWTs, and uses authenticated identity to scope user-specific decisions and dashboard data. This makes the API authentication boundary central rather than relying on frontend-only access control.

#### AI Decision and Emissions Stage
The core decision-analysis workflow is implemented server-side in `server.js`: incoming user choice context is sent to Google Gemini 2.5 Flash, whose response supplies sustainability guidance and CO₂ estimates. Prompting/calibration is expected to align with documented reference factors for transport, food, shopping, energy, and general lifecycle emissions; Gemini is an external service boundary and estimates are advisory rather than research-grade LCA results.

#### Persistence and Resilience
`server.js` owns data storage for users and/or decision records. MongoDB is the intended durable datastore, while an in-memory fallback allows operation when MongoDB is unavailable. This fallback changes durability characteristics: dashboard history and account/decision data may not survive process restarts without MongoDB.

#### Impact Reporting and Visualization
The dashboard client in `public/js/dashboard.js` retrieves authenticated user data from the API and renders decision/impact trends with Chart.js. `public/dashboard.html` is therefore the reporting endpoint, while `public/index.html` contains projected aggregate impact figures that are explicitly not live tracked metrics.

Main entry points: [`server.js`](https://github.com/devaprasath4/ecodecide/blob/main/server.js) (Express application), [`public/js/dashboard.js`](https://github.com/devaprasath4/ecodecide/blob/main/public/js/dashboard.js) (Dashboard client), [`public/css/style.css`](https://github.com/devaprasath4/ecodecide/blob/main/public/css/style.css) (Shared styles), [`public/index.html`](https://github.com/devaprasath4/ecodecide/blob/main/public/index.html) (Landing page)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Browser Client"]
  node_landing["Landing page<br/>static page<br/>[index.html]"]
  node_main_js["General interactions<br/>browser script<br/>[main.js]"]
  node_login["Login page<br/>static page<br/>[login.html]"]
  node_auth_js["Auth client<br/>browser script<br/>[auth.js]"]
  node_dashboard["Dashboard page<br/>static page<br/>[dashboard.html]"]
  node_dashboard_js["Dashboard client<br/>browser script<br/>[dashboard.js]"]
  node_styles["Shared styles<br/>stylesheet<br/>[style.css]"]
end

subgraph group_server["Express Server"]
  node_express{{"Express application<br/>HTTP boundary<br/>[server.js]"}}
  node_jwt_auth["JWT authentication<br/>identity layer<br/>[server.js]"]
  node_decision_analysis["Decision analysis<br/>AI workflow<br/>[server.js]"]
  node_persistence["Data repository<br/>storage layer<br/>[server.js]"]
  node_memory_store[("In-memory fallback<br/>volatile datastore<br/>[server.js]")]
end

subgraph group_external["External Services"]
  node_chartjs["Chart.js<br/>visualization library"]
  node_mongodb[("MongoDB<br/>durable datastore")]
  node_gemini{{"Gemini 2.5 Flash<br/>AI service"}}
end

node_landing -->|"loads"| node_main_js
node_login -->|"loads"| node_auth_js
node_dashboard -->|"loads"| node_dashboard_js
node_landing -->|"styled by"| node_styles
node_login -->|"styled by"| node_styles
node_dashboard -->|"styled by"| node_styles
node_main_js -->|"submits choices"| node_express
node_auth_js -->|"auth requests"| node_express
node_dashboard_js -->|"authenticated data requests"| node_express
node_dashboard_js -->|"renders charts"| node_chartjs
node_express -->|"authenticates API requests"| node_jwt_auth
node_express -->|"routes decision requests"| node_decision_analysis
node_express -->|"reads and writes user data"| node_persistence
node_decision_analysis -->|"sends choice context"| node_gemini
node_persistence -->|"primary storage"| node_mongodb
node_persistence -.->|"on database failure"| node_memory_store
node_jwt_auth -->|"scopes records by identity"| node_persistence

click node_landing "https://github.com/devaprasath4/ecodecide/blob/main/public/index.html"
click node_main_js "https://github.com/devaprasath4/ecodecide/blob/main/public/js/main.js"
click node_login "https://github.com/devaprasath4/ecodecide/blob/main/public/login.html"
click node_auth_js "https://github.com/devaprasath4/ecodecide/blob/main/public/js/auth.js"
click node_dashboard "https://github.com/devaprasath4/ecodecide/blob/main/public/dashboard.html"
click node_dashboard_js "https://github.com/devaprasath4/ecodecide/blob/main/public/js/dashboard.js"
click node_styles "https://github.com/devaprasath4/ecodecide/blob/main/public/css/style.css"
click node_express "https://github.com/devaprasath4/ecodecide/blob/main/server.js"
click node_jwt_auth "https://github.com/devaprasath4/ecodecide/blob/main/server.js"
click node_decision_analysis "https://github.com/devaprasath4/ecodecide/blob/main/server.js"
click node_persistence "https://github.com/devaprasath4/ecodecide/blob/main/server.js"
click node_memory_store "https://github.com/devaprasath4/ecodecide/blob/main/server.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_landing,node_main_js,node_login,node_auth_js,node_dashboard,node_dashboard_js,node_styles toneBlue
class node_express,node_jwt_auth,node_decision_analysis,node_persistence,node_memory_store toneAmber
class node_chartjs,node_mongodb,node_gemini toneMint
```

## Components

### Browser Client

- [Landing page](https://github.com/devaprasath4/ecodecide/blob/main/public/index.html): static page · Collects everyday choice input and shows projected aggregate impact. · `public/index.html`
- [General interactions](https://github.com/devaprasath4/ecodecide/blob/main/public/js/main.js): browser script · `public/js/main.js`
- [Login page](https://github.com/devaprasath4/ecodecide/blob/main/public/login.html): static page · `public/login.html`
- [Auth client](https://github.com/devaprasath4/ecodecide/blob/main/public/js/auth.js): browser script · Manages login flow and session credentials. · `public/js/auth.js`
- [Dashboard page](https://github.com/devaprasath4/ecodecide/blob/main/public/dashboard.html): static page · Authenticated reporting surface. · `public/dashboard.html`
- [Dashboard client](https://github.com/devaprasath4/ecodecide/blob/main/public/js/dashboard.js): browser script · Retrieves history and renders impact trends. · `public/js/dashboard.js`
- [Shared styles](https://github.com/devaprasath4/ecodecide/blob/main/public/css/style.css): stylesheet · `public/css/style.css`

### Express Server

- [Express application](https://github.com/devaprasath4/ecodecide/blob/main/server.js): HTTP boundary · Serves static assets and exposes frontend API endpoints. · `server.js`
- [JWT authentication](https://github.com/devaprasath4/ecodecide/blob/main/server.js): identity layer · Requires JWT_SECRET and scopes requests to authenticated users. · `server.js`
- [Decision analysis](https://github.com/devaprasath4/ecodecide/blob/main/server.js): AI workflow · Builds sustainability guidance and advisory CO₂ estimates. · `server.js`
- [Data repository](https://github.com/devaprasath4/ecodecide/blob/main/server.js): storage layer · Stores users and decision records. · `server.js`
- [In-memory fallback](https://github.com/devaprasath4/ecodecide/blob/main/server.js): volatile datastore · Used when MongoDB is unavailable; data is lost on restart. · `server.js`

### External Services

- **Chart.js**: visualization library
- **MongoDB**: durable datastore
- **Gemini 2.5 Flash**: AI service · External source of generated guidance and emissions estimates.

## Connections

- Landing page → General interactions: loads
- Login page → Auth client: loads
- Dashboard page → Dashboard client: loads
- Landing page → Shared styles: styled by
- Login page → Shared styles: styled by
- Dashboard page → Shared styles: styled by
- General interactions → Express application: submits choices
- Auth client → Express application: auth requests
- Dashboard client → Express application: authenticated data requests
- Dashboard client → Chart.js: renders charts
- Express application → JWT authentication: authenticates API requests
- Express application → Decision analysis: routes decision requests
- Express application → Data repository: reads and writes user data
- Decision analysis → Gemini 2.5 Flash: sends choice context
- Data repository → MongoDB: primary storage
- Data repository → In-memory fallback: on database failure
- JWT authentication → Data repository: scopes records by identity