# maxoliverbr/eia-api-ts architecture

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

- Interactive diagram: https://gitdiagram.com/maxoliverbr/eia-api-ts
- Repository: https://github.com/maxoliverbr/eia-api-ts

## Overview

eia-api-ts is a typed HTTP wrapper that makes EIA data easier for agents and TypeScript clients to discover and query. The main workflow is to discover a domain, inspect its routes or facets, then submit a unified query that the service validates and proxies to EIA. Search, the agent guide, ontology endpoints, and optional MCP access provide complementary ways to find and use datasets. The graph reflects documented capabilities and sampled wiring; unsampled route implementations are represented only where the README or source index supports them.

Main entry points: [`elysia.config.ts`](https://github.com/maxoliverbr/eia-api-ts/blob/main/elysia.config.ts) (App composition), [`src/domains/index.ts`](https://github.com/maxoliverbr/eia-api-ts/blob/main/src/domains/index.ts) (Domain registry), [`src/lib/eia-client.ts`](https://github.com/maxoliverbr/eia-api-ts/blob/main/src/lib/eia-client.ts) (EIA HTTP client), [`src/ontology/index.ts`](https://github.com/maxoliverbr/eia-api-ts/blob/main/src/ontology/index.ts) (Ontology model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_service["HTTP service"]
  node_app["App composition<br/>[elysia.config.ts]"]
  node_env["Runtime config<br/>[env.ts]"]
  node_meta["Health and metadata<br/>[meta.ts]"]
  node_root["Root endpoint<br/>[root.ts]"]
  node_openapi["OpenAPI spec<br/>[openapi.ts]"]
end

subgraph group_discovery["Discovery and guidance"]
  node_domains["Domain registry<br/>[index.ts]"]
  node_domain_metadata["Domain metadata"]
  node_discovery_routes["Domain discovery<br/>[discovery.ts]"]
  node_facet_routes["Facet inspection<br/>[facets.ts]"]
  node_search_routes["Dataset search<br/>[search.ts]"]
  node_search["Search ranking<br/>[search.ts]"]
  node_guide["Agent guide<br/>[guide.ts]"]
end

subgraph group_data["Energy data access"]
  node_query["Unified query<br/>[query.ts]"]
  node_eia_client["EIA HTTP client<br/>[eia-client.ts]"]
  node_cache[("Response cache<br/>[cache.ts]")]
  node_rate_limiter["Rate limiter<br/>[rate-limiter.ts]"]
  node_errors["Error normalization<br/>[errors.ts]"]
end

subgraph group_knowledge["Ontology"]
  node_ontology_routes["Ontology API<br/>[ontology.ts]"]
  node_ontology_model["Ontology model<br/>[index.ts]"]
  node_ontology_classes["Energy classes<br/>[classes.ts]"]
  node_ontology_relations["Typed relations<br/>[relations.ts]"]
  node_ontology_mappings["Domain mappings<br/>[mappings.ts]"]
  node_facet_bindings["Semantic facets<br/>[facet-bindings.ts]"]
end

subgraph group_mcp["MCP access"]
  node_mcp_routes["MCP endpoint<br/>[mcp.ts]"]
  node_mcp_server["MCP tools and resources<br/>[index.ts]"]
  node_mcp_tools["MCP tools<br/>[tools.ts]"]
  node_mcp_resources["MCP resources<br/>[resources.ts]"]
  node_mcp_client["In-process client<br/>[client.ts]"]
end

node_client(("API client"))
node_eia["EIA API"]

node_client -->|"requests"| node_app
node_app -->|"mounts"| node_root
node_app -->|"mounts"| node_meta
node_app -->|"mounts"| node_discovery_routes
node_app -->|"mounts"| node_facet_routes
node_app -->|"mounts"| node_query
node_app -->|"mounts"| node_search_routes
node_app -->|"mounts"| node_guide
node_app -->|"mounts"| node_ontology_routes
node_app -->|"optionally mounts"| node_mcp_routes
node_app -->|"uses"| node_openapi
node_app -->|"starts with"| node_env
node_discovery_routes -->|"reads"| node_domains
node_domains -->|"aggregates"| node_domain_metadata
node_facet_routes -->|"fetches facets"| node_eia_client
node_facet_routes -->|"reads"| node_domains
node_search_routes -->|"searches with"| node_search
node_search_routes -->|"searches"| node_domains
node_guide -->|"uses metadata"| node_domains
node_query -->|"resolves route"| node_domains
node_query -->|"proxies query"| node_eia_client
node_eia_client -->|"sends requests"| node_eia
node_eia_client -->|"caches responses"| node_cache
node_eia_client -->|"queues requests"| node_rate_limiter
node_eia_client -->|"normalizes errors"| node_errors
node_ontology_routes -->|"queries and exports"| node_ontology_model
node_ontology_routes -->|"searches ontology"| node_search
node_ontology_routes -->|"reads domains"| node_domains
node_ontology_model -->|"uses"| node_ontology_classes
node_ontology_model -->|"uses"| node_ontology_relations
node_ontology_model -->|"uses"| node_ontology_mappings
node_ontology_model -->|"uses"| node_facet_bindings
node_mcp_routes -->|"mounts"| node_mcp_server
node_mcp_server -->|"registers"| node_mcp_tools
node_mcp_server -->|"registers"| node_mcp_resources
node_mcp_tools -->|"calls routes through"| node_mcp_client
node_mcp_resources -->|"calls routes through"| node_mcp_client
node_mcp_client -->|"dispatches in-process"| node_app

click node_app "https://github.com/maxoliverbr/eia-api-ts/blob/main/elysia.config.ts"
click node_env "https://github.com/maxoliverbr/eia-api-ts/blob/main/src/config/env.ts"
click node_meta "https://github.com/maxoliverbr/eia-api-ts/blob/main/src/routes/meta.ts"
click node_root "https://github.com/maxoliverbr/eia-api-ts/blob/main/src/routes/root.ts"
click node_openapi "https://github.com/maxoliverbr/eia-api-ts/blob/main/src/openapi.ts"
click node_domains "https://github.com/maxoliverbr/eia-api-ts/blob/main/src/domains/index.ts"
click node_domain_metadata "https://github.com/maxoliverbr/eia-api-ts/tree/main/src/domains"
click node_discovery_routes "https://github.com/maxoliverbr/eia-api-ts/blob/main/src/routes/discovery.ts"
click node_facet_routes "https://github.com/maxoliverbr/eia-api-ts/blob/main/src/routes/facets.ts"
click node_search_routes "https://github.com/maxoliverbr/eia-api-ts/blob/main/src/routes/search.ts"
click node_search "https://github.com/maxoliverbr/eia-api-ts/blob/main/src/lib/search.ts"
click node_guide "https://github.com/maxoliverbr/eia-api-ts/blob/main/src/routes/guide.ts"
click node_query "https://github.com/maxoliverbr/eia-api-ts/blob/main/src/routes/query.ts"
click node_eia_client "https://github.com/maxoliverbr/eia-api-ts/blob/main/src/lib/eia-client.ts"
click node_cache "https://github.com/maxoliverbr/eia-api-ts/blob/main/src/lib/cache.ts"
click node_rate_limiter "https://github.com/maxoliverbr/eia-api-ts/blob/main/src/lib/rate-limiter.ts"
click node_errors "https://github.com/maxoliverbr/eia-api-ts/blob/main/src/lib/errors.ts"
click node_ontology_routes "https://github.com/maxoliverbr/eia-api-ts/blob/main/src/routes/ontology.ts"
click node_ontology_model "https://github.com/maxoliverbr/eia-api-ts/blob/main/src/ontology/index.ts"
click node_ontology_classes "https://github.com/maxoliverbr/eia-api-ts/blob/main/src/ontology/classes.ts"
click node_ontology_relations "https://github.com/maxoliverbr/eia-api-ts/blob/main/src/ontology/relations.ts"
click node_ontology_mappings "https://github.com/maxoliverbr/eia-api-ts/blob/main/src/ontology/mappings.ts"
click node_facet_bindings "https://github.com/maxoliverbr/eia-api-ts/blob/main/src/ontology/facet-bindings.ts"
click node_mcp_routes "https://github.com/maxoliverbr/eia-api-ts/blob/main/src/routes/mcp.ts"
click node_mcp_server "https://github.com/maxoliverbr/eia-api-ts/blob/main/src/mcp/index.ts"
click node_mcp_tools "https://github.com/maxoliverbr/eia-api-ts/blob/main/src/mcp/tools.ts"
click node_mcp_resources "https://github.com/maxoliverbr/eia-api-ts/blob/main/src/mcp/resources.ts"
click node_mcp_client "https://github.com/maxoliverbr/eia-api-ts/blob/main/src/mcp/client.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_env,node_meta,node_root,node_openapi,node_client toneBlue
class node_domains,node_domain_metadata,node_discovery_routes,node_facet_routes,node_search_routes,node_search,node_guide toneAmber
class node_query,node_eia_client,node_cache,node_rate_limiter,node_errors,node_eia toneMint
class node_ontology_routes,node_ontology_model,node_ontology_classes,node_ontology_relations,node_ontology_mappings,node_facet_bindings toneRose
class node_mcp_routes,node_mcp_server,node_mcp_tools,node_mcp_resources,node_mcp_client toneIndigo
```

## Components

### HTTP service

- [App composition](https://github.com/maxoliverbr/eia-api-ts/blob/main/elysia.config.ts): `elysia.config.ts`
- [Runtime config](https://github.com/maxoliverbr/eia-api-ts/blob/main/src/config/env.ts): `src/config/env.ts`
- [Health and metadata](https://github.com/maxoliverbr/eia-api-ts/blob/main/src/routes/meta.ts): `src/routes/meta.ts`
- [Root endpoint](https://github.com/maxoliverbr/eia-api-ts/blob/main/src/routes/root.ts): `src/routes/root.ts`
- [OpenAPI spec](https://github.com/maxoliverbr/eia-api-ts/blob/main/src/openapi.ts): `src/openapi.ts`

### Discovery and guidance

- [Domain registry](https://github.com/maxoliverbr/eia-api-ts/blob/main/src/domains/index.ts): `src/domains/index.ts`
- [Domain metadata](https://github.com/maxoliverbr/eia-api-ts/tree/main/src/domains): `src/domains`
- [Domain discovery](https://github.com/maxoliverbr/eia-api-ts/blob/main/src/routes/discovery.ts): `src/routes/discovery.ts`
- [Facet inspection](https://github.com/maxoliverbr/eia-api-ts/blob/main/src/routes/facets.ts): `src/routes/facets.ts`
- [Dataset search](https://github.com/maxoliverbr/eia-api-ts/blob/main/src/routes/search.ts): `src/routes/search.ts`
- [Search ranking](https://github.com/maxoliverbr/eia-api-ts/blob/main/src/lib/search.ts): `src/lib/search.ts`
- [Agent guide](https://github.com/maxoliverbr/eia-api-ts/blob/main/src/routes/guide.ts): `src/routes/guide.ts`

### Energy data access

- [Unified query](https://github.com/maxoliverbr/eia-api-ts/blob/main/src/routes/query.ts): `src/routes/query.ts`
- [EIA HTTP client](https://github.com/maxoliverbr/eia-api-ts/blob/main/src/lib/eia-client.ts): `src/lib/eia-client.ts`
- [Response cache](https://github.com/maxoliverbr/eia-api-ts/blob/main/src/lib/cache.ts): `src/lib/cache.ts`
- [Rate limiter](https://github.com/maxoliverbr/eia-api-ts/blob/main/src/lib/rate-limiter.ts): `src/lib/rate-limiter.ts`
- [Error normalization](https://github.com/maxoliverbr/eia-api-ts/blob/main/src/lib/errors.ts): `src/lib/errors.ts`

### Ontology

- [Ontology API](https://github.com/maxoliverbr/eia-api-ts/blob/main/src/routes/ontology.ts): `src/routes/ontology.ts`
- [Ontology model](https://github.com/maxoliverbr/eia-api-ts/blob/main/src/ontology/index.ts): `src/ontology/index.ts`
- [Energy classes](https://github.com/maxoliverbr/eia-api-ts/blob/main/src/ontology/classes.ts): `src/ontology/classes.ts`
- [Typed relations](https://github.com/maxoliverbr/eia-api-ts/blob/main/src/ontology/relations.ts): `src/ontology/relations.ts`
- [Domain mappings](https://github.com/maxoliverbr/eia-api-ts/blob/main/src/ontology/mappings.ts): `src/ontology/mappings.ts`
- [Semantic facets](https://github.com/maxoliverbr/eia-api-ts/blob/main/src/ontology/facet-bindings.ts): `src/ontology/facet-bindings.ts`

### MCP access

- [MCP endpoint](https://github.com/maxoliverbr/eia-api-ts/blob/main/src/routes/mcp.ts): `src/routes/mcp.ts`
- [MCP tools and resources](https://github.com/maxoliverbr/eia-api-ts/blob/main/src/mcp/index.ts): `src/mcp/index.ts`
- [MCP tools](https://github.com/maxoliverbr/eia-api-ts/blob/main/src/mcp/tools.ts): `src/mcp/tools.ts`
- [MCP resources](https://github.com/maxoliverbr/eia-api-ts/blob/main/src/mcp/resources.ts): `src/mcp/resources.ts`
- [In-process client](https://github.com/maxoliverbr/eia-api-ts/blob/main/src/mcp/client.ts): `src/mcp/client.ts`

### Other components

- **API client**
- **EIA API**

## Connections

- API client → App composition: requests
- App composition → Root endpoint: mounts (evidence: `elysia.config.ts`)
- App composition → Health and metadata: mounts (evidence: `elysia.config.ts`)
- App composition → Domain discovery: mounts (evidence: `elysia.config.ts`)
- App composition → Facet inspection: mounts (evidence: `elysia.config.ts`)
- App composition → Unified query: mounts (evidence: `elysia.config.ts`)
- App composition → Dataset search: mounts (evidence: `elysia.config.ts`)
- App composition → Agent guide: mounts (evidence: `elysia.config.ts`)
- App composition → Ontology API: mounts (evidence: `elysia.config.ts`)
- App composition → MCP endpoint: optionally mounts (evidence: `elysia.config.ts`)
- App composition → OpenAPI spec: uses (evidence: `elysia.config.ts`)
- App composition → Runtime config: starts with (evidence: `src/index.ts`)
- Domain discovery → Domain registry: reads (evidence: `src/routes/discovery.ts`)
- Domain registry → Domain metadata: aggregates (evidence: `src/domains/index.ts`)
- Facet inspection → EIA HTTP client: fetches facets (evidence: `src/routes/facets.ts`)
- Facet inspection → Domain registry: reads (evidence: `src/routes/facets.ts`)
- Dataset search → Search ranking: searches with (evidence: `src/routes/search.ts`)
- Dataset search → Domain registry: searches (evidence: `src/routes/search.ts`)
- Agent guide → Domain registry: uses metadata (evidence: `src/routes/guide.ts`)
- Unified query → Domain registry: resolves route (evidence: `src/routes/query.ts`)
- Unified query → EIA HTTP client: proxies query (evidence: `src/routes/query.ts`)
- EIA HTTP client → EIA API: sends requests (evidence: `src/lib/eia-client.ts`)
- EIA HTTP client → Response cache: caches responses (evidence: `src/lib/eia-client.ts`)
- EIA HTTP client → Rate limiter: queues requests (evidence: `src/lib/eia-client.ts`)
- EIA HTTP client → Error normalization: normalizes errors (evidence: `src/lib/eia-client.ts`)
- Ontology API → Ontology model: queries and exports (evidence: `src/routes/ontology.ts`)
- Ontology API → Search ranking: searches ontology (evidence: `src/routes/ontology.ts`)
- Ontology API → Domain registry: reads domains (evidence: `src/routes/ontology.ts`)
- Ontology model → Energy classes: uses (evidence: `src/ontology/index.ts`)
- Ontology model → Typed relations: uses (evidence: `src/ontology/index.ts`)
- Ontology model → Domain mappings: uses (evidence: `src/ontology/index.ts`)
- Ontology model → Semantic facets: uses (evidence: `src/ontology/index.ts`)
- MCP endpoint → MCP tools and resources: mounts
- MCP tools and resources → MCP tools: registers (evidence: `src/mcp/index.ts`)
- MCP tools and resources → MCP resources: registers (evidence: `src/mcp/index.ts`)
- MCP tools → In-process client: calls routes through (evidence: `src/mcp/tools.ts`)
- MCP resources → In-process client: calls routes through (evidence: `src/mcp/resources.ts`)
- In-process client → App composition: dispatches in-process (evidence: `src/mcp/client.ts`)