# bc1pzzfnxl/eurometrics architecture

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

- Interactive diagram: https://gitdiagram.com/bc1pzzfnxl/eurometrics
- Repository: https://github.com/bc1pzzfnxl/eurometrics

## Overview

1. **What this repository is**
   - EuroMetrics is a client-side Vue dashboard for Eurozone economic and financial indicators.
   - The app is mostly a single-page frontend that fetches data from official public APIs, renders interactive comparisons, and is deployed as static assets.

2. **Top-level runtime and build boundary**
   - The stack is **Vue 3 + TypeScript + Vite**, managed with **Bun**.
   - `src/main.ts` bootstraps the app, and `src/App.vue` is the composition root for the UI.
   - The `dist/` output and `public/` assets indicate static-site deployment rather than a traditional server-rendered backend.

3. **Primary external data boundary**
   - The main external integration is `src/services/ecbApi.ts`, which is the repository’s API access layer.
   - The README says data comes from the **ECB** and **Eurostat** APIs, so the app’s core data flow is:
     - UI interaction → store/filter state changes → API/service fetches → normalized domain data → chart/UI rendering.
   - This is the main boundary between the app and the outside world.

4. **State management layer**
   - `src/stores/bondDataStore.ts` and `src/stores/filtersStore.ts` hold the central application state.
   - `filtersStore` likely tracks user-selected country, maturity, period, and other comparison controls.
   - `bondDataStore` likely caches fetched datasets and derived market data so charts and selectors can share a single source of truth.
   - These stores form the hub between data fetching, computed views, and the UI.

5. **Derived data and chart configuration**
   - `src/composables/useBondData.ts` and `src/composables/useChartOptions.ts` are the main view-model/computation layer.
   - They likely translate raw store data into chart-ready series, labels, formatting, and options.
   - This keeps the rendering components simpler and separates “data shaping” from “presentation.”

6. **Core UI composition**
   - `src/components/BondChart.vue` is the main visualization surface.
   - `ControlBar.vue`, `CountrySelector.vue`, `MaturitySelector.vue`, `PeriodSelector.vue`, and `QuickCompare.vue` are the interaction controls that drive the dashboard state.
   - `ThemeToggle.vue` provides a UI-level presentation setting rather than data filtering.
   - `App.vue` probably arranges these into the dashboard layout and connects them to the stores.

7. **Specialized feature area: AI chat**
   - `src/components/AiChatDock.vue` and `src/agent.js` define a separate assistant/chat subsystem.
   - Architecturally, this appears to be an optional overlay or sidecar feature rather than part of the core charting pipeline.
   - It should be treated as a secondary interaction path that may query or explain dashboard data, not as the primary data source.

8. **Domain model and shared constants**
   - `src/types/bond.ts` defines the core financial data structures used across services, stores, and charts.
   - `src/constants/countries.ts` centralizes Eurozone country metadata.
   - These shared definitions reduce duplication and keep the dashboard’s comparison logic consistent across components.

9. **Reusable UI primitive layer**
   - `src/components/ui/*` contains low-level building blocks such as button, command palette, popover, and select components.
   - These are infrastructure for the dashboard controls rather than business logic.
   - The app’s higher-level selectors and menus are built on top of these primitives, which helps keep the dashboard styling and behavior consistent.

10. **Worker and off-main-thread boundary**
   - `src/worker.js` and `worker-configuration.d.ts` indicate a dedicated worker-based execution path.
   - This suggests some processing is moved off the main UI thread, likely for data transformation, computation, or another performance-sensitive task.
   - For an architecture diagram, this is a useful separate lane from the main Vue render thread.

11. **Presentation and static assets**
   - `src/style.css` and `src/assets` provide app-wide styling and local assets.
   - `index.html` is the Vite entry shell, and `public/` contains deployment-facing files like `robots.txt`, `sitemap.xml`, and `_headers`.
   - These point to a polished static frontend with SEO/hosting configuration baked into the repository.

12. **Deployment and hosting signals**
   - `wrangler.jsonc` and `public/_headers` suggest Cloudflare-oriented deployment or edge/static hosting configuration.
   - This matters architecturally because the app is designed to be served as a static SPA with edge-friendly headers, not from a custom application server.

13. **Testing and validation**
   - `src/eurometrics.test.ts` provides a focused test entry point, likely for core calculation or data-shaping behavior.
   - This suggests the most important logic to validate is in the data/composable/store layer rather than in network or server code.

14. **Mental model for the diagram**
   - Draw the app as:
     - **User interaction layer**: selectors, chart, theme toggle, AI dock.
     - **State/logic layer**: stores + composables.
     - **Data access layer**: ECB/Eurostat service calls.
     - **Render layer**: chart and UI primitives.
     - **Auxiliary execution layer**: worker.
     - **External systems**: official APIs and static hosting/CDN.

Main entry points: [`src/App.vue`](https://github.com/bc1pzzfnxl/eurometrics/blob/main/src/App.vue) (App.vue), [`src/composables/useBondData.ts`](https://github.com/bc1pzzfnxl/eurometrics/blob/main/src/composables/useBondData.ts) (useBondData), [`src/components/ControlBar.vue`](https://github.com/bc1pzzfnxl/eurometrics/blob/main/src/components/ControlBar.vue) (ControlBar), [`src/stores/filtersStore.ts`](https://github.com/bc1pzzfnxl/eurometrics/blob/main/src/stores/filtersStore.ts) (filtersStore)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["App runtime"]
  node_main["main.ts<br/>bootstrap<br/>[main.ts]"]
  node_app["App.vue<br/>composition root<br/>[App.vue]"]
end

subgraph group_data["Data and state"]
  node_bondstore[("bondDataStore<br/>state store<br/>[bondDataStore.ts]")]
  node_filterstore[("filtersStore<br/>state store<br/>[filtersStore.ts]")]
  node_usebond{{"useBondData<br/>view-model<br/>[useBondData.ts]"}}
  node_usechart{{"useChartOptions<br/>chart config<br/>[useChartOptions.ts]"}}
  node_ecbapi["ecbApi<br/>api client<br/>[ecbApi.ts]"]
  node_bondtypes["bond types<br/>domain model<br/>[bond.ts]"]
  node_countries["countries<br/>reference data<br/>[countries.ts]"]
end

subgraph group_ui["Dashboard UI"]
  node_bondchart["BondChart<br/>chart view<br/>[BondChart.vue]"]
  node_controlbar["ControlBar<br/>dashboard controls<br/>[ControlBar.vue]"]
  node_country["CountrySelector<br/>country filter"]
  node_maturity["MaturitySelector<br/>maturity filter"]
  node_period["PeriodSelector<br/>time filter<br/>[PeriodSelector.vue]"]
  node_quickcompare["QuickCompare<br/>comparison control<br/>[QuickCompare.vue]"]
  node_theme["ThemeToggle<br/>ui setting<br/>[ThemeToggle.vue]"]
  node_uikit["UI primitives<br/>component library"]
end

subgraph group_aux["Auxiliary paths"]
  node_aichat["AiChatDock<br/>assistant ui<br/>[AiChatDock.vue]"]
  node_agent["agent.js<br/>assistant runtime<br/>[agent.js]"]
  node_worker["worker.js<br/>[worker.js]"]
end

subgraph group_platform["Platform"]
  node_style["style.css<br/>global styles<br/>[style.css]"]
  node_indexhtml["index.html<br/>spa shell<br/>[index.html]"]
  node_publicassets["public<br/>static assets"]
  node_deploy["wrangler.jsonc<br/>hosting config<br/>[wrangler.jsonc]"]
end

node_main -->|"mounts"| node_app
node_app -->|"composes"| node_controlbar
node_app -->|"composes"| node_bondchart
node_app -->|"composes"| node_theme
node_controlbar -->|"contains"| node_country
node_controlbar -->|"contains"| node_maturity
node_controlbar -->|"contains"| node_period
node_controlbar -->|"contains"| node_quickcompare
node_country -->|"updates"| node_filterstore
node_maturity -->|"updates"| node_filterstore
node_period -->|"updates"| node_filterstore
node_quickcompare -->|"updates"| node_filterstore
node_filterstore -->|"drives"| node_usebond
node_bondstore -->|"supplies"| node_usebond
node_usebond -->|"feeds"| node_usechart
node_usechart -->|"configures"| node_bondchart
node_usebond -->|"renders"| node_bondchart
node_usebond -->|"fetches"| node_ecbapi
node_ecbapi -->|"maps to"| node_bondtypes
node_bondtypes -->|"shapes"| node_bondstore
node_countries -->|"populates"| node_country
node_app -->|"uses"| node_uikit
node_country -->|"uses"| node_uikit
node_maturity -->|"uses"| node_uikit
node_period -->|"uses"| node_uikit
node_quickcompare -->|"uses"| node_uikit
node_aichat -->|"uses"| node_agent
node_worker -.->|"accelerates"| node_usebond
node_indexhtml -->|"loads"| node_main
node_style -->|"styles"| node_app
node_publicassets -->|"served by"| node_indexhtml
node_deploy -->|"configures"| node_publicassets

click node_main "https://github.com/bc1pzzfnxl/eurometrics/blob/main/src/main.ts"
click node_app "https://github.com/bc1pzzfnxl/eurometrics/blob/main/src/App.vue"
click node_bondchart "https://github.com/bc1pzzfnxl/eurometrics/blob/main/src/components/BondChart.vue"
click node_controlbar "https://github.com/bc1pzzfnxl/eurometrics/blob/main/src/components/ControlBar.vue"
click node_country "https://github.com/bc1pzzfnxl/eurometrics/blob/main/src/components/CountrySelector.vue"
click node_maturity "https://github.com/bc1pzzfnxl/eurometrics/blob/main/src/components/MaturitySelector.vue"
click node_period "https://github.com/bc1pzzfnxl/eurometrics/blob/main/src/components/PeriodSelector.vue"
click node_quickcompare "https://github.com/bc1pzzfnxl/eurometrics/blob/main/src/components/QuickCompare.vue"
click node_theme "https://github.com/bc1pzzfnxl/eurometrics/blob/main/src/components/ThemeToggle.vue"
click node_uikit "https://github.com/bc1pzzfnxl/eurometrics/tree/main/src/components/ui"
click node_bondstore "https://github.com/bc1pzzfnxl/eurometrics/blob/main/src/stores/bondDataStore.ts"
click node_filterstore "https://github.com/bc1pzzfnxl/eurometrics/blob/main/src/stores/filtersStore.ts"
click node_usebond "https://github.com/bc1pzzfnxl/eurometrics/blob/main/src/composables/useBondData.ts"
click node_usechart "https://github.com/bc1pzzfnxl/eurometrics/blob/main/src/composables/useChartOptions.ts"
click node_ecbapi "https://github.com/bc1pzzfnxl/eurometrics/blob/main/src/services/ecbApi.ts"
click node_bondtypes "https://github.com/bc1pzzfnxl/eurometrics/blob/main/src/types/bond.ts"
click node_countries "https://github.com/bc1pzzfnxl/eurometrics/blob/main/src/constants/countries.ts"
click node_aichat "https://github.com/bc1pzzfnxl/eurometrics/blob/main/src/components/AiChatDock.vue"
click node_agent "https://github.com/bc1pzzfnxl/eurometrics/blob/main/src/agent.js"
click node_worker "https://github.com/bc1pzzfnxl/eurometrics/blob/main/src/worker.js"
click node_style "https://github.com/bc1pzzfnxl/eurometrics/blob/main/src/style.css"
click node_indexhtml "https://github.com/bc1pzzfnxl/eurometrics/blob/main/index.html"
click node_publicassets "https://github.com/bc1pzzfnxl/eurometrics/tree/main/public"
click node_deploy "https://github.com/bc1pzzfnxl/eurometrics/blob/main/wrangler.jsonc"

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_main,node_app toneBlue
class node_bondstore,node_filterstore,node_usebond,node_usechart,node_ecbapi,node_bondtypes,node_countries toneAmber
class node_bondchart,node_controlbar,node_country,node_maturity,node_period,node_quickcompare,node_theme,node_uikit toneMint
class node_aichat,node_agent,node_worker toneRose
class node_style,node_indexhtml,node_publicassets,node_deploy toneIndigo
```

## Components

### App runtime

Vue/Vite client application and its composition root.

- [main.ts](https://github.com/bc1pzzfnxl/eurometrics/blob/main/src/main.ts): bootstrap · Vue app entry that mounts the dashboard. · `src/main.ts`
- [App.vue](https://github.com/bc1pzzfnxl/eurometrics/blob/main/src/App.vue): composition root · Top-level layout and wiring for the dashboard. · `src/App.vue`

### Data and state

External API access, shared state, and derived view-model logic.

- [bondDataStore](https://github.com/bc1pzzfnxl/eurometrics/blob/main/src/stores/bondDataStore.ts): state store · Shared cache for fetched bond data and derived market state. · `src/stores/bondDataStore.ts`
- [filtersStore](https://github.com/bc1pzzfnxl/eurometrics/blob/main/src/stores/filtersStore.ts): state store · Central user-selection state for dashboard filters. · `src/stores/filtersStore.ts`
- [useBondData](https://github.com/bc1pzzfnxl/eurometrics/blob/main/src/composables/useBondData.ts): view-model · Shapes store data into chart-ready series and display data. · `src/composables/useBondData.ts`
- [useChartOptions](https://github.com/bc1pzzfnxl/eurometrics/blob/main/src/composables/useChartOptions.ts): chart config · Builds chart options and formatting from domain data. · `src/composables/useChartOptions.ts`
- [ecbApi](https://github.com/bc1pzzfnxl/eurometrics/blob/main/src/services/ecbApi.ts): api client · Fetches official ECB/Eurostat data and normalizes responses. · `src/services/ecbApi.ts`
- [bond types](https://github.com/bc1pzzfnxl/eurometrics/blob/main/src/types/bond.ts): domain model · Shared financial data structures and payload shapes. · `src/types/bond.ts`
- [countries](https://github.com/bc1pzzfnxl/eurometrics/blob/main/src/constants/countries.ts): reference data · Eurozone country metadata used across selectors and comparisons. · `src/constants/countries.ts`

### Dashboard UI

Main visualization surface, controls, and reusable UI primitives.

- [BondChart](https://github.com/bc1pzzfnxl/eurometrics/blob/main/src/components/BondChart.vue): chart view · Primary charting surface for Eurozone comparisons. · `src/components/BondChart.vue`
- [ControlBar](https://github.com/bc1pzzfnxl/eurometrics/blob/main/src/components/ControlBar.vue): dashboard controls · Container for the main user filters and actions. · `src/components/ControlBar.vue`
- [CountrySelector](https://github.com/bc1pzzfnxl/eurometrics/blob/main/src/components/CountrySelector.vue): country filter · Selects countries for comparison. · `src/components/CountrySelector.vue`
- [MaturitySelector](https://github.com/bc1pzzfnxl/eurometrics/blob/main/src/components/MaturitySelector.vue): maturity filter · Selects bond maturities and related views. · `src/components/MaturitySelector.vue`
- [PeriodSelector](https://github.com/bc1pzzfnxl/eurometrics/blob/main/src/components/PeriodSelector.vue): time filter · Selects the date range or period window. · `src/components/PeriodSelector.vue`
- [QuickCompare](https://github.com/bc1pzzfnxl/eurometrics/blob/main/src/components/QuickCompare.vue): comparison control · Shortcut interactions for fast side-by-side comparisons. · `src/components/QuickCompare.vue`
- [ThemeToggle](https://github.com/bc1pzzfnxl/eurometrics/blob/main/src/components/ThemeToggle.vue): ui setting · Toggles presentation theme. · `src/components/ThemeToggle.vue`
- [UI primitives](https://github.com/bc1pzzfnxl/eurometrics/tree/main/src/components/ui): component library · Reusable button, command, popover, and select building blocks. · `src/components/ui`

### Auxiliary paths

Secondary execution and assistant features.

- [AiChatDock](https://github.com/bc1pzzfnxl/eurometrics/blob/main/src/components/AiChatDock.vue): assistant ui · Optional chat/assistant overlay for explanations and guidance. · `src/components/AiChatDock.vue`
- [agent.js](https://github.com/bc1pzzfnxl/eurometrics/blob/main/src/agent.js): assistant runtime · Chat/agent-side execution path for the assistant feature. · `src/agent.js`
- [worker.js](https://github.com/bc1pzzfnxl/eurometrics/blob/main/src/worker.js): worker · Off-main-thread processing lane for performance-sensitive work. · `src/worker.js`

### Platform

Static entry, hosting, and deployment-facing assets.

- [style.css](https://github.com/bc1pzzfnxl/eurometrics/blob/main/src/style.css): global styles · App-wide styling for the dashboard. · `src/style.css`
- [index.html](https://github.com/bc1pzzfnxl/eurometrics/blob/main/index.html): spa shell · Vite entry shell for the single-page app. · `index.html`
- [public](https://github.com/bc1pzzfnxl/eurometrics/tree/main/public): static assets · Deployment-facing files such as headers, robots, and sitemap. · `public`
- [wrangler.jsonc](https://github.com/bc1pzzfnxl/eurometrics/blob/main/wrangler.jsonc): hosting config · Cloudflare-oriented deployment and edge hosting configuration. · `wrangler.jsonc`

## Connections

- main.ts → App.vue: mounts · Bootstraps the Vue application and renders the root component.
- App.vue → ControlBar: composes · Places the primary dashboard controls in the layout.
- App.vue → BondChart: composes · Renders the main visualization surface.
- App.vue → ThemeToggle: composes · Includes presentation settings in the shell.
- ControlBar → CountrySelector: contains · Groups the country comparison selector.
- ControlBar → MaturitySelector: contains · Groups the maturity selector.
- ControlBar → PeriodSelector: contains · Groups the period selector.
- ControlBar → QuickCompare: contains · Groups the fast comparison controls.
- CountrySelector → filtersStore: updates · Changes selected countries in shared filter state.
- MaturitySelector → filtersStore: updates · Changes maturity filter state.
- PeriodSelector → filtersStore: updates · Changes selected time window.
- QuickCompare → filtersStore: updates · Applies comparison presets and shortcuts.
- filtersStore → useBondData: drives · Feeds selected filters into derived data shaping.
- bondDataStore → useBondData: supplies · Provides cached and fetched bond data.
- useBondData → useChartOptions: feeds · Provides chart-ready series and labels.
- useChartOptions → BondChart: configures · Supplies display options to the chart view.
- useBondData → BondChart: renders · Provides transformed data for visualization.
- useBondData → ecbApi: fetches · Requests updated official market and macro data.
- ecbApi → bond types: maps to · Normalizes API responses into shared domain shapes.
- bond types → bondDataStore: shapes · Defines the store's core data model.
- countries → CountrySelector: populates · Supplies country metadata to the selector.
- App.vue → UI primitives: uses · Builds controls from reusable UI primitives.
- CountrySelector → UI primitives: uses · Relies on select and command primitives.
- MaturitySelector → UI primitives: uses · Relies on select primitives.
- PeriodSelector → UI primitives: uses · Relies on select/popover primitives.
- QuickCompare → UI primitives: uses · Relies on button, popover, and command primitives.
- AiChatDock → agent.js: uses · Delegates assistant interactions to the agent path.
- worker.js → useBondData: accelerates · Supports off-main-thread processing for data shaping.
- index.html → main.ts: loads · Entry shell loads the application bootstrap.
- style.css → App.vue: styles · Provides global application styling.
- public → index.html: served by · Deployment-facing static files accompany the SPA shell.
- wrangler.jsonc → public: configures · Sets hosting behavior for static delivery.
