# dhanyalk-alt/energy-marketplace architecture

> Architecture diagram of the GitHub repository dhanyalk-alt/energy-marketplace, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dhanyalk-alt/energy-marketplace
- Repository: https://github.com/dhanyalk-alt/energy-marketplace

## Overview

Energy Marketplace supports producer and consumer accounts, role-specific dashboards, renewable-energy listings and purchases, negotiations, and related market features. The principal workflow is sign-in, enter the role-specific marketplace, then list or request energy and manage trades. The README documents PostgreSQL-backed FastAPI APIs; the tree also shows assistant, insights, battery, and weather subsystems. Router registration and sampled auth/weather code support the wiring shown; unsampled route-to-service relationships are left unspecified.

Main entry points: [`energy-backend/app/main.py`](https://github.com/dhanyalk-alt/energy-marketplace/blob/main/energy-backend/app/main.py) (FastAPI application), [`src/App.jsx`](https://github.com/dhanyalk-alt/energy-marketplace/blob/main/src/App.jsx) (Role application), [`energy-backend/app/routers/login.py`](https://github.com/dhanyalk-alt/energy-marketplace/blob/main/energy-backend/app/routers/login.py) (Authentication routes), [`energy-backend/app/routers/weather.py`](https://github.com/dhanyalk-alt/energy-marketplace/blob/main/energy-backend/app/routers/weather.py) (Weather routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web application"]
  node_app["Role application<br/>[App.jsx]"]
  node_auth_ui["Sign-in and register<br/>[AuthGateway.jsx]"]
  node_producer_ui["Producer dashboard<br/>[ProducerLayout.jsx]"]
  node_consumer_ui["Consumer dashboard<br/>[ConsumerLayout.jsx]"]
  node_weather_ui["Weather dashboard<br/>[Forecasting.jsx]"]
  node_weather_hook["Weather data hook<br/>[useWeather.js]"]
  node_weather_client["Weather API client<br/>[weatherService.js]"]
end

subgraph group_api["Marketplace API"]
  node_api_main["FastAPI application<br/>[main.py]"]
  node_login["Authentication routes<br/>[login.py]"]
  node_producer_routes["Producer routes<br/>[producer.py]"]
  node_consumer_routes["Consumer routes<br/>[consumer.py]"]
  node_trading_routes["Trading routes<br/>[trading.py]"]
  node_market_routes["Market routes<br/>[market.py]"]
  node_weather_routes["Weather routes<br/>[weather.py]"]
  node_assistant_routes["Assistant routes<br/>[assistant.py]"]
  node_insights_routes["Producer insights routes"]
  node_battery_routes["Battery routes<br/>[battery_router.py]"]
end

subgraph group_domain["Marketplace services"]
  node_negotiation["Negotiation pricing"]
  node_assistant_context["Permission-safe context"]
  node_insights["Producer recommendations"]
end

subgraph group_state["Persistent state"]
  node_database[("Marketplace database<br/>[database.py]")]
end

subgraph group_integrations["External data"]
  node_external_data["Weather and location data"]
end

node_producer(("Producer"))
node_consumer(("Consumer"))
node_weather_provider["Weather provider"]

node_producer -->|"uses"| node_app
node_consumer -->|"uses"| node_app
node_app -->|"shows"| node_auth_ui
node_auth_ui -->|"registers or signs in"| node_login
node_login -->|"serves through"| node_api_main
node_app -->|"selects role"| node_producer_ui
node_app -->|"selects role"| node_consumer_ui
node_api_main -->|"mounts"| node_login
node_api_main -->|"mounts"| node_producer_routes
node_api_main -->|"mounts"| node_consumer_routes
node_api_main -->|"mounts"| node_trading_routes
node_api_main -->|"mounts"| node_market_routes
node_api_main -->|"mounts"| node_weather_routes
node_api_main -->|"mounts"| node_assistant_routes
node_api_main -->|"mounts"| node_insights_routes
node_api_main -->|"mounts"| node_battery_routes
node_weather_ui -->|"consumes"| node_weather_hook
node_weather_hook -->|"fetches forecast"| node_weather_client
node_weather_client -->|"requests forecast"| node_weather_routes
node_weather_routes -.->|"obtains weather data"| node_external_data
node_external_data -.->|"requests forecast"| node_weather_provider
node_assistant_routes -->|"builds context"| node_assistant_context
node_insights_routes -->|"serves insights"| node_insights
node_trading_routes -->|"calculates offer"| node_negotiation
node_assistant_context -->|"reads records"| node_database
node_insights -->|"reads marketplace data"| node_database

click node_app "https://github.com/dhanyalk-alt/energy-marketplace/blob/main/src/App.jsx"
click node_auth_ui "https://github.com/dhanyalk-alt/energy-marketplace/blob/main/src/components/auth/AuthGateway.jsx"
click node_producer_ui "https://github.com/dhanyalk-alt/energy-marketplace/blob/main/src/components/producer/ProducerLayout.jsx"
click node_consumer_ui "https://github.com/dhanyalk-alt/energy-marketplace/blob/main/src/components/consumer/ConsumerLayout.jsx"
click node_weather_ui "https://github.com/dhanyalk-alt/energy-marketplace/blob/main/src/components/producer/weather/Forecasting.jsx"
click node_weather_hook "https://github.com/dhanyalk-alt/energy-marketplace/blob/main/src/components/producer/weather/useWeather.js"
click node_weather_client "https://github.com/dhanyalk-alt/energy-marketplace/blob/main/src/components/producer/weather/weatherService.js"
click node_api_main "https://github.com/dhanyalk-alt/energy-marketplace/blob/main/energy-backend/app/main.py"
click node_login "https://github.com/dhanyalk-alt/energy-marketplace/blob/main/energy-backend/app/routers/login.py"
click node_producer_routes "https://github.com/dhanyalk-alt/energy-marketplace/blob/main/energy-backend/app/routers/producer.py"
click node_consumer_routes "https://github.com/dhanyalk-alt/energy-marketplace/blob/main/energy-backend/app/routers/consumer.py"
click node_trading_routes "https://github.com/dhanyalk-alt/energy-marketplace/blob/main/energy-backend/app/routers/trading.py"
click node_market_routes "https://github.com/dhanyalk-alt/energy-marketplace/blob/main/energy-backend/app/routers/market.py"
click node_weather_routes "https://github.com/dhanyalk-alt/energy-marketplace/blob/main/energy-backend/app/routers/weather.py"
click node_assistant_routes "https://github.com/dhanyalk-alt/energy-marketplace/blob/main/energy-backend/app/routers/assistant.py"
click node_insights_routes "https://github.com/dhanyalk-alt/energy-marketplace/blob/main/energy-backend/app/routers/producer_insights.py"
click node_battery_routes "https://github.com/dhanyalk-alt/energy-marketplace/blob/main/energy-backend/app/battery_router.py"
click node_negotiation "https://github.com/dhanyalk-alt/energy-marketplace/blob/main/energy-backend/app/services/negotiation_service.py"
click node_assistant_context "https://github.com/dhanyalk-alt/energy-marketplace/blob/main/energy-backend/app/assistant_context_service.py"
click node_insights "https://github.com/dhanyalk-alt/energy-marketplace/blob/main/energy-backend/app/services/producer_insights_service.py"
click node_external_data "https://github.com/dhanyalk-alt/energy-marketplace/blob/main/energy-backend/app/external_data_service.py"
click node_database "https://github.com/dhanyalk-alt/energy-marketplace/blob/main/energy-backend/app/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_app,node_auth_ui,node_producer_ui,node_consumer_ui,node_weather_ui,node_weather_hook,node_weather_client toneBlue
class node_api_main,node_login,node_producer_routes,node_consumer_routes,node_trading_routes,node_market_routes,node_weather_routes,node_assistant_routes,node_insights_routes,node_battery_routes toneAmber
class node_negotiation,node_assistant_context,node_insights toneMint
class node_database toneRose
class node_external_data,node_producer,node_consumer,node_weather_provider toneIndigo
```

## Components

### Web application

- [Role application](https://github.com/dhanyalk-alt/energy-marketplace/blob/main/src/App.jsx): `src/App.jsx`
- [Sign-in and register](https://github.com/dhanyalk-alt/energy-marketplace/blob/main/src/components/auth/AuthGateway.jsx): `src/components/auth/AuthGateway.jsx`
- [Producer dashboard](https://github.com/dhanyalk-alt/energy-marketplace/blob/main/src/components/producer/ProducerLayout.jsx): `src/components/producer/ProducerLayout.jsx`
- [Consumer dashboard](https://github.com/dhanyalk-alt/energy-marketplace/blob/main/src/components/consumer/ConsumerLayout.jsx): `src/components/consumer/ConsumerLayout.jsx`
- [Weather dashboard](https://github.com/dhanyalk-alt/energy-marketplace/blob/main/src/components/producer/weather/Forecasting.jsx): `src/components/producer/weather/Forecasting.jsx`
- [Weather data hook](https://github.com/dhanyalk-alt/energy-marketplace/blob/main/src/components/producer/weather/useWeather.js): `src/components/producer/weather/useWeather.js`
- [Weather API client](https://github.com/dhanyalk-alt/energy-marketplace/blob/main/src/components/producer/weather/weatherService.js): `src/components/producer/weather/weatherService.js`

### Marketplace API

- [FastAPI application](https://github.com/dhanyalk-alt/energy-marketplace/blob/main/energy-backend/app/main.py): `energy-backend/app/main.py`
- [Authentication routes](https://github.com/dhanyalk-alt/energy-marketplace/blob/main/energy-backend/app/routers/login.py): `energy-backend/app/routers/login.py`
- [Producer routes](https://github.com/dhanyalk-alt/energy-marketplace/blob/main/energy-backend/app/routers/producer.py): `energy-backend/app/routers/producer.py`
- [Consumer routes](https://github.com/dhanyalk-alt/energy-marketplace/blob/main/energy-backend/app/routers/consumer.py): `energy-backend/app/routers/consumer.py`
- [Trading routes](https://github.com/dhanyalk-alt/energy-marketplace/blob/main/energy-backend/app/routers/trading.py): `energy-backend/app/routers/trading.py`
- [Market routes](https://github.com/dhanyalk-alt/energy-marketplace/blob/main/energy-backend/app/routers/market.py): `energy-backend/app/routers/market.py`
- [Weather routes](https://github.com/dhanyalk-alt/energy-marketplace/blob/main/energy-backend/app/routers/weather.py): `energy-backend/app/routers/weather.py`
- [Assistant routes](https://github.com/dhanyalk-alt/energy-marketplace/blob/main/energy-backend/app/routers/assistant.py): `energy-backend/app/routers/assistant.py`
- [Producer insights routes](https://github.com/dhanyalk-alt/energy-marketplace/blob/main/energy-backend/app/routers/producer_insights.py): `energy-backend/app/routers/producer_insights.py`
- [Battery routes](https://github.com/dhanyalk-alt/energy-marketplace/blob/main/energy-backend/app/battery_router.py): `energy-backend/app/battery_router.py`

### Marketplace services

- [Negotiation pricing](https://github.com/dhanyalk-alt/energy-marketplace/blob/main/energy-backend/app/services/negotiation_service.py): `energy-backend/app/services/negotiation_service.py`
- [Permission-safe context](https://github.com/dhanyalk-alt/energy-marketplace/blob/main/energy-backend/app/assistant_context_service.py): `energy-backend/app/assistant_context_service.py`
- [Producer recommendations](https://github.com/dhanyalk-alt/energy-marketplace/blob/main/energy-backend/app/services/producer_insights_service.py): `energy-backend/app/services/producer_insights_service.py`

### Persistent state

- [Marketplace database](https://github.com/dhanyalk-alt/energy-marketplace/blob/main/energy-backend/app/database.py): `energy-backend/app/database.py`

### External data

- [Weather and location data](https://github.com/dhanyalk-alt/energy-marketplace/blob/main/energy-backend/app/external_data_service.py): `energy-backend/app/external_data_service.py`

### Other components

- **Producer**
- **Consumer**
- **Weather provider**

## Connections

- Producer → Role application: uses
- Consumer → Role application: uses
- Role application → Sign-in and register: shows
- Sign-in and register → Authentication routes: registers or signs in
- Authentication routes → FastAPI application: serves through
- Role application → Producer dashboard: selects role
- Role application → Consumer dashboard: selects role
- FastAPI application → Authentication routes: mounts
- FastAPI application → Producer routes: mounts
- FastAPI application → Consumer routes: mounts
- FastAPI application → Trading routes: mounts
- FastAPI application → Market routes: mounts
- FastAPI application → Weather routes: mounts
- FastAPI application → Assistant routes: mounts
- FastAPI application → Producer insights routes: mounts
- FastAPI application → Battery routes: mounts
- Weather dashboard → Weather data hook: consumes
- Weather data hook → Weather API client: fetches forecast
- Weather API client → Weather routes: requests forecast
- Weather routes → Weather and location data: obtains weather data
- Weather and location data → Weather provider: requests forecast
- Assistant routes → Permission-safe context: builds context
- Producer insights routes → Producer recommendations: serves insights
- Trading routes → Negotiation pricing: calculates offer
- Permission-safe context → Marketplace database: reads records
- Producer recommendations → Marketplace database: reads marketplace data