# jake-herrera/weather-station-backend architecture

> Architecture diagram of the GitHub repository jake-herrera/weather-station-backend, 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/jake-herrera/weather-station-backend
- Repository: https://github.com/jake-herrera/weather-station-backend

## Overview

This backend receives weather readings from an ESP32, validates and timestamps them, stores them in Firebase, and serves readings through REST and MCP tools. The graph separates HTTP handling, MCP access, domain helpers, and persistence. The MCP tool-to-database links are supported by the source index; unsampled tool internals are not described beyond those references.

Main entry points: [`src/db/firebase.ts`](https://github.com/jake-herrera/weather-station-backend/blob/main/src/db/firebase.ts) (Firebase Data Access), [`src/index.ts`](https://github.com/jake-herrera/weather-station-backend/blob/main/src/index.ts) (Express App), [`src/mcp/server.ts`](https://github.com/jake-herrera/weather-station-backend/blob/main/src/mcp/server.ts) (MCP Server), [`src/routes/data.ts`](https://github.com/jake-herrera/weather-station-backend/blob/main/src/routes/data.ts) (Reading Ingestion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_http["REST API"]
  node_app["Express App<br/>[index.ts]"]
  node_ingest["Reading Ingestion<br/>[data.ts]"]
  node_read_api["Reading Queries<br/>[readings.ts]"]
end

subgraph group_mcp["MCP API"]
  node_mcp_transport["MCP Transport<br/>[transport.ts]"]
  node_mcp_server["MCP Server<br/>[server.ts]"]
  node_latest_tool["Latest Tool"]
  node_range_tool["Range Tool"]
  node_stats_tool["Statistics Tool"]
  node_meta_tool["Device Metadata Tool<br/>[get-device-meta.ts]"]
end

subgraph group_domain["Reading Domain"]
  node_validator["Reading Validation"]
  node_reading_schema["Reading Schema<br/>[reading.ts]"]
  node_time_range["Time Range Helpers<br/>[time-range.ts]"]
  node_dns["DNS Configuration<br/>[dns.ts]"]
end

subgraph group_storage["Persistence"]
  node_firebase_adapter["Firebase Data Access<br/>[firebase.ts]"]
  node_firebase_db[("Firebase Realtime DB")]
end

node_esp32(("ESP32 Station"))
node_rest_client(("REST Client"))
node_ai_client(("AI Assistant"))

node_esp32 -->|"sends readings"| node_app
node_rest_client -->|"requests REST"| node_app
node_ai_client -->|"sends MCP requests"| node_mcp_transport
node_app -->|"configures DNS"| node_dns
node_app -->|"mounts route"| node_ingest
node_app -->|"mounts route"| node_read_api
node_app -->|"mounts route"| node_mcp_transport
node_app -->|"initializes"| node_firebase_adapter
node_ingest -->|"validates payload"| node_validator
node_validator -->|"parses against"| node_reading_schema
node_ingest -->|"saves reading"| node_firebase_adapter
node_read_api -->|"validates and computes range"| node_time_range
node_read_api -->|"fetches readings"| node_firebase_adapter
node_mcp_transport -->|"creates server"| node_mcp_server
node_mcp_server -->|"registers tool"| node_latest_tool
node_mcp_server -->|"registers tool"| node_range_tool
node_mcp_server -->|"registers tool"| node_stats_tool
node_mcp_server -->|"registers tool"| node_meta_tool
node_latest_tool -->|"reads latest"| node_firebase_adapter
node_range_tool -->|"reads range"| node_firebase_adapter
node_stats_tool -->|"fetches readings and metadata"| node_firebase_adapter
node_meta_tool -->|"reads metadata"| node_firebase_adapter
node_firebase_adapter -->|"reads and writes"| node_firebase_db

click node_app "https://github.com/jake-herrera/weather-station-backend/blob/main/src/index.ts"
click node_ingest "https://github.com/jake-herrera/weather-station-backend/blob/main/src/routes/data.ts"
click node_read_api "https://github.com/jake-herrera/weather-station-backend/blob/main/src/routes/readings.ts"
click node_mcp_transport "https://github.com/jake-herrera/weather-station-backend/blob/main/src/mcp/transport.ts"
click node_mcp_server "https://github.com/jake-herrera/weather-station-backend/blob/main/src/mcp/server.ts"
click node_latest_tool "https://github.com/jake-herrera/weather-station-backend/blob/main/src/mcp/tools/get-latest-reading.ts"
click node_range_tool "https://github.com/jake-herrera/weather-station-backend/blob/main/src/mcp/tools/get-readings-in-range.ts"
click node_stats_tool "https://github.com/jake-herrera/weather-station-backend/blob/main/src/mcp/tools/get-stats-for-range.ts"
click node_meta_tool "https://github.com/jake-herrera/weather-station-backend/blob/main/src/mcp/tools/get-device-meta.ts"
click node_validator "https://github.com/jake-herrera/weather-station-backend/blob/main/src/services/validate-reading.ts"
click node_reading_schema "https://github.com/jake-herrera/weather-station-backend/blob/main/src/types/reading.ts"
click node_time_range "https://github.com/jake-herrera/weather-station-backend/blob/main/src/services/time-range.ts"
click node_dns "https://github.com/jake-herrera/weather-station-backend/blob/main/src/config/dns.ts"
click node_firebase_adapter "https://github.com/jake-herrera/weather-station-backend/blob/main/src/db/firebase.ts"

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_ingest,node_read_api,node_rest_client toneBlue
class node_mcp_transport,node_mcp_server,node_latest_tool,node_range_tool,node_stats_tool,node_meta_tool toneAmber
class node_validator,node_reading_schema,node_time_range,node_dns toneMint
class node_firebase_adapter,node_firebase_db toneRose
class node_esp32,node_ai_client toneIndigo
```

## Components

### REST API

- [Express App](https://github.com/jake-herrera/weather-station-backend/blob/main/src/index.ts): `src/index.ts`
- [Reading Ingestion](https://github.com/jake-herrera/weather-station-backend/blob/main/src/routes/data.ts): `src/routes/data.ts`
- [Reading Queries](https://github.com/jake-herrera/weather-station-backend/blob/main/src/routes/readings.ts): `src/routes/readings.ts`

### MCP API

- [MCP Transport](https://github.com/jake-herrera/weather-station-backend/blob/main/src/mcp/transport.ts): `src/mcp/transport.ts`
- [MCP Server](https://github.com/jake-herrera/weather-station-backend/blob/main/src/mcp/server.ts): `src/mcp/server.ts`
- [Latest Tool](https://github.com/jake-herrera/weather-station-backend/blob/main/src/mcp/tools/get-latest-reading.ts): `src/mcp/tools/get-latest-reading.ts`
- [Range Tool](https://github.com/jake-herrera/weather-station-backend/blob/main/src/mcp/tools/get-readings-in-range.ts): `src/mcp/tools/get-readings-in-range.ts`
- [Statistics Tool](https://github.com/jake-herrera/weather-station-backend/blob/main/src/mcp/tools/get-stats-for-range.ts): `src/mcp/tools/get-stats-for-range.ts`
- [Device Metadata Tool](https://github.com/jake-herrera/weather-station-backend/blob/main/src/mcp/tools/get-device-meta.ts): `src/mcp/tools/get-device-meta.ts`

### Reading Domain

- [Reading Validation](https://github.com/jake-herrera/weather-station-backend/blob/main/src/services/validate-reading.ts): `src/services/validate-reading.ts`
- [Reading Schema](https://github.com/jake-herrera/weather-station-backend/blob/main/src/types/reading.ts): `src/types/reading.ts`
- [Time Range Helpers](https://github.com/jake-herrera/weather-station-backend/blob/main/src/services/time-range.ts): `src/services/time-range.ts`
- [DNS Configuration](https://github.com/jake-herrera/weather-station-backend/blob/main/src/config/dns.ts): `src/config/dns.ts`

### Persistence

- [Firebase Data Access](https://github.com/jake-herrera/weather-station-backend/blob/main/src/db/firebase.ts): `src/db/firebase.ts`
- **Firebase Realtime DB**

### Other components

- **ESP32 Station**
- **REST Client**
- **AI Assistant**

## Connections

- ESP32 Station → Express App: sends readings (evidence: `README.md`)
- REST Client → Express App: requests REST (evidence: `README.md`)
- AI Assistant → MCP Transport: sends MCP requests (evidence: `README.md`)
- Express App → DNS Configuration: configures DNS (evidence: `src/index.ts`)
- Express App → Reading Ingestion: mounts route (evidence: `src/index.ts`)
- Express App → Reading Queries: mounts route (evidence: `src/index.ts`)
- Express App → MCP Transport: mounts route (evidence: `src/index.ts`)
- Express App → Firebase Data Access: initializes (evidence: `src/index.ts`)
- Reading Ingestion → Reading Validation: validates payload (evidence: `src/routes/data.ts`)
- Reading Validation → Reading Schema: parses against (evidence: `src/services/validate-reading.ts`)
- Reading Ingestion → Firebase Data Access: saves reading (evidence: `src/routes/data.ts`)
- Reading Queries → Time Range Helpers: validates and computes range (evidence: `src/routes/readings.ts`)
- Reading Queries → Firebase Data Access: fetches readings (evidence: `src/routes/readings.ts`)
- MCP Transport → MCP Server: creates server (evidence: `src/mcp/transport.ts`)
- MCP Server → Latest Tool: registers tool (evidence: `src/mcp/server.ts`)
- MCP Server → Range Tool: registers tool (evidence: `src/mcp/server.ts`)
- MCP Server → Statistics Tool: registers tool (evidence: `src/mcp/server.ts`)
- MCP Server → Device Metadata Tool: registers tool (evidence: `src/mcp/server.ts`)
- Latest Tool → Firebase Data Access: reads latest (evidence: `src/mcp/tools/get-latest-reading.ts`)
- Range Tool → Firebase Data Access: reads range (evidence: `src/mcp/tools/get-readings-in-range.ts`)
- Statistics Tool → Firebase Data Access: fetches readings and metadata (evidence: `src/mcp/tools/get-stats-for-range.ts`)
- Device Metadata Tool → Firebase Data Access: reads metadata (evidence: `src/mcp/tools/get-device-meta.ts`)
- Firebase Data Access → Firebase Realtime DB: reads and writes (evidence: `src/db/firebase.ts`)
