# abood-syr/reson-mate architecture

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

- Interactive diagram: https://gitdiagram.com/abood-syr/reson-mate
- Repository: https://github.com/abood-syr/reson-mate

## Overview

This is a FastAPI exchange-rate and metals-price service. Its main result path is quote collection (scheduled or manually requested), provider fallback and validation, persistence of timestamped quotes, then public or API-key-protected quote responses. Separate capabilities include instrument and plan administration, API-key usage limits, public/admin web pages, and health checks. The graph reflects the sampled source and README; some route internals and page-serving wiring were not shown, so those links are omitted or marked unverified.

Main entry points: [`app/services/updater.py`](https://github.com/abood-syr/reson-mate/blob/main/app/services/updater.py) (Quote updater), [`app/routes/api.py`](https://github.com/abood-syr/reson-mate/blob/main/app/routes/api.py) (API routes), [`app/main.py`](https://github.com/abood-syr/reson-mate/blob/main/app/main.py) (Application startup), [`app/core/security.py`](https://github.com/abood-syr/reson-mate/blob/main/app/core/security.py) (API security)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["API and interfaces"]
  node_api["API routes<br/>[api.py]"]
  node_public_ui["Public site<br/>[public.html]"]
  node_admin_ui["Admin page<br/>[admin.html]"]
  node_schemas["Request schemas<br/>[__init__.py]"]
end

subgraph group_ingest["Quote collection"]
  node_scheduler["Update scheduler<br/>[scheduler.py]"]
  node_updater["Quote updater<br/>[updater.py]"]
  node_gemini["Gemini provider<br/>[gemini.py]"]
  node_scraper["Scraper fallback<br/>[scraper.py]"]
end

subgraph group_state["Data and cache"]
  node_models["Domain models<br/>[__init__.py]"]
  node_database_init["Database setup<br/>[database.py]"]
end

subgraph group_access["Access and operations"]
  node_security["API security<br/>[security.py]"]
  node_network["Client IP handling<br/>[network.py]"]
  node_app_main["Application startup<br/>[main.py]"]
end

node_visitor(("Site visitor"))
node_api_client(("API client"))
node_google{{"Gemini and Search"}}
node_source_sites{{"Quote source sites"}}
node_postgres[("PostgreSQL")]
node_redis[("Redis")]

node_visitor -->|"opens"| node_public_ui
node_visitor -->|"opens"| node_admin_ui
node_api_client -->|"requests quotes"| node_api
node_api -->|"validates with"| node_schemas
node_api -->|"authorizes with"| node_security
node_security -->|"resolves client IP"| node_network
node_security -->|"checks rate limits"| node_redis
node_security -->|"checks keys and quotas"| node_postgres
node_api -->|"reads and manages"| node_postgres
node_api -->|"limits and caches"| node_redis
node_app_main -->|"registers routes"| node_api
node_app_main -->|"starts worker"| node_scheduler
node_app_main -->|"configures provider"| node_gemini
node_app_main -->|"configures provider"| node_scraper
node_scheduler -->|"runs updates"| node_updater
node_updater -->|"loads instruments and saves quotes"| node_postgres
node_updater -->|"locks and invalidates cache"| node_redis
node_updater -->|"builds quote records"| node_models
node_updater -.->|"requests observations"| node_gemini
node_updater -.->|"requests observations"| node_scraper
node_gemini -->|"searches and grounds"| node_google
node_scraper -->|"fetches pages"| node_source_sites
node_gemini -->|"validates response"| node_schemas
node_scraper -->|"returns observations"| node_schemas
node_app_main -->|"initializes data"| node_database_init
node_database_init -->|"seeds plans and views"| node_postgres
node_database_init -->|"creates domain records"| node_models

click node_api "https://github.com/abood-syr/reson-mate/blob/main/app/routes/api.py"
click node_public_ui "https://github.com/abood-syr/reson-mate/blob/main/app/web/public.html"
click node_admin_ui "https://github.com/abood-syr/reson-mate/blob/main/app/web/admin.html"
click node_schemas "https://github.com/abood-syr/reson-mate/blob/main/app/schemas/__init__.py"
click node_scheduler "https://github.com/abood-syr/reson-mate/blob/main/app/services/scheduler.py"
click node_updater "https://github.com/abood-syr/reson-mate/blob/main/app/services/updater.py"
click node_gemini "https://github.com/abood-syr/reson-mate/blob/main/app/services/gemini.py"
click node_scraper "https://github.com/abood-syr/reson-mate/blob/main/app/services/scraper.py"
click node_models "https://github.com/abood-syr/reson-mate/blob/main/app/models/__init__.py"
click node_database_init "https://github.com/abood-syr/reson-mate/blob/main/app/core/database.py"
click node_security "https://github.com/abood-syr/reson-mate/blob/main/app/core/security.py"
click node_network "https://github.com/abood-syr/reson-mate/blob/main/app/core/network.py"
click node_app_main "https://github.com/abood-syr/reson-mate/blob/main/app/main.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_api,node_public_ui,node_admin_ui,node_schemas,node_api_client toneBlue
class node_scheduler,node_updater,node_gemini,node_scraper,node_postgres,node_redis toneAmber
class node_models,node_database_init toneMint
class node_security,node_network,node_app_main toneRose
class node_visitor,node_google,node_source_sites toneIndigo
```

## Components

### API and interfaces

- [API routes](https://github.com/abood-syr/reson-mate/blob/main/app/routes/api.py): `app/routes/api.py`
- [Public site](https://github.com/abood-syr/reson-mate/blob/main/app/web/public.html): `app/web/public.html`
- [Admin page](https://github.com/abood-syr/reson-mate/blob/main/app/web/admin.html): `app/web/admin.html`
- [Request schemas](https://github.com/abood-syr/reson-mate/blob/main/app/schemas/__init__.py): `app/schemas/__init__.py`

### Quote collection

- [Update scheduler](https://github.com/abood-syr/reson-mate/blob/main/app/services/scheduler.py): `app/services/scheduler.py`
- [Quote updater](https://github.com/abood-syr/reson-mate/blob/main/app/services/updater.py): `app/services/updater.py`
- [Gemini provider](https://github.com/abood-syr/reson-mate/blob/main/app/services/gemini.py): `app/services/gemini.py`
- [Scraper fallback](https://github.com/abood-syr/reson-mate/blob/main/app/services/scraper.py): `app/services/scraper.py`

### Data and cache

- [Domain models](https://github.com/abood-syr/reson-mate/blob/main/app/models/__init__.py): `app/models/__init__.py`
- [Database setup](https://github.com/abood-syr/reson-mate/blob/main/app/core/database.py): `app/core/database.py`

### Access and operations

- [API security](https://github.com/abood-syr/reson-mate/blob/main/app/core/security.py): `app/core/security.py`
- [Client IP handling](https://github.com/abood-syr/reson-mate/blob/main/app/core/network.py): `app/core/network.py`
- [Application startup](https://github.com/abood-syr/reson-mate/blob/main/app/main.py): `app/main.py`

### Other components

- **Site visitor**
- **API client**
- **Gemini and Search**
- **Quote source sites**
- **PostgreSQL**
- **Redis**

## Connections

- Site visitor → Public site: opens (evidence: `README.md`)
- Site visitor → Admin page: opens (evidence: `README.md`)
- API client → API routes: requests quotes (evidence: `README.md`)
- API routes → Request schemas: validates with (evidence: `app/routes/api.py`)
- API routes → API security: authorizes with (evidence: `app/routes/api.py`)
- API security → Client IP handling: resolves client IP (evidence: `app/core/security.py`)
- API security → Redis: checks rate limits (evidence: `app/core/security.py`)
- API security → PostgreSQL: checks keys and quotas (evidence: `app/core/security.py`)
- API routes → PostgreSQL: reads and manages (evidence: `app/routes/api.py`)
- API routes → Redis: limits and caches (evidence: `README.md`)
- Application startup → API routes: registers routes (evidence: `app/main.py`)
- Application startup → Update scheduler: starts worker (evidence: `app/main.py`)
- Application startup → Gemini provider: configures provider (evidence: `app/main.py`)
- Application startup → Scraper fallback: configures provider (evidence: `app/main.py`)
- Update scheduler → Quote updater: runs updates (evidence: `app/services/scheduler.py`)
- Quote updater → PostgreSQL: loads instruments and saves quotes (evidence: `app/services/updater.py`)
- Quote updater → Redis: locks and invalidates cache (evidence: `app/services/updater.py`)
- Quote updater → Domain models: builds quote records (evidence: `app/services/updater.py`)
- Quote updater → Gemini provider: requests observations
- Quote updater → Scraper fallback: requests observations
- Gemini provider → Gemini and Search: searches and grounds (evidence: `app/services/gemini.py`)
- Scraper fallback → Quote source sites: fetches pages (evidence: `app/services/scraper.py`)
- Gemini provider → Request schemas: validates response (evidence: `app/services/gemini.py`)
- Scraper fallback → Request schemas: returns observations (evidence: `app/services/scraper.py`)
- Application startup → Database setup: initializes data (evidence: `app/main.py`)
- Database setup → PostgreSQL: seeds plans and views (evidence: `app/core/database.py`)
- Database setup → Domain models: creates domain records (evidence: `app/core/database.py`)
