# nxthanh01/ecometric-ios architecture

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

- Interactive diagram: https://gitdiagram.com/nxthanh01/ecometric-ios
- Repository: https://github.com/nxthanh01/ecometric-ios

## Overview

EcoMetric is an iOS application backed by a FastAPI service for operational energy measurement, analysis, recommendations, and action tracking. The principal journey is to enter electricity measurements, persist them by organization, run deterministic time-series analysis, optionally obtain Gemini interpretation, then review recommendations and remeasure results. The graph includes the documented account, reporting, and workflow capabilities. Some connections are based on README architecture documentation; unsampled implementations are represented only at their supported directory or module path.

Main entry points: [`ECOMETRIC BACKEND/ecometric-backend/main.py`](https://github.com/nxthanh01/ecometric-ios/blob/main/ECOMETRIC%20BACKEND/ecometric-backend/main.py) (FastAPI routes), [`EcoMetric/EcoMetric/ViewModels/AppAnalysisStore.swift`](https://github.com/nxthanh01/ecometric-ios/blob/main/EcoMetric/EcoMetric/ViewModels/AppAnalysisStore.swift) (Analysis state), [`EcoMetric/EcoMetric/Services/OperationalDataAPIService.swift`](https://github.com/nxthanh01/ecometric-ios/blob/main/EcoMetric/EcoMetric/Services/OperationalDataAPIService.swift) (Operational API), [`ECOMETRIC BACKEND/ecometric-backend/services/auth_service.py`](https://github.com/nxthanh01/ecometric-ios/blob/main/ECOMETRIC%20BACKEND/ecometric-backend/services/auth_service.py) (Auth and roles)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ios["iOS application"]
  node_input_view["Data input"]
  node_input_vm["Input state"]
  node_analysis_store["Analysis state"]
  node_dashboard["Dashboard"]
  node_mobile_api["Operational API"]
  node_account["Account session"]
  node_auth_api["Account API"]
  node_auth_view["Authentication"]
  node_ai_view["AI workspace"]
  node_reports["Energy reports<br/>[ReportsView.swift]"]
  node_pdf["PDF export"]
  node_remeasure["Remeasure results"]
end

subgraph group_backend["Backend API and accounts"]
  node_backend_api["FastAPI routes<br/>[main.py]"]
  node_auth_service["Auth and roles<br/>[auth_service.py]"]
  node_email["Email delivery<br/>[email_service.py]"]
end

subgraph group_measurement["Measurement and analysis"]
  node_store["Dataset storage"]
  node_models["Database models<br/>[db_models.py]"]
  node_timeseries["Time-series engine"]
end

subgraph group_decision["Insights and action"]
  node_gemini_service["Gemini insights"]
  node_recommendations["Recommendations"]
  node_knowledge["Knowledge service"]
  node_workflow["Action workflow"]
end

node_user(("Business user"))
node_postgres[("PostgreSQL")]
node_gemini{{"Gemini API"}}

node_user -->|"enters readings"| node_input_view
node_input_view -->|"updates input"| node_input_vm
node_input_vm -->|"submits dataset"| node_mobile_api
node_mobile_api -->|"sends REST requests"| node_backend_api
node_backend_api -->|"stores datasets"| node_store
node_store -->|"uses ORM models"| node_models
node_models -.->|"persists records"| node_postgres
node_backend_api -->|"runs analysis"| node_timeseries
node_timeseries -->|"provides validated data"| node_gemini_service
node_gemini_service -->|"requests interpretation"| node_gemini
node_mobile_api -->|"returns analysis"| node_analysis_store
node_analysis_store -->|"feeds dashboard"| node_dashboard
node_backend_api -->|"routes recommendation requests"| node_recommendations
node_recommendations -->|"uses knowledge records"| node_knowledge
node_analysis_store -.->|"supplies analysis"| node_ai_view
node_user -->|"reviews insights"| node_ai_view
node_backend_api -->|"manages action work"| node_workflow
node_user -->|"reviews reports"| node_reports
node_reports -->|"exports PDF"| node_pdf
node_analysis_store -->|"supplies baseline"| node_remeasure
node_user -->|"compares periods"| node_remeasure
node_user -->|"signs in"| node_auth_view
node_auth_view -->|"updates session"| node_account
node_account -->|"calls account API"| node_auth_api
node_auth_api -.->|"sends account requests"| node_backend_api
node_backend_api -.->|"handles authentication"| node_auth_service
node_auth_service -->|"sends invitations"| node_email
node_auth_service -.->|"stores sessions"| node_postgres

click node_input_view "https://github.com/nxthanh01/ecometric-ios/blob/main/EcoMetric/EcoMetric/Views/Data/DataInputView.swift"
click node_input_vm "https://github.com/nxthanh01/ecometric-ios/blob/main/EcoMetric/EcoMetric/ViewModels/DataInputViewModel.swift"
click node_analysis_store "https://github.com/nxthanh01/ecometric-ios/blob/main/EcoMetric/EcoMetric/ViewModels/AppAnalysisStore.swift"
click node_dashboard "https://github.com/nxthanh01/ecometric-ios/blob/main/EcoMetric/EcoMetric/Views/Dashboard/DashboardView.swift"
click node_mobile_api "https://github.com/nxthanh01/ecometric-ios/blob/main/EcoMetric/EcoMetric/Services/OperationalDataAPIService.swift"
click node_account "https://github.com/nxthanh01/ecometric-ios/blob/main/EcoMetric/EcoMetric/ViewModels/AccountSession.swift"
click node_auth_api "https://github.com/nxthanh01/ecometric-ios/blob/main/EcoMetric/EcoMetric/Services/AccountAPIService.swift"
click node_auth_view "https://github.com/nxthanh01/ecometric-ios/blob/main/EcoMetric/EcoMetric/Views/Profile/AuthenticationView.swift"
click node_backend_api "https://github.com/nxthanh01/ecometric-ios/blob/main/ECOMETRIC%20BACKEND/ecometric-backend/main.py"
click node_auth_service "https://github.com/nxthanh01/ecometric-ios/blob/main/ECOMETRIC%20BACKEND/ecometric-backend/services/auth_service.py"
click node_email "https://github.com/nxthanh01/ecometric-ios/blob/main/ECOMETRIC%20BACKEND/ecometric-backend/services/email_service.py"
click node_store "https://github.com/nxthanh01/ecometric-ios/blob/main/ECOMETRIC%20BACKEND/ecometric-backend/services/data_store_service.py"
click node_models "https://github.com/nxthanh01/ecometric-ios/blob/main/ECOMETRIC%20BACKEND/ecometric-backend/db_models.py"
click node_timeseries "https://github.com/nxthanh01/ecometric-ios/blob/main/ECOMETRIC%20BACKEND/ecometric-backend/services/time_series_service.py"
click node_gemini_service "https://github.com/nxthanh01/ecometric-ios/blob/main/ECOMETRIC%20BACKEND/ecometric-backend/services/gemini_insight_service.py"
click node_recommendations "https://github.com/nxthanh01/ecometric-ios/blob/main/ECOMETRIC%20BACKEND/ecometric-backend/services/recommendation_service.py"
click node_knowledge "https://github.com/nxthanh01/ecometric-ios/blob/main/ECOMETRIC%20BACKEND/ecometric-backend/services/knowledge_service.py"
click node_ai_view "https://github.com/nxthanh01/ecometric-ios/blob/main/EcoMetric/EcoMetric/Views/AI/AIWorkspaceView.swift"
click node_reports "https://github.com/nxthanh01/ecometric-ios/blob/main/EcoMetric/EcoMetric/Views/Reports/ReportsView.swift"
click node_pdf "https://github.com/nxthanh01/ecometric-ios/blob/main/EcoMetric/EcoMetric/Services/EnergyReportPDFService.swift"
click node_workflow "https://github.com/nxthanh01/ecometric-ios/blob/main/ECOMETRIC%20BACKEND/ecometric-backend/services/workflow_service.py"
click node_remeasure "https://github.com/nxthanh01/ecometric-ios/blob/main/EcoMetric/EcoMetric/Views/Reports/OperationalWorkflowView.swift"

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_input_view,node_input_vm,node_analysis_store,node_dashboard,node_mobile_api,node_account,node_auth_api,node_auth_view,node_ai_view,node_reports,node_pdf,node_remeasure,node_user toneBlue
class node_backend_api,node_auth_service,node_email,node_postgres toneAmber
class node_store,node_models,node_timeseries,node_gemini toneMint
class node_gemini_service,node_recommendations,node_knowledge,node_workflow toneRose
```

## Components

### iOS application

- [Data input](https://github.com/nxthanh01/ecometric-ios/blob/main/EcoMetric/EcoMetric/Views/Data/DataInputView.swift): `EcoMetric/EcoMetric/Views/Data/DataInputView.swift`
- [Input state](https://github.com/nxthanh01/ecometric-ios/blob/main/EcoMetric/EcoMetric/ViewModels/DataInputViewModel.swift): `EcoMetric/EcoMetric/ViewModels/DataInputViewModel.swift`
- [Analysis state](https://github.com/nxthanh01/ecometric-ios/blob/main/EcoMetric/EcoMetric/ViewModels/AppAnalysisStore.swift): `EcoMetric/EcoMetric/ViewModels/AppAnalysisStore.swift`
- [Dashboard](https://github.com/nxthanh01/ecometric-ios/blob/main/EcoMetric/EcoMetric/Views/Dashboard/DashboardView.swift): `EcoMetric/EcoMetric/Views/Dashboard/DashboardView.swift`
- [Operational API](https://github.com/nxthanh01/ecometric-ios/blob/main/EcoMetric/EcoMetric/Services/OperationalDataAPIService.swift): `EcoMetric/EcoMetric/Services/OperationalDataAPIService.swift`
- [Account session](https://github.com/nxthanh01/ecometric-ios/blob/main/EcoMetric/EcoMetric/ViewModels/AccountSession.swift): `EcoMetric/EcoMetric/ViewModels/AccountSession.swift`
- [Account API](https://github.com/nxthanh01/ecometric-ios/blob/main/EcoMetric/EcoMetric/Services/AccountAPIService.swift): `EcoMetric/EcoMetric/Services/AccountAPIService.swift`
- [Authentication](https://github.com/nxthanh01/ecometric-ios/blob/main/EcoMetric/EcoMetric/Views/Profile/AuthenticationView.swift): `EcoMetric/EcoMetric/Views/Profile/AuthenticationView.swift`
- [AI workspace](https://github.com/nxthanh01/ecometric-ios/blob/main/EcoMetric/EcoMetric/Views/AI/AIWorkspaceView.swift): `EcoMetric/EcoMetric/Views/AI/AIWorkspaceView.swift`
- [Energy reports](https://github.com/nxthanh01/ecometric-ios/blob/main/EcoMetric/EcoMetric/Views/Reports/ReportsView.swift): `EcoMetric/EcoMetric/Views/Reports/ReportsView.swift`
- [PDF export](https://github.com/nxthanh01/ecometric-ios/blob/main/EcoMetric/EcoMetric/Services/EnergyReportPDFService.swift): `EcoMetric/EcoMetric/Services/EnergyReportPDFService.swift`
- [Remeasure results](https://github.com/nxthanh01/ecometric-ios/blob/main/EcoMetric/EcoMetric/Views/Reports/OperationalWorkflowView.swift): `EcoMetric/EcoMetric/Views/Reports/OperationalWorkflowView.swift`

### Backend API and accounts

- [FastAPI routes](https://github.com/nxthanh01/ecometric-ios/blob/main/ECOMETRIC%20BACKEND/ecometric-backend/main.py): `ECOMETRIC BACKEND/ecometric-backend/main.py`
- [Auth and roles](https://github.com/nxthanh01/ecometric-ios/blob/main/ECOMETRIC%20BACKEND/ecometric-backend/services/auth_service.py): `ECOMETRIC BACKEND/ecometric-backend/services/auth_service.py`
- [Email delivery](https://github.com/nxthanh01/ecometric-ios/blob/main/ECOMETRIC%20BACKEND/ecometric-backend/services/email_service.py): `ECOMETRIC BACKEND/ecometric-backend/services/email_service.py`

### Measurement and analysis

- [Dataset storage](https://github.com/nxthanh01/ecometric-ios/blob/main/ECOMETRIC%20BACKEND/ecometric-backend/services/data_store_service.py): `ECOMETRIC BACKEND/ecometric-backend/services/data_store_service.py`
- [Database models](https://github.com/nxthanh01/ecometric-ios/blob/main/ECOMETRIC%20BACKEND/ecometric-backend/db_models.py): `ECOMETRIC BACKEND/ecometric-backend/db_models.py`
- [Time-series engine](https://github.com/nxthanh01/ecometric-ios/blob/main/ECOMETRIC%20BACKEND/ecometric-backend/services/time_series_service.py): `ECOMETRIC BACKEND/ecometric-backend/services/time_series_service.py`

### Insights and action

- [Gemini insights](https://github.com/nxthanh01/ecometric-ios/blob/main/ECOMETRIC%20BACKEND/ecometric-backend/services/gemini_insight_service.py): `ECOMETRIC BACKEND/ecometric-backend/services/gemini_insight_service.py`
- [Recommendations](https://github.com/nxthanh01/ecometric-ios/blob/main/ECOMETRIC%20BACKEND/ecometric-backend/services/recommendation_service.py): `ECOMETRIC BACKEND/ecometric-backend/services/recommendation_service.py`
- [Knowledge service](https://github.com/nxthanh01/ecometric-ios/blob/main/ECOMETRIC%20BACKEND/ecometric-backend/services/knowledge_service.py): `ECOMETRIC BACKEND/ecometric-backend/services/knowledge_service.py`
- [Action workflow](https://github.com/nxthanh01/ecometric-ios/blob/main/ECOMETRIC%20BACKEND/ecometric-backend/services/workflow_service.py): `ECOMETRIC BACKEND/ecometric-backend/services/workflow_service.py`

### Other components

- **Business user**
- **PostgreSQL**
- **Gemini API**

## Connections

- Business user → Data input: enters readings (evidence: `README.md`)
- Data input → Input state: updates input (evidence: `EcoMetric/EcoMetric/Views/Data/DataInputView.swift`)
- Input state → Operational API: submits dataset (evidence: `EcoMetric/EcoMetric/ViewModels/DataInputViewModel.swift`)
- Operational API → FastAPI routes: sends REST requests (evidence: `EcoMetric/EcoMetric/Services/OperationalDataAPIService.swift`)
- FastAPI routes → Dataset storage: stores datasets (evidence: `README.md`)
- Dataset storage → Database models: uses ORM models (evidence: `ECOMETRIC BACKEND/ecometric-backend/services/data_store_service.py`)
- Database models → PostgreSQL: persists records
- FastAPI routes → Time-series engine: runs analysis (evidence: `README.md`)
- Time-series engine → Gemini insights: provides validated data (evidence: `README.md`)
- Gemini insights → Gemini API: requests interpretation (evidence: `README.md`)
- Operational API → Analysis state: returns analysis (evidence: `EcoMetric/EcoMetric/ViewModels/AppAnalysisStore.swift`)
- Analysis state → Dashboard: feeds dashboard (evidence: `EcoMetric/EcoMetric/Views/Dashboard/DashboardView.swift`)
- FastAPI routes → Recommendations: routes recommendation requests (evidence: `ECOMETRIC BACKEND/ecometric-backend/main.py`)
- Recommendations → Knowledge service: uses knowledge records (evidence: `ECOMETRIC BACKEND/ecometric-backend/services/recommendation_service.py`)
- Analysis state → AI workspace: supplies analysis
- Business user → AI workspace: reviews insights (evidence: `README.md`)
- FastAPI routes → Action workflow: manages action work (evidence: `README.md`)
- Business user → Energy reports: reviews reports (evidence: `README.md`)
- Energy reports → PDF export: exports PDF (evidence: `README.md`)
- Analysis state → Remeasure results: supplies baseline (evidence: `EcoMetric/EcoMetric/Views/Reports/RemeasureView.swift`)
- Business user → Remeasure results: compares periods (evidence: `README.md`)
- Business user → Authentication: signs in (evidence: `README.md`)
- Authentication → Account session: updates session (evidence: `EcoMetric/EcoMetric/Views/Profile/AuthenticationView.swift`)
- Account session → Account API: calls account API (evidence: `EcoMetric/EcoMetric/ViewModels/AccountSession.swift`)
- Account API → FastAPI routes: sends account requests
- FastAPI routes → Auth and roles: handles authentication (evidence: `ECOMETRIC BACKEND/ecometric-backend/main.py`)
- Auth and roles → Email delivery: sends invitations (evidence: `ECOMETRIC BACKEND/ecometric-backend/services/auth_service.py`)
- Auth and roles → PostgreSQL: stores sessions
