# akashatnitr/econest-capstone architecture

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

- Interactive diagram: https://gitdiagram.com/akashatnitr/econest-capstone
- Repository: https://github.com/akashatnitr/econest-capstone

## Overview

EcoNest is an AI-assisted smart-home orchestrator. A signed-in user submits and confirms a request; the Command API sends it to agent routing, and device actions pass through MCP for permission checks, live Home Assistant validation, and auditing. Advisory energy and security reviews do not control devices. Background monitoring and sensor ingestion, analytics, graph context, and the Launchpad/API are additional product branches. Some subsystem links rely on README descriptions because their implementation files were not sampled.

Main entry points: [`orchestrator/agents/orchestrator.py`](https://github.com/akashatnitr/econest-capstone/blob/main/orchestrator/agents/orchestrator.py) (Task Router), [`orchestrator/mcp/executor.py`](https://github.com/akashatnitr/econest-capstone/blob/main/orchestrator/mcp/executor.py) (MCP Dispatch), [`orchestrator/api/command.py`](https://github.com/akashatnitr/econest-capstone/blob/main/orchestrator/api/command.py) (Command Center), [`orchestrator/core/database.py`](https://github.com/akashatnitr/econest-capstone/blob/main/orchestrator/core/database.py) (Database Clients)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User Experience"]
  node_command_api["Command Center<br/>[command.py]"]
  node_launchpad["Launchpad<br/>[launchpad.py]"]
  node_autonomy_api["Autonomy API<br/>[autonomy.py]"]
  node_analytics_api["Insights API<br/>[analytics.py]"]
  node_auth["Authentication<br/>[auth.py]"]
end

subgraph group_agents["Task Orchestration"]
  node_task_router["Task Router<br/>[orchestrator.py]"]
  node_agent_base["Agent Runtime<br/>[base.py]"]
  node_device_agent["Device Agent<br/>[device_agent.py]"]
  node_energy_agent["Energy Agent<br/>[energy_agent.py]"]
  node_security_agent["Security Agent<br/>[security_agent.py]"]
  node_sensor_agent["Sensor Agent<br/>[sensor_agent.py]"]
  node_irrigation_agent["Irrigation Agent"]
  node_llm["Ollama Model<br/>[client.py]"]
end

subgraph group_safety["Safety and Integrations"]
  node_mcp["MCP Dispatch<br/>[executor.py]"]
  node_permissions["Access Policy<br/>[permissions.py]"]
  node_audit["Audit Records<br/>[audit.py]"]
  node_ha_tools["Home Assistant Tools<br/>[ha_tools.py]"]
end

subgraph group_insights["Home Data and Insights"]
  node_ingest["HA State Ingestion<br/>[ha_ingest.py]"]
  node_event_history["Home Event History<br/>[home_events.py]"]
  node_energy_analytics["Energy Analytics"]
  node_weather["Weather Context<br/>[weather.py]"]
  node_graph["Home Relationship Graph<br/>[builder.py]"]
  node_database["Database Clients<br/>[database.py]"]
end

node_user(("Homeowner"))
node_home_assistant["Home Assistant"]
node_mysql[("MySQL")]
node_arcadedb[("ArcadeDB")]

node_user -->|"submits request"| node_command_api
node_command_api -->|"authenticates"| node_auth
node_command_api -->|"submits task"| node_task_router
node_task_router -->|"executes agent"| node_agent_base
node_task_router -->|"routes device task"| node_device_agent
node_task_router -->|"routes energy task"| node_energy_agent
node_task_router -->|"routes security task"| node_security_agent
node_task_router -->|"routes sensor task"| node_sensor_agent
node_task_router -->|"routes irrigation task"| node_irrigation_agent
node_agent_base -->|"dispatches tools"| node_mcp
node_task_router -->|"classifies tasks"| node_llm
node_mcp -->|"checks access"| node_permissions
node_mcp -->|"records activity"| node_audit
node_mcp -->|"dispatches tools"| node_ha_tools
node_ha_tools -->|"validates and acts"| node_home_assistant
node_device_agent -->|"verifies state"| node_home_assistant
node_task_router -->|"records outcomes"| node_audit
node_autonomy_api -.->|"submits tasks"| node_task_router
node_user -->|"requests review"| node_autonomy_api
node_ingest -->|"reads live states"| node_home_assistant
node_ingest -->|"stores readings"| node_database
node_database -->|"persists records"| node_mysql
node_database -->|"queries graph store"| node_arcadedb
node_analytics_api -.->|"serves insights"| node_energy_analytics
node_analytics_api -.->|"serves history"| node_event_history
node_energy_agent -.->|"uses forecast"| node_weather
node_graph -.->|"builds graph"| node_arcadedb
node_launchpad -.->|"opens actions"| node_command_api
node_launchpad -.->|"opens insights"| node_analytics_api

click node_command_api "https://github.com/akashatnitr/econest-capstone/blob/main/orchestrator/api/command.py"
click node_launchpad "https://github.com/akashatnitr/econest-capstone/blob/main/orchestrator/api/launchpad.py"
click node_autonomy_api "https://github.com/akashatnitr/econest-capstone/blob/main/orchestrator/api/autonomy.py"
click node_analytics_api "https://github.com/akashatnitr/econest-capstone/blob/main/orchestrator/api/analytics.py"
click node_auth "https://github.com/akashatnitr/econest-capstone/blob/main/orchestrator/api/auth.py"
click node_task_router "https://github.com/akashatnitr/econest-capstone/blob/main/orchestrator/agents/orchestrator.py"
click node_agent_base "https://github.com/akashatnitr/econest-capstone/blob/main/orchestrator/agents/base.py"
click node_device_agent "https://github.com/akashatnitr/econest-capstone/blob/main/orchestrator/agents/device_agent.py"
click node_energy_agent "https://github.com/akashatnitr/econest-capstone/blob/main/orchestrator/agents/energy_agent.py"
click node_security_agent "https://github.com/akashatnitr/econest-capstone/blob/main/orchestrator/agents/security_agent.py"
click node_sensor_agent "https://github.com/akashatnitr/econest-capstone/blob/main/orchestrator/agents/sensor_agent.py"
click node_irrigation_agent "https://github.com/akashatnitr/econest-capstone/blob/main/orchestrator/agents/irrigation_agent.py"
click node_mcp "https://github.com/akashatnitr/econest-capstone/blob/main/orchestrator/mcp/executor.py"
click node_permissions "https://github.com/akashatnitr/econest-capstone/blob/main/orchestrator/core/permissions.py"
click node_audit "https://github.com/akashatnitr/econest-capstone/blob/main/orchestrator/core/audit.py"
click node_ha_tools "https://github.com/akashatnitr/econest-capstone/blob/main/orchestrator/mcp/tools/ha_tools.py"
click node_llm "https://github.com/akashatnitr/econest-capstone/blob/main/orchestrator/llm/client.py"
click node_ingest "https://github.com/akashatnitr/econest-capstone/blob/main/orchestrator/core/ha_ingest.py"
click node_event_history "https://github.com/akashatnitr/econest-capstone/blob/main/orchestrator/core/home_events.py"
click node_energy_analytics "https://github.com/akashatnitr/econest-capstone/blob/main/orchestrator/core/energy_analytics.py"
click node_weather "https://github.com/akashatnitr/econest-capstone/blob/main/orchestrator/core/weather.py"
click node_graph "https://github.com/akashatnitr/econest-capstone/blob/main/orchestrator/graph/builder.py"
click node_database "https://github.com/akashatnitr/econest-capstone/blob/main/orchestrator/core/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_command_api,node_launchpad,node_autonomy_api,node_analytics_api,node_auth toneBlue
class node_task_router,node_agent_base,node_device_agent,node_energy_agent,node_security_agent,node_sensor_agent,node_irrigation_agent,node_llm,node_mysql,node_arcadedb toneAmber
class node_mcp,node_permissions,node_audit,node_ha_tools toneMint
class node_ingest,node_event_history,node_energy_analytics,node_weather,node_graph,node_database toneRose
class node_user,node_home_assistant toneIndigo
```

## Components

### User Experience

- [Command Center](https://github.com/akashatnitr/econest-capstone/blob/main/orchestrator/api/command.py): `orchestrator/api/command.py`
- [Launchpad](https://github.com/akashatnitr/econest-capstone/blob/main/orchestrator/api/launchpad.py): `orchestrator/api/launchpad.py`
- [Autonomy API](https://github.com/akashatnitr/econest-capstone/blob/main/orchestrator/api/autonomy.py): `orchestrator/api/autonomy.py`
- [Insights API](https://github.com/akashatnitr/econest-capstone/blob/main/orchestrator/api/analytics.py): `orchestrator/api/analytics.py`
- [Authentication](https://github.com/akashatnitr/econest-capstone/blob/main/orchestrator/api/auth.py): `orchestrator/api/auth.py`

### Task Orchestration

- [Task Router](https://github.com/akashatnitr/econest-capstone/blob/main/orchestrator/agents/orchestrator.py): `orchestrator/agents/orchestrator.py`
- [Agent Runtime](https://github.com/akashatnitr/econest-capstone/blob/main/orchestrator/agents/base.py): `orchestrator/agents/base.py`
- [Device Agent](https://github.com/akashatnitr/econest-capstone/blob/main/orchestrator/agents/device_agent.py): `orchestrator/agents/device_agent.py`
- [Energy Agent](https://github.com/akashatnitr/econest-capstone/blob/main/orchestrator/agents/energy_agent.py): `orchestrator/agents/energy_agent.py`
- [Security Agent](https://github.com/akashatnitr/econest-capstone/blob/main/orchestrator/agents/security_agent.py): `orchestrator/agents/security_agent.py`
- [Sensor Agent](https://github.com/akashatnitr/econest-capstone/blob/main/orchestrator/agents/sensor_agent.py): `orchestrator/agents/sensor_agent.py`
- [Irrigation Agent](https://github.com/akashatnitr/econest-capstone/blob/main/orchestrator/agents/irrigation_agent.py): `orchestrator/agents/irrigation_agent.py`
- [Ollama Model](https://github.com/akashatnitr/econest-capstone/blob/main/orchestrator/llm/client.py): `orchestrator/llm/client.py`

### Safety and Integrations

- [MCP Dispatch](https://github.com/akashatnitr/econest-capstone/blob/main/orchestrator/mcp/executor.py): `orchestrator/mcp/executor.py`
- [Access Policy](https://github.com/akashatnitr/econest-capstone/blob/main/orchestrator/core/permissions.py): `orchestrator/core/permissions.py`
- [Audit Records](https://github.com/akashatnitr/econest-capstone/blob/main/orchestrator/core/audit.py): `orchestrator/core/audit.py`
- [Home Assistant Tools](https://github.com/akashatnitr/econest-capstone/blob/main/orchestrator/mcp/tools/ha_tools.py): `orchestrator/mcp/tools/ha_tools.py`

### Home Data and Insights

- [HA State Ingestion](https://github.com/akashatnitr/econest-capstone/blob/main/orchestrator/core/ha_ingest.py): `orchestrator/core/ha_ingest.py`
- [Home Event History](https://github.com/akashatnitr/econest-capstone/blob/main/orchestrator/core/home_events.py): `orchestrator/core/home_events.py`
- [Energy Analytics](https://github.com/akashatnitr/econest-capstone/blob/main/orchestrator/core/energy_analytics.py): `orchestrator/core/energy_analytics.py`
- [Weather Context](https://github.com/akashatnitr/econest-capstone/blob/main/orchestrator/core/weather.py): `orchestrator/core/weather.py`
- [Home Relationship Graph](https://github.com/akashatnitr/econest-capstone/blob/main/orchestrator/graph/builder.py): `orchestrator/graph/builder.py`
- [Database Clients](https://github.com/akashatnitr/econest-capstone/blob/main/orchestrator/core/database.py): `orchestrator/core/database.py`

### Other components

- **Homeowner**
- **Home Assistant**
- **MySQL**
- **ArcadeDB**

## Connections

- Homeowner → Command Center: submits request
- Command Center → Authentication: authenticates (evidence: `orchestrator/api/command.py`)
- Command Center → Task Router: submits task (evidence: `orchestrator/api/command.py`)
- Task Router → Agent Runtime: executes agent (evidence: `orchestrator/agents/orchestrator.py`)
- Task Router → Device Agent: routes device task (evidence: `orchestrator/agents/orchestrator.py`)
- Task Router → Energy Agent: routes energy task (evidence: `orchestrator/agents/orchestrator.py`)
- Task Router → Security Agent: routes security task (evidence: `orchestrator/agents/orchestrator.py`)
- Task Router → Sensor Agent: routes sensor task (evidence: `orchestrator/agents/orchestrator.py`)
- Task Router → Irrigation Agent: routes irrigation task (evidence: `orchestrator/agents/orchestrator.py`)
- Agent Runtime → MCP Dispatch: dispatches tools (evidence: `orchestrator/agents/base.py`)
- Task Router → Ollama Model: classifies tasks (evidence: `orchestrator/agents/orchestrator.py`)
- MCP Dispatch → Access Policy: checks access (evidence: `orchestrator/mcp/executor.py`)
- MCP Dispatch → Audit Records: records activity (evidence: `orchestrator/mcp/executor.py`)
- MCP Dispatch → Home Assistant Tools: dispatches tools
- Home Assistant Tools → Home Assistant: validates and acts
- Device Agent → Home Assistant: verifies state
- Task Router → Audit Records: records outcomes (evidence: `orchestrator/agents/orchestrator.py`)
- Autonomy API → Task Router: submits tasks
- Homeowner → Autonomy API: requests review
- HA State Ingestion → Home Assistant: reads live states (evidence: `orchestrator/core/ha_ingest.py`)
- HA State Ingestion → Database Clients: stores readings (evidence: `orchestrator/core/ha_ingest.py`)
- Database Clients → MySQL: persists records (evidence: `orchestrator/core/database.py`)
- Database Clients → ArcadeDB: queries graph store (evidence: `orchestrator/core/database.py`)
- Insights API → Energy Analytics: serves insights
- Insights API → Home Event History: serves history
- Energy Agent → Weather Context: uses forecast
- Home Relationship Graph → ArcadeDB: builds graph
- Launchpad → Command Center: opens actions
- Launchpad → Insights API: opens insights