# thomasvtf/zentheris-prototype architecture

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

- Interactive diagram: https://gitdiagram.com/thomasvtf/zentheris-prototype
- Repository: https://github.com/thomasvtf/zentheris-prototype

## Overview

Zentheris is a Colombian household energy-monitoring and reduction app: the Expo client presents household consumption and advice, calls a FastAPI REST API, and the API uses Supabase. The domain spans household setup and membership, simulated readings by household and zone, consumption history, goals and tariffs, and alerts and tips. The README documents those product capabilities; the sampled backend shows router-to-service delegation, while several service implementations remain skeletal or unsampled, so their storage and simulation links are not asserted as verified calls.

Main entry points: [`api/app/services`](https://github.com/thomasvtf/zentheris-prototype/tree/main/api/app/services) (Use-case services), [`api/app/main.py`](https://github.com/thomasvtf/zentheris-prototype/blob/main/api/app/main.py) (API application), [`api/app/routers/users.py`](https://github.com/thomasvtf/zentheris-prototype/blob/main/api/app/routers/users.py) (User and onboarding), [`api/app/routers/members_invitations.py`](https://github.com/thomasvtf/zentheris-prototype/blob/main/api/app/routers/members_invitations.py) (Households and members)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mobile["Mobile app"]
  node_mobile_app["Expo client<br/>[_layout.tsx]"]
  node_dashboard["Consumption dashboard"]
  node_mobile_routes["Feature screens"]
  node_api_client["API client<br/>[client.ts]"]
end

subgraph group_api["REST API"]
  node_api_entry["API application<br/>[main.py]"]
  node_identity_routes["User and onboarding<br/>[users.py]"]
  node_household_routes["Households and members"]
  node_consumption_routes["Consumption and history<br/>[consumption.py]"]
  node_goals_routes["Goals and tariffs<br/>[goals_tariff.py]"]
  node_advice_routes["Alerts and tips<br/>[alerts_tips.py]"]
  node_feature_services["Use-case services"]
  node_authz["Authentication and permissions<br/>[dependencies.py]"]
  node_contracts["API schemas"]
end

subgraph group_domain["Energy domain"]
  node_simulation["Simulated readings"]
  node_consumption_rules["Consumption rules<br/>[alert_rules.py]"]
  node_history_logic["History calculations<br/>[history.py]"]
end

subgraph group_persistence["Persistence and identity"]
  node_database_session["Database sessions<br/>[database.py]"]
  node_supabase_db[("Supabase PostgreSQL")]
  node_supabase_auth["Supabase Auth"]
  node_supabase_storage["Supabase Storage"]
end

node_resident(("Household user"))

node_resident -->|"uses"| node_mobile_app
node_mobile_app -.->|"presents"| node_dashboard
node_mobile_app -.->|"presents"| node_mobile_routes
node_dashboard -.->|"requests data"| node_api_client
node_mobile_routes -.->|"requests data"| node_api_client
node_api_client -->|"calls REST API"| node_api_entry
node_api_entry -->|"registers"| node_identity_routes
node_api_entry -->|"registers"| node_household_routes
node_api_entry -->|"registers"| node_consumption_routes
node_api_entry -->|"registers"| node_goals_routes
node_api_entry -->|"registers"| node_advice_routes
node_identity_routes -->|"delegates to"| node_feature_services
node_household_routes -->|"delegates to"| node_feature_services
node_consumption_routes -->|"delegates to"| node_feature_services
node_goals_routes -->|"delegates to"| node_feature_services
node_advice_routes -->|"delegates to"| node_feature_services
node_identity_routes -->|"requires identity"| node_authz
node_household_routes -->|"requires identity"| node_authz
node_consumption_routes -->|"requires identity"| node_authz
node_identity_routes -.->|"validates with"| node_contracts
node_household_routes -.->|"validates with"| node_contracts
node_consumption_routes -.->|"validates with"| node_contracts
node_feature_services -.->|"may access"| node_database_session
node_feature_services -.->|"may use"| node_simulation
node_feature_services -.->|"may apply"| node_consumption_rules
node_feature_services -.->|"may apply"| node_history_logic
node_database_session -->|"connects to"| node_supabase_db
node_api_entry -.->|"uses"| node_supabase_auth
node_api_entry -.->|"uses"| node_supabase_storage

click node_mobile_app "https://github.com/thomasvtf/zentheris-prototype/blob/main/app/src/app/_layout.tsx"
click node_dashboard "https://github.com/thomasvtf/zentheris-prototype/blob/main/app/src/screens/DashboardScreen.tsx"
click node_mobile_routes "https://github.com/thomasvtf/zentheris-prototype/tree/main/app/src/app"
click node_api_client "https://github.com/thomasvtf/zentheris-prototype/blob/main/app/src/api/client.ts"
click node_api_entry "https://github.com/thomasvtf/zentheris-prototype/blob/main/api/app/main.py"
click node_identity_routes "https://github.com/thomasvtf/zentheris-prototype/blob/main/api/app/routers/users.py"
click node_household_routes "https://github.com/thomasvtf/zentheris-prototype/blob/main/api/app/routers/members_invitations.py"
click node_consumption_routes "https://github.com/thomasvtf/zentheris-prototype/blob/main/api/app/routers/consumption.py"
click node_goals_routes "https://github.com/thomasvtf/zentheris-prototype/blob/main/api/app/routers/goals_tariff.py"
click node_advice_routes "https://github.com/thomasvtf/zentheris-prototype/blob/main/api/app/routers/alerts_tips.py"
click node_feature_services "https://github.com/thomasvtf/zentheris-prototype/tree/main/api/app/services"
click node_authz "https://github.com/thomasvtf/zentheris-prototype/blob/main/api/app/security/dependencies.py"
click node_contracts "https://github.com/thomasvtf/zentheris-prototype/tree/main/api/app/schemas"
click node_simulation "https://github.com/thomasvtf/zentheris-prototype/tree/main/api/app/domain/simulator"
click node_consumption_rules "https://github.com/thomasvtf/zentheris-prototype/blob/main/api/app/domain/alert_rules.py"
click node_history_logic "https://github.com/thomasvtf/zentheris-prototype/blob/main/api/app/domain/history.py"
click node_database_session "https://github.com/thomasvtf/zentheris-prototype/blob/main/api/app/data/database.py"

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_mobile_app,node_dashboard,node_mobile_routes,node_api_client,node_resident toneBlue
class node_api_entry,node_identity_routes,node_household_routes,node_consumption_routes,node_goals_routes,node_advice_routes,node_feature_services,node_authz,node_contracts toneAmber
class node_simulation,node_consumption_rules,node_history_logic toneMint
class node_database_session,node_supabase_db,node_supabase_auth,node_supabase_storage toneRose
```

## Components

### Mobile app

- [Expo client](https://github.com/thomasvtf/zentheris-prototype/blob/main/app/src/app/_layout.tsx): `app/src/app/_layout.tsx`
- [Consumption dashboard](https://github.com/thomasvtf/zentheris-prototype/blob/main/app/src/screens/DashboardScreen.tsx): `app/src/screens/DashboardScreen.tsx`
- [Feature screens](https://github.com/thomasvtf/zentheris-prototype/tree/main/app/src/app): `app/src/app`
- [API client](https://github.com/thomasvtf/zentheris-prototype/blob/main/app/src/api/client.ts): `app/src/api/client.ts`

### REST API

- [API application](https://github.com/thomasvtf/zentheris-prototype/blob/main/api/app/main.py): `api/app/main.py`
- [User and onboarding](https://github.com/thomasvtf/zentheris-prototype/blob/main/api/app/routers/users.py): `api/app/routers/users.py`
- [Households and members](https://github.com/thomasvtf/zentheris-prototype/blob/main/api/app/routers/members_invitations.py): `api/app/routers/members_invitations.py`
- [Consumption and history](https://github.com/thomasvtf/zentheris-prototype/blob/main/api/app/routers/consumption.py): `api/app/routers/consumption.py`
- [Goals and tariffs](https://github.com/thomasvtf/zentheris-prototype/blob/main/api/app/routers/goals_tariff.py): `api/app/routers/goals_tariff.py`
- [Alerts and tips](https://github.com/thomasvtf/zentheris-prototype/blob/main/api/app/routers/alerts_tips.py): `api/app/routers/alerts_tips.py`
- [Use-case services](https://github.com/thomasvtf/zentheris-prototype/tree/main/api/app/services): `api/app/services`
- [Authentication and permissions](https://github.com/thomasvtf/zentheris-prototype/blob/main/api/app/security/dependencies.py): `api/app/security/dependencies.py`
- [API schemas](https://github.com/thomasvtf/zentheris-prototype/tree/main/api/app/schemas): `api/app/schemas`

### Energy domain

- [Simulated readings](https://github.com/thomasvtf/zentheris-prototype/tree/main/api/app/domain/simulator): `api/app/domain/simulator`
- [Consumption rules](https://github.com/thomasvtf/zentheris-prototype/blob/main/api/app/domain/alert_rules.py): `api/app/domain/alert_rules.py`
- [History calculations](https://github.com/thomasvtf/zentheris-prototype/blob/main/api/app/domain/history.py): `api/app/domain/history.py`

### Persistence and identity

- [Database sessions](https://github.com/thomasvtf/zentheris-prototype/blob/main/api/app/data/database.py): `api/app/data/database.py`
- **Supabase PostgreSQL**
- **Supabase Auth**
- **Supabase Storage**

### Other components

- **Household user**

## Connections

- Household user → Expo client: uses
- Expo client → Consumption dashboard: presents
- Expo client → Feature screens: presents
- Consumption dashboard → API client: requests data
- Feature screens → API client: requests data
- API client → API application: calls REST API
- API application → User and onboarding: registers (evidence: `api/app/main.py`)
- API application → Households and members: registers (evidence: `api/app/main.py`)
- API application → Consumption and history: registers (evidence: `api/app/main.py`)
- API application → Goals and tariffs: registers (evidence: `api/app/main.py`)
- API application → Alerts and tips: registers (evidence: `api/app/main.py`)
- User and onboarding → Use-case services: delegates to (evidence: `api/app/routers/users.py`)
- Households and members → Use-case services: delegates to (evidence: `api/app/routers/members_invitations.py`)
- Consumption and history → Use-case services: delegates to (evidence: `api/app/routers/consumption.py`)
- Goals and tariffs → Use-case services: delegates to (evidence: `api/app/routers/goals_tariff.py`)
- Alerts and tips → Use-case services: delegates to (evidence: `api/app/routers/alerts_tips.py`)
- User and onboarding → Authentication and permissions: requires identity (evidence: `api/app/routers/users.py`)
- Households and members → Authentication and permissions: requires identity (evidence: `api/app/routers/members_invitations.py`)
- Consumption and history → Authentication and permissions: requires identity (evidence: `api/app/routers/consumption.py`)
- User and onboarding → API schemas: validates with (evidence: `api/app/routers/users.py`)
- Households and members → API schemas: validates with (evidence: `api/app/routers/members_invitations.py`)
- Consumption and history → API schemas: validates with (evidence: `api/app/routers/consumption.py`)
- Use-case services → Database sessions: may access
- Use-case services → Simulated readings: may use
- Use-case services → Consumption rules: may apply
- Use-case services → History calculations: may apply
- Database sessions → Supabase PostgreSQL: connects to
- API application → Supabase Auth: uses
- API application → Supabase Storage: uses
