From d14a14e7fe81ba547b78b6fb2f6079493064931f Mon Sep 17 00:00:00 2001
From: DeepZone <mail@noisens.de>
Date: Wed, 20 May 2026 15:26:05 +0100
Subject: [PATCH] Add cache freshness transparency across diagnostics and
 reports

---
 .env.example                             |  1 +
 README.md                                | 15 ++++-
 RELEASE_NOTES.md                         | 11 ++++
 backend/app/api/routes_system.py         |  2 +-
 backend/app/config.py                    |  2 +-
 backend/app/core/source_diagnostics.py   | 36 ++++++++++++
 backend/app/main.py                      |  2 +-
 backend/app/services/ripe_stat_client.py | 75 ++++++++++++++++--------
 backend/app/templates/report.html.j2     |  2 +-
 backend/app/templates/report.md.j2       |  4 +-
 backend/pyproject.toml                   |  2 +-
 backend/tests/test_api_smoke.py          |  3 +
 backend/tests/test_ripe_stat_client.py   | 48 +++++++++++++++
 backend/tests/test_source_diagnostics.py | 14 ++++-
 frontend/package-lock.json               |  4 +-
 frontend/package.json                    |  2 +-
 frontend/src/App.tsx                     |  6 +-
 frontend/src/components/Layout.tsx       |  2 +-
 frontend/src/components/ReportView.tsx   | 15 ++++-
 frontend/src/types.ts                    |  4 ++
 20 files changed, 205 insertions(+), 45 deletions(-)
 create mode 100644 backend/tests/test_ripe_stat_client.py

diff --git a/.env.example b/.env.example
index 1762730..18deb2c 100644
--- a/.env.example
+++ b/.env.example
@@ -1,6 +1,7 @@
 DATABASE_URL=sqlite:///./routeforge.db
 HTTP_TIMEOUT_SECONDS=10
 CACHE_TTL_SECONDS=900
+RIPESTAT_CACHE_TTL_SECONDS=900
 CORS_ORIGINS=http://localhost:3000,http://127.0.0.1:3000
 RIPESTAT_BASE_URL=https://stat.ripe.net/data
 ROUTEFORGE_DEMO_MODE=false
diff --git a/README.md b/README.md
index 500289d..932fb58 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
 
 RouteForge is a read-only routing preflight and explainability tool for BGP, RPKI, Registry/IRR and Routing Visibility checks.
 
-Current user-facing version: **v0.4.0-alpha**.
+Current user-facing version: **v0.4.1-alpha**.
 
 <!-- Screenshot gallery placeholder:
 - docs/screenshots/dashboard.png
@@ -32,7 +32,7 @@ Routing changes often require fast but traceable checks across multiple external
 
 ## Current Alpha Status
 
-RouteForge is a **functional alpha** release with production-like workflows for read-only validation and demo usage. Current release target: **v0.4.0-alpha**.
+RouteForge is a **functional alpha** release with production-like workflows for read-only validation and demo usage. Current release target: **v0.4.1-alpha**.
 
 ## Quickstart with Docker Compose
 
@@ -94,6 +94,17 @@ Preflight decision model:
 - `NO-GO`
 - `UNKNOWN`
 
+## Cache and Freshness
+
+RouteForge shows per-source diagnostics indicating whether data was fetched live or served from cache. Cache Age, TTL and Freshness help operators assess how current a result is.
+
+Freshness values:
+- `LIVE`: queried live
+- `FRESH`: cached and fresh
+- `EXPIRING_SOON`: cache close to expiry
+- `STALE`: older than TTL
+- `UNKNOWN`: cache age cannot be determined
+
 ## Export and Sharing
 
 RouteForge reports can be exported/shared as:
diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
index d64b3ee..fb69802 100644
--- a/RELEASE_NOTES.md
+++ b/RELEASE_NOTES.md
@@ -1,5 +1,16 @@
 # Release Notes
 
+## v0.4.1-alpha
+
+### Highlights
+
+- Cache & Freshness Transparency
+- Cache age and TTL shown in diagnostics
+- Freshness classification LIVE/FRESH/EXPIRING_SOON/STALE/UNKNOWN
+- Force Refresh support prepared internally
+
+---
+
 ## v0.4.0-alpha
 
 **Product Demo & Release Readiness**
diff --git a/backend/app/api/routes_system.py b/backend/app/api/routes_system.py
index cd207d0..71650ac 100644
--- a/backend/app/api/routes_system.py
+++ b/backend/app/api/routes_system.py
@@ -9,7 +9,7 @@
 def system_info():
     return {
         'name': 'RouteForge',
-        'version': 'v0.4.0-alpha',
+        'version': 'v0.4.1-alpha',
         'demo_mode': settings.demo_mode,
         'read_only': True,
         'data_sources': ['RIPEstat', 'RIPEstat Whois/Registry'],
diff --git a/backend/app/config.py b/backend/app/config.py
index a2740a6..e2d2c87 100644
--- a/backend/app/config.py
+++ b/backend/app/config.py
@@ -8,7 +8,7 @@ class Settings(BaseSettings):
     database_url: str = "sqlite:///./routeforge.db"
     ripestat_base_url: str = "https://stat.ripe.net/data"
     http_timeout_seconds: int = 10
-    cache_ttl_seconds: int = 900
+    cache_ttl_seconds: int = Field(default=900, validation_alias="RIPESTAT_CACHE_TTL_SECONDS")
     cors_origins: str = "http://192.168.58.167:3000,http://127.0.0.1:3000"
     demo_mode: bool = Field(default=False, validation_alias="ROUTEFORGE_DEMO_MODE")
 
diff --git a/backend/app/core/source_diagnostics.py b/backend/app/core/source_diagnostics.py
index f497859..3f80af5 100644
--- a/backend/app/core/source_diagnostics.py
+++ b/backend/app/core/source_diagnostics.py
@@ -29,6 +29,34 @@
 }
 
 
+def make_cache_metadata(
+    cached: bool | None,
+    cache_age_seconds: int | None = None,
+    cache_ttl_seconds: int | None = None,
+    fetched_at: str | None = None,
+    expires_at: str | None = None,
+) -> dict[str, Any]:
+    freshness = "UNKNOWN"
+    if cached is False:
+        freshness = "LIVE"
+    elif cached is True and cache_age_seconds is not None and cache_ttl_seconds is not None:
+        if cache_age_seconds <= cache_ttl_seconds * 0.75:
+            freshness = "FRESH"
+        elif cache_age_seconds <= cache_ttl_seconds:
+            freshness = "EXPIRING_SOON"
+        else:
+            freshness = "STALE"
+
+    return {
+        "cached": cached,
+        "cache_age_seconds": cache_age_seconds,
+        "cache_ttl_seconds": cache_ttl_seconds,
+        "fetched_at": fetched_at,
+        "expires_at": expires_at,
+        "freshness": freshness,
+    }
+
+
 def make_source_diagnostic(
     name: str,
     endpoint: str,
@@ -37,6 +65,10 @@ def make_source_diagnostic(
     duration_ms: int | None = None,
     cached: bool | None = None,
     cache_age_seconds: int | None = None,
+    cache_ttl_seconds: int | None = None,
+    fetched_at: str | None = None,
+    expires_at: str | None = None,
+    freshness: str | None = None,
     http_status: int | None = None,
     error_type: str | None = None,
     details: dict[str, Any] | None = None,
@@ -49,6 +81,10 @@ def make_source_diagnostic(
         "duration_ms": duration_ms,
         "cached": cached,
         "cache_age_seconds": cache_age_seconds,
+        "cache_ttl_seconds": cache_ttl_seconds,
+        "fetched_at": fetched_at,
+        "expires_at": expires_at,
+        "freshness": freshness,
         "http_status": http_status,
         "error_type": error_type,
         "details": details or {},
diff --git a/backend/app/main.py b/backend/app/main.py
index efc9417..b476d06 100644
--- a/backend/app/main.py
+++ b/backend/app/main.py
@@ -8,7 +8,7 @@
 from app.config import settings
 from app.database import Base, engine
 
-app = FastAPI(title="RouteForge", version="0.4.0")
+app = FastAPI(title="RouteForge", version="0.4.1")
 
 app.add_middleware(
     CORSMiddleware,
diff --git a/backend/app/services/ripe_stat_client.py b/backend/app/services/ripe_stat_client.py
index 15059f1..ba4f588 100644
--- a/backend/app/services/ripe_stat_client.py
+++ b/backend/app/services/ripe_stat_client.py
@@ -1,9 +1,10 @@
 import time
+from datetime import UTC, datetime, timedelta
 
 import httpx
 from sqlalchemy.orm import Session
 
-from app.config import settings
+import app.config as config
 from app.core.source_diagnostics import (
     EMPTY_RESPONSE,
     ERROR,
@@ -12,9 +13,10 @@
     PARSE_ERROR,
     RATE_LIMITED,
     TIMEOUT,
+    make_cache_metadata,
     make_source_diagnostic,
 )
-from app.services.cache import get_cached, set_cached
+from app.services.cache import _cache_key, get_cached, set_cached
 
 
 class RipeStatClient:
@@ -25,65 +27,86 @@ def get(self, endpoint: str, params: dict) -> dict:
         payload, _diagnostic = self.get_with_diagnostics(endpoint, params)
         return payload or {"error": "empty response", "endpoint": endpoint, "params": params}
 
-    def get_with_diagnostics(self, endpoint: str, params: dict) -> tuple[dict | None, dict]:
+    def get_with_diagnostics(self, endpoint: str, params: dict, force_refresh: bool = False) -> tuple[dict | None, dict]:
         started = time.perf_counter()
-        if settings.demo_mode:
+        cache_key = _cache_key(endpoint, params)
+        if config.settings.demo_mode:
             payload = self._get_demo_data(endpoint, params)
+            cache_meta = make_cache_metadata(cached=False)
             return payload, make_source_diagnostic(
                 name=f"RIPEstat {endpoint}",
                 endpoint=endpoint,
                 status=OK,
                 message="Demo data returned",
                 duration_ms=int((time.perf_counter() - started) * 1000),
-                cached=False,
-                details={"demo_mode": True},
+                **cache_meta,
+                details={"demo_mode": True, "force_refresh": force_refresh, "cache_key": cache_key},
             )
 
-        cached_payload = get_cached(self.db, endpoint, params)
-        if cached_payload:
-            return cached_payload, make_source_diagnostic(
-                name=f"RIPEstat {endpoint}",
-                endpoint=endpoint,
-                status=OK,
-                message="RIPEstat response returned from cache",
-                duration_ms=int((time.perf_counter() - started) * 1000),
-                cached=True,
-            )
+        if not force_refresh:
+            cached_payload = get_cached(self.db, endpoint, params)
+            if cached_payload:
+                payload = cached_payload if isinstance(cached_payload, dict) else {"payload": cached_payload}
+                # backward compatibility: older cache may store raw payload
+                if "payload" in payload and "fetched_at" in payload:
+                    wrapped = payload
+                else:
+                    wrapped = {"payload": payload, "fetched_at": datetime.now(UTC).isoformat(), "ttl_seconds": config.settings.cache_ttl_seconds, "cache_key": cache_key}
+
+                fetched_dt = datetime.fromisoformat(wrapped["fetched_at"]).replace(tzinfo=UTC)
+                age_seconds = max(0, int((datetime.now(UTC) - fetched_dt).total_seconds()))
+                ttl = int(wrapped.get("ttl_seconds") or config.settings.cache_ttl_seconds)
+                expires_at = (fetched_dt + timedelta(seconds=ttl)).isoformat()
+                cache_meta = make_cache_metadata(True, age_seconds, ttl, wrapped["fetched_at"], expires_at)
+                return wrapped.get("payload"), make_source_diagnostic(
+                    name=f"RIPEstat {endpoint}",
+                    endpoint=endpoint,
+                    status=OK,
+                    message="RIPEstat response served from cache",
+                    duration_ms=int((time.perf_counter() - started) * 1000),
+                    **cache_meta,
+                    details={"cache_key": cache_key, "fetched_at": wrapped["fetched_at"], "expires_at": expires_at, "force_refresh": False},
+                )
 
-        url = f"{settings.ripestat_base_url.rstrip('/')}/{endpoint}/data.json"
+        url = f"{config.settings.ripestat_base_url.rstrip('/')}/{endpoint}/data.json"
         try:
-            with httpx.Client(timeout=settings.http_timeout_seconds) as client:
+            with httpx.Client(timeout=config.settings.http_timeout_seconds) as client:
                 resp = client.get(url, params=params)
                 if resp.status_code == 429:
                     return {"error": "rate limited", "endpoint": endpoint, "params": params}, make_source_diagnostic(
-                        name=f"RIPEstat {endpoint}", endpoint=endpoint, status=RATE_LIMITED, message="RIPEstat rate limit reached", duration_ms=int((time.perf_counter() - started) * 1000), cached=False, http_status=resp.status_code, error_type="http_429"
+                        name=f"RIPEstat {endpoint}", endpoint=endpoint, status=RATE_LIMITED, message="RIPEstat rate limit reached", duration_ms=int((time.perf_counter() - started) * 1000), cached=False, freshness="LIVE", http_status=resp.status_code, error_type="http_429", details={"cache_key": cache_key, "force_refresh": force_refresh}
                     )
                 resp.raise_for_status()
                 data = resp.json()
         except httpx.TimeoutException as exc:
             return {"error": str(exc), "endpoint": endpoint, "params": params}, make_source_diagnostic(
-                name=f"RIPEstat {endpoint}", endpoint=endpoint, status=TIMEOUT, message="RIPEstat did not respond before timeout", duration_ms=int((time.perf_counter() - started) * 1000), cached=False, error_type=type(exc).__name__
+                name=f"RIPEstat {endpoint}", endpoint=endpoint, status=TIMEOUT, message="RIPEstat did not respond before timeout", duration_ms=int((time.perf_counter() - started) * 1000), cached=False, freshness="LIVE", error_type=type(exc).__name__, details={"cache_key": cache_key, "force_refresh": force_refresh}
             )
         except httpx.HTTPStatusError as exc:
             return {"error": str(exc), "endpoint": endpoint, "params": params}, make_source_diagnostic(
-                name=f"RIPEstat {endpoint}", endpoint=endpoint, status=HTTP_ERROR, message="RIPEstat responded with HTTP error", duration_ms=int((time.perf_counter() - started) * 1000), cached=False, http_status=exc.response.status_code, error_type=type(exc).__name__
+                name=f"RIPEstat {endpoint}", endpoint=endpoint, status=HTTP_ERROR, message="RIPEstat responded with HTTP error", duration_ms=int((time.perf_counter() - started) * 1000), cached=False, freshness="LIVE", http_status=exc.response.status_code, error_type=type(exc).__name__, details={"cache_key": cache_key, "force_refresh": force_refresh}
             )
         except ValueError as exc:
             return {"error": str(exc), "endpoint": endpoint, "params": params}, make_source_diagnostic(
-                name=f"RIPEstat {endpoint}", endpoint=endpoint, status=PARSE_ERROR, message="RIPEstat response could not be parsed as JSON", duration_ms=int((time.perf_counter() - started) * 1000), cached=False, error_type=type(exc).__name__
+                name=f"RIPEstat {endpoint}", endpoint=endpoint, status=PARSE_ERROR, message="RIPEstat response could not be parsed as JSON", duration_ms=int((time.perf_counter() - started) * 1000), cached=False, freshness="LIVE", error_type=type(exc).__name__, details={"cache_key": cache_key, "force_refresh": force_refresh}
             )
         except Exception as exc:
             return {"error": str(exc), "endpoint": endpoint, "params": params}, make_source_diagnostic(
-                name=f"RIPEstat {endpoint}", endpoint=endpoint, status=ERROR, message="RIPEstat request failed", duration_ms=int((time.perf_counter() - started) * 1000), cached=False, error_type=type(exc).__name__
+                name=f"RIPEstat {endpoint}", endpoint=endpoint, status=ERROR, message="RIPEstat request failed", duration_ms=int((time.perf_counter() - started) * 1000), cached=False, freshness="LIVE", error_type=type(exc).__name__, details={"cache_key": cache_key, "force_refresh": force_refresh}
             )
 
         if not data:
             return data, make_source_diagnostic(
-                name=f"RIPEstat {endpoint}", endpoint=endpoint, status=EMPTY_RESPONSE, message="RIPEstat returned an empty response", duration_ms=int((time.perf_counter() - started) * 1000), cached=False
+                name=f"RIPEstat {endpoint}", endpoint=endpoint, status=EMPTY_RESPONSE, message="RIPEstat returned an empty response", duration_ms=int((time.perf_counter() - started) * 1000), cached=False, freshness="LIVE", details={"cache_key": cache_key, "force_refresh": force_refresh}
             )
-        set_cached(self.db, endpoint, params, data)
+
+        fetched_at = datetime.now(UTC).isoformat()
+        ttl = config.settings.cache_ttl_seconds
+        expires_at = (datetime.now(UTC) + timedelta(seconds=ttl)).isoformat()
+        set_cached(self.db, endpoint, params, {"payload": data, "fetched_at": fetched_at, "ttl_seconds": ttl, "cache_key": cache_key})
+        cache_meta = make_cache_metadata(False, None, ttl, fetched_at, expires_at)
         return data, make_source_diagnostic(
-            name=f"RIPEstat {endpoint}", endpoint=endpoint, status=OK, message="RIPEstat response received", duration_ms=int((time.perf_counter() - started) * 1000), cached=False
+            name=f"RIPEstat {endpoint}", endpoint=endpoint, status=OK, message="RIPEstat response received", duration_ms=int((time.perf_counter() - started) * 1000), **cache_meta, details={"cache_key": cache_key, "fetched_at": fetched_at, "expires_at": expires_at, "force_refresh": force_refresh}
         )
 
     def _get_demo_data(self, endpoint: str, params: dict) -> dict:
diff --git a/backend/app/templates/report.html.j2 b/backend/app/templates/report.html.j2
index 641f81c..c2f1100 100644
--- a/backend/app/templates/report.html.j2
+++ b/backend/app/templates/report.html.j2
@@ -50,7 +50,7 @@
 </ul>
 
 <h2>Data Source Diagnostics</h2>
-{% if report.details and report.details.source_diagnostics %}<table border="1" cellpadding="6" cellspacing="0"><tr><th>Quelle</th><th>Endpoint</th><th>Status</th><th>Dauer</th><th>Cache</th><th>Message</th></tr>{% for d in report.details.source_diagnostics %}<tr><td>{{ d.name or '-' }}</td><td>{{ d.endpoint or '-' }}</td><td>{{ d.status or '-' }}</td><td>{{ d.duration_ms if d.duration_ms is not none else '-' }}</td><td>{{ 'HIT' if d.cached is sameas true else ('MISS' if d.cached is sameas false else '-') }}</td><td>{{ d.message or '-' }}{% if d.details %}<details><summary>Details</summary><pre>{{ d.details | tojson(indent=2) }}</pre></details>{% endif %}</td></tr>{% endfor %}</table>{% else %}<p>No source diagnostics available.</p>{% endif %}
+{% if report.details and report.details.source_diagnostics %}<table border="1" cellpadding="6" cellspacing="0"><tr><th>Quelle</th><th>Endpoint</th><th>Status</th><th>Dauer</th><th>Freshness</th><th>Cache</th><th>Cache Age</th><th>TTL</th><th>Message</th></tr>{% for d in report.details.source_diagnostics %}<tr><td>{{ d.name or '-' }}</td><td>{{ d.endpoint or '-' }}</td><td>{{ d.status or '-' }}</td><td>{{ d.duration_ms if d.duration_ms is not none else '-' }}</td><td>{{ d.freshness or 'UNKNOWN' }}</td><td>{{ 'HIT' if d.cached is sameas true else ('MISS' if d.cached is sameas false else '-') }}</td><td>{{ d.cache_age_seconds if d.cache_age_seconds is not none else 'Unknown' }}</td><td>{{ d.cache_ttl_seconds if d.cache_ttl_seconds is not none else 'Unknown' }}</td><td>{{ d.message or '-' }}{% if d.details %}<details><summary>Details</summary><pre>{{ d.details | tojson(indent=2) }}</pre></details>{% endif %}</td></tr>{% endfor %}</table>{% else %}<p>No source diagnostics available.</p>{% endif %}
 
 <h2>Rohdaten</h2>
 <h3>RPKI Rohdaten</h3>
diff --git a/backend/app/templates/report.md.j2 b/backend/app/templates/report.md.j2
index 62035b5..a5a214d 100644
--- a/backend/app/templates/report.md.j2
+++ b/backend/app/templates/report.md.j2
@@ -43,9 +43,9 @@
 
 ## Data Source Diagnostics
 {% if report.details and report.details.source_diagnostics %}
-| Quelle | Endpoint | Status | Dauer | Cache | Message |
+| Quelle | Endpoint | Status | Dauer | Freshness | Cache | Cache Age | TTL | Message |
 |---|---|---|---:|---|---|
-{% for d in report.details.source_diagnostics %}| {{ d.name or '-' }} | {{ d.endpoint or '-' }} | {{ d.status or '-' }} | {{ d.duration_ms if d.duration_ms is not none else '-' }} | {{ 'HIT' if d.cached is sameas true else ('MISS' if d.cached is sameas false else '-') }} | {{ d.message or '-' }} |
+{% for d in report.details.source_diagnostics %}| {{ d.name or '-' }} | {{ d.endpoint or '-' }} | {{ d.status or '-' }} | {{ d.duration_ms if d.duration_ms is not none else '-' }} | {{ d.freshness or 'UNKNOWN' }} | {{ 'HIT' if d.cached is sameas true else ('MISS' if d.cached is sameas false else '-') }} | {{ d.cache_age_seconds if d.cache_age_seconds is not none else 'Unknown' }} | {{ d.cache_ttl_seconds if d.cache_ttl_seconds is not none else 'Unknown' }} | {{ d.message or '-' }} |
 {% endfor %}
 {% else %}No source diagnostics available.
 {% endif %}
diff --git a/backend/pyproject.toml b/backend/pyproject.toml
index 9065ed7..beaa6e3 100644
--- a/backend/pyproject.toml
+++ b/backend/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "routeforge-backend"
-version = "0.4.0"
+version = "0.4.1"
 description = "RouteForge backend"
 requires-python = ">=3.12"
 dependencies = [
diff --git a/backend/tests/test_api_smoke.py b/backend/tests/test_api_smoke.py
index 8b3618b..754f931 100644
--- a/backend/tests/test_api_smoke.py
+++ b/backend/tests/test_api_smoke.py
@@ -34,6 +34,7 @@ def test_prefix_check_without_origin_as() -> None:
     assert payload.get('markdown')
     assert payload.get('html')
     assert payload.get('details', {}).get('resource_holder')
+    assert any('freshness' in d for d in payload.get('details', {}).get('source_diagnostics', []) if isinstance(d, dict))
 
 
 def test_asn_check() -> None:
@@ -47,6 +48,7 @@ def test_asn_check() -> None:
     assert 'extracted_prefixes' in details
     assert details.get('rpki_batch', {}).get('available') is True
     assert details.get('resource_holder')
+    assert any('freshness' in d for d in details.get('source_diagnostics', []) if isinstance(d, dict))
 
 
 def test_asn_check_without_prefixes_has_batch_reason() -> None:
@@ -112,6 +114,7 @@ def test_preflight_check() -> None:
     assert 'routing_visibility' in checks
     assert payload.get('details', {}).get('preflight_mode') is True
     assert isinstance(payload.get('details', {}).get('source_diagnostics'), list)
+    assert any('freshness' in d for d in payload.get('details', {}).get('source_diagnostics', []) if isinstance(d, dict))
     assert payload.get('details', {}).get('resource_holder')
     assert payload.get('details', {}).get('preflight_decision') in {'GO', 'CAUTION', 'NO-GO', 'UNKNOWN'}
 
diff --git a/backend/tests/test_ripe_stat_client.py b/backend/tests/test_ripe_stat_client.py
new file mode 100644
index 0000000..95f8b97
--- /dev/null
+++ b/backend/tests/test_ripe_stat_client.py
@@ -0,0 +1,48 @@
+from app.config import Settings
+from app.services.ripe_stat_client import RipeStatClient
+
+
+class DummyQuery:
+    def filter(self, *_args, **_kwargs):
+        return self
+
+    def first(self):
+        return None
+
+
+class DummyDb:
+    def query(self, *_args, **_kwargs):
+        return DummyQuery()
+
+    def add(self, *_args, **_kwargs):
+        return None
+
+    def commit(self):
+        return None
+
+
+def test_demo_mode_diagnostics_live(monkeypatch):
+    import app.config as config
+
+    monkeypatch.setattr(config, 'settings', Settings(_env_file=None, ROUTEFORGE_DEMO_MODE=True))
+    from app.services import ripe_stat_client as module
+
+    client = RipeStatClient(DummyDb())
+    _payload, diag = client.get_with_diagnostics('as-overview', {'resource': 'AS3320'})
+    assert diag['cached'] is False
+    assert diag['freshness'] == 'LIVE'
+    assert diag['message'] == 'Demo data returned'
+
+
+def test_cached_response_has_age(monkeypatch):
+    import app.config as config
+
+    monkeypatch.setattr(config, 'settings', Settings(_env_file=None, ROUTEFORGE_DEMO_MODE=False))
+    from app.services import ripe_stat_client as module
+
+    monkeypatch.setattr(module, 'get_cached', lambda *_args, **_kwargs: {'payload': {'data': {}}, 'fetched_at': '2026-05-20T00:00:00+00:00', 'ttl_seconds': 900})
+    client = RipeStatClient(DummyDb())
+    _payload, diag = client.get_with_diagnostics('as-overview', {'resource': 'AS3320'})
+    assert diag['cached'] is True
+    assert isinstance(diag['cache_age_seconds'], int)
+    assert diag['cache_ttl_seconds'] == 900
diff --git a/backend/tests/test_source_diagnostics.py b/backend/tests/test_source_diagnostics.py
index 76c2087..c68ab4f 100644
--- a/backend/tests/test_source_diagnostics.py
+++ b/backend/tests/test_source_diagnostics.py
@@ -1,13 +1,14 @@
-from app.core.source_diagnostics import KNOWN_SOURCE_STATUSES, OK, TIMEOUT, make_source_diagnostic
+from app.core.source_diagnostics import KNOWN_SOURCE_STATUSES, OK, TIMEOUT, make_cache_metadata, make_source_diagnostic
 
 
 def test_make_source_diagnostic_shape() -> None:
-    d = make_source_diagnostic("RIPEstat routing-status", "routing-status", OK, "ok", duration_ms=12, cached=False)
+    d = make_source_diagnostic("RIPEstat routing-status", "routing-status", OK, "ok", duration_ms=12, cached=False, freshness="LIVE")
     assert d["name"] == "RIPEstat routing-status"
     assert d["endpoint"] == "routing-status"
     assert d["status"] == OK
     assert d["duration_ms"] == 12
     assert d["cached"] is False
+    assert d["freshness"] == "LIVE"
     assert isinstance(d["details"], dict)
 
 
@@ -18,6 +19,15 @@ def test_make_source_diagnostic_optional_defaults() -> None:
     assert d["error_type"] is None
 
 
+def test_make_cache_metadata_freshness_rules() -> None:
+    assert make_cache_metadata(False)["freshness"] == "LIVE"
+    assert make_cache_metadata(True, 100, 900)["freshness"] == "FRESH"
+    assert make_cache_metadata(True, 800, 900)["freshness"] == "EXPIRING_SOON"
+    assert make_cache_metadata(True, 1000, 900)["freshness"] == "STALE"
+    assert make_cache_metadata(True)["freshness"] == "UNKNOWN"
+    assert make_cache_metadata(None)["freshness"] == "UNKNOWN"
+
+
 def test_known_status_values_present() -> None:
     for value in [OK, TIMEOUT, "HTTP_ERROR", "PARSE_ERROR", "UNKNOWN_STRUCTURE", "RATE_LIMITED", "CACHE_HIT", "CACHE_MISS", "EMPTY_RESPONSE", "NO_DATA", "ERROR"]:
         assert value in KNOWN_SOURCE_STATUSES
diff --git a/frontend/package-lock.json b/frontend/package-lock.json
index 58544d8..b7156dd 100644
--- a/frontend/package-lock.json
+++ b/frontend/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "routeforge-frontend",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "routeforge-frontend",
-      "version": "0.4.0",
+      "version": "0.4.1",
       "dependencies": {
         "react": "^18.3.1",
         "react-dom": "^18.3.1"
diff --git a/frontend/package.json b/frontend/package.json
index 70a56f6..963b3a3 100644
--- a/frontend/package.json
+++ b/frontend/package.json
@@ -1,6 +1,6 @@
 {
   "name": "routeforge-frontend",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "private": true,
   "type": "module",
   "scripts": {
diff --git a/frontend/src/App.tsx b/frontend/src/App.tsx
index e68c238..c39f08b 100644
--- a/frontend/src/App.tsx
+++ b/frontend/src/App.tsx
@@ -15,7 +15,7 @@ export default function App() {
   const [copyMessage, setCopyMessage] = useState('')
   const [system, setSystem] = useState<SystemInfo | null>(null)
   useEffect(() => { getReports().then(setReports).catch(() => setReports([])); getSystemInfo().then(setSystem).catch(() => null) }, [])
-  const systemLine = useMemo(() => system ? `${system.name} ${system.version} · mode=${system.demo_mode ? 'DEMO' : 'LIVE'} · read_only=${String(system.read_only)}` : 'RouteForge v0.4.0-alpha · read-only preflight checks', [system])
+  const systemLine = useMemo(() => system ? `${system.name} ${system.version} · mode=${system.demo_mode ? 'DEMO' : 'LIVE'} · read_only=${String(system.read_only)}` : 'RouteForge v0.4.1-alpha · read-only preflight checks', [system])
   const title = { dashboard: 'Dashboard', asn: 'ASN Check', prefix: 'Prefix Check', preflight: 'Preflight Check', reports: 'Reports', about: 'About RouteForge' }[active]
   const notify = (message: string) => {
     setCopyMessage(message)
@@ -37,7 +37,7 @@ export default function App() {
 
   return <Layout active={active} onNav={setActive} systemLine={systemLine} title={title} demoMode={Boolean(system?.demo_mode)}>
     {active === 'dashboard' && <section className='space-y-4'>
-      <article className='rf-card p-6'><h1 className='text-2xl font-bold'>RouteForge v0.4.0-alpha</h1><p className='mt-2 text-slate-600'>Modernes read-only Operator-Tool für Preflight Checks von ASN, Prefix, RPKI und Registry/IRR.</p><p className='mt-3 rf-alert border-slate-200 bg-slate-50 text-slate-700'>Security-Modell: ausschließlich read-only, keine writes/deployments.</p></article>
+      <article className='rf-card p-6'><h1 className='text-2xl font-bold'>RouteForge v0.4.1-alpha</h1><p className='mt-2 text-slate-600'>Modernes read-only Operator-Tool für Preflight Checks von ASN, Prefix, RPKI und Registry/IRR.</p><p className='mt-3 rf-alert border-slate-200 bg-slate-50 text-slate-700'>Security-Modell: ausschließlich read-only, keine writes/deployments.</p></article>
       <div className='grid gap-3 md:grid-cols-3'>{[['ASN Check', 'asn'], ['Prefix Check', 'prefix'], ['Preflight Check', 'preflight'], ['Reports', 'reports']].map(([x, key]) => <button key={x} onClick={() => setActive(key as NavKey)} className='rf-card p-4 text-left hover:border-blue-300'><h3 className='font-semibold'>{x}</h3></button>)}</div>
       <article className='rf-card p-4'><h2 className='mb-2 font-semibold'>Letzte Reports</h2>{reports.length === 0 ? <div className='rounded-xl border border-dashed border-slate-300 p-6 text-sm text-slate-500'>Noch keine Reports vorhanden.</div> : <div className='overflow-x-auto'><table className='w-full text-sm'><thead><tr className='border-b text-left'><th className='py-2'>Zeit</th><th>Typ</th><th>Resource</th><th>Holder</th><th>Status</th></tr></thead><tbody>{reports.slice(0, 8).map(r => <tr key={r.report_id} className='border-b border-slate-100'><td className='py-2'>{new Date(r.created_at).toLocaleString()}</td><td>{r.check_type === 'preflight' ? 'Preflight' : r.check_type}</td><td>{r.input_resource}</td><td>{r.holder || 'Unknown'}</td><td><StatusBadge status={r.status} /></td></tr>)}</tbody></table></div>}</article>
     </section>}
@@ -45,6 +45,6 @@ export default function App() {
     {active === 'prefix' && <PrefixCheckForm />}
     {active === 'preflight' && <PreflightCheckForm />}
     {active === 'reports' && <section className='rf-card p-4'><h2 className='mb-3 text-xl font-semibold'>Reports</h2>{reports.length===0 ? <div className='rounded-xl border border-dashed border-slate-300 p-6 text-sm text-slate-500'>Noch keine Reports vorhanden.</div> : <div className='overflow-x-auto'><table className='w-full text-sm'><thead><tr className='border-b text-left'><th>Zeitpunkt</th><th>Typ</th><th>Resource</th><th>Origin-AS</th><th>Holder</th><th>Status</th><th>Kurzfassung</th><th>Actions</th></tr></thead><tbody>{reports.map(r=><tr key={r.report_id} className='border-b border-slate-100'><td className='py-2'>{new Date(r.created_at).toLocaleString()}</td><td>{r.check_type === 'preflight' ? 'Preflight' : r.check_type}</td><td>{r.input_resource}</td><td>{r.origin_as || '-'}</td><td>{r.holder || 'Unknown'}</td><td><StatusBadge status={r.status} /></td><td>{r.summary}</td><td><div className='flex flex-wrap gap-1'><button className='rf-btn-secondary' onClick={() => window.open(`/api/reports/${r.report_id}`, '_blank')}>Open</button><button className='rf-btn-secondary' onClick={async ()=>copyText(await getReportSummary(r.report_id), 'Summary copied')}>Copy Summary</button><button className='rf-btn-secondary' onClick={async ()=>downloadText(`routeforge-report-${r.report_id}.md`, await getReportMarkdown(r.report_id), 'text/markdown;charset=utf-8')}>Download Markdown</button><button className='rf-btn-secondary' onClick={async ()=>downloadText(`routeforge-report-${r.report_id}.html`, await getReportHtml(r.report_id), 'text/html;charset=utf-8')}>Download HTML</button></div></td></tr>)}</tbody></table></div>}{copyMessage && <p className='mt-2 text-sm text-slate-600'>{copyMessage}</p>}</section>}
-    {active === 'about' && <section className='rf-card p-5 space-y-2 text-sm text-slate-700'><p>RouteForge liefert nachvollziehbare Routing-Preflightchecks für technische Operator-Workflows.</p><p><b>Datenquellen:</b> RPKI Validator APIs und Registry/IRR Quellen.</p><p><b>Modell:</b> read-only Betrieb.</p><p><b>Limitations:</b> Externe Datenquellen können unvollständig oder verzögert sein.</p><p><b>Version:</b> v0.4.0-alpha</p></section>}
+    {active === 'about' && <section className='rf-card p-5 space-y-2 text-sm text-slate-700'><p>RouteForge liefert nachvollziehbare Routing-Preflightchecks für technische Operator-Workflows.</p><p><b>Datenquellen:</b> RPKI Validator APIs und Registry/IRR Quellen.</p><p><b>Modell:</b> read-only Betrieb.</p><p><b>Limitations:</b> Externe Datenquellen können unvollständig oder verzögert sein.</p><p><b>Version:</b> v0.4.1-alpha</p></section>}
   </Layout>
 }
diff --git a/frontend/src/components/Layout.tsx b/frontend/src/components/Layout.tsx
index f4288dc..188ea05 100644
--- a/frontend/src/components/Layout.tsx
+++ b/frontend/src/components/Layout.tsx
@@ -27,7 +27,7 @@ export function Layout({ children, active, onNav, systemLine, title, demoMode }:
           <div className='flex flex-wrap gap-2 text-xs font-semibold'>
             <span className={`rounded-full border px-3 py-1 ${demoMode ? 'border-amber-300 bg-amber-50 text-amber-700' : 'border-emerald-300 bg-emerald-50 text-emerald-700'}`}>{demoMode ? 'DEMO' : 'LIVE'}</span>
             <span className='rounded-full border border-blue-200 bg-blue-50 px-3 py-1 text-blue-700'>READ-ONLY</span>
-            <span className='rounded-full border border-slate-200 bg-slate-50 px-3 py-1 text-slate-700'>v0.4.0-alpha</span>
+            <span className='rounded-full border border-slate-200 bg-slate-50 px-3 py-1 text-slate-700'>v0.4.1-alpha</span>
           </div>
         </header>
         <main className='space-y-4'>{children}</main>
diff --git a/frontend/src/components/ReportView.tsx b/frontend/src/components/ReportView.tsx
index 4bb2bfe..8ed32cf 100644
--- a/frontend/src/components/ReportView.tsx
+++ b/frontend/src/components/ReportView.tsx
@@ -7,6 +7,19 @@ import { StatusBadge } from './StatusBadge'
 const order = { CRITICAL: 0, WARNING: 1, UNKNOWN: 2, OK: 3 }
 const decisionByStatus: Record<string, string> = { OK: 'GO', WARNING: 'CAUTION', CRITICAL: 'NO-GO', UNKNOWN: 'UNKNOWN' }
 
+const formatDurationSeconds = (seconds: number): string => {
+  if (seconds < 60) return `${seconds}s`
+  if (seconds < 3600) return `${Math.floor(seconds / 60)}m`
+  return `${Math.floor(seconds / 3600)}h`
+}
+
+const freshnessClass = (freshness?: string): string => {
+  if (freshness === 'LIVE' || freshness === 'FRESH') return 'text-emerald-700'
+  if (freshness === 'EXPIRING_SOON') return 'text-amber-700'
+  if (freshness === 'STALE') return 'text-red-700'
+  return 'text-slate-500'
+}
+
 export function ReportView({ report }: { report: CheckResponse }) {
   const [copyMessage, setCopyMessage] = useState<string>('')
   const details = report.details ?? {}
@@ -76,7 +89,7 @@ export function ReportView({ report }: { report: CheckResponse }) {
     </section>
 
 
-    {sourceDiagnostics.length > 0 && <section className='rf-card p-4 space-y-2'><h4 className='font-semibold'>Data Source Diagnostics</h4><div className='overflow-x-auto'><table className='w-full text-sm'><thead><tr className='border-b text-left'><th className='py-2'>Source</th><th>Endpoint</th><th>Status</th><th>Duration</th><th>Cache</th><th>Message</th></tr></thead><tbody>{sourceDiagnostics.map((d, idx) => <tr key={`${d.name}-${idx}`} className='border-b border-slate-100'><td>{d.name || '-'}</td><td className='font-mono'>{d.endpoint || '-'}</td><td><StatusBadge status={d.status || 'UNKNOWN'} /></td><td>{typeof d.duration_ms === 'number' ? `${d.duration_ms} ms` : '-'}</td><td>{d.cached === true ? 'HIT' : d.cached === false ? 'MISS' : '-'}</td><td>{d.message || '-'}</td></tr>)}</tbody></table></div></section>}
+    {sourceDiagnostics.length > 0 && <section className='rf-card p-4 space-y-2'><h4 className='font-semibold'>Data Source Diagnostics</h4><div className='overflow-x-auto'><table className='w-full text-sm'><thead><tr className='border-b text-left'><th className='py-2'>Source</th><th>Endpoint</th><th>Status</th><th>Freshness</th><th>Duration</th><th>Cache</th><th>Age</th><th>TTL</th><th>Message</th></tr></thead><tbody>{sourceDiagnostics.map((d, idx) => <tr key={`${d.name}-${idx}`} className='border-b border-slate-100'><td>{d.name || '-'}</td><td className='font-mono'>{d.endpoint || '-'}</td><td><StatusBadge status={d.status || 'UNKNOWN'} /></td><td className={freshnessClass(d.freshness)}>{d.freshness || 'UNKNOWN'}</td><td>{typeof d.duration_ms === 'number' ? `${d.duration_ms} ms` : '-'}</td><td>{d.cached === true ? 'HIT' : d.cached === false ? 'MISS' : '-'}</td><td>{typeof d.cache_age_seconds === 'number' ? formatDurationSeconds(d.cache_age_seconds) : 'Unknown'}</td><td>{typeof d.cache_ttl_seconds === 'number' ? formatDurationSeconds(d.cache_ttl_seconds) : 'Unknown'}</td><td>{d.message || '-'}</td></tr>)}</tbody></table></div></section>}
 
     <details className='rf-card p-4'><summary className='cursor-pointer text-sm font-semibold'>Technische Details</summary><pre className='mt-3 overflow-auto rounded-xl bg-slate-50 p-3 text-xs'>{JSON.stringify({ input: report.input, holder: details.resource_holder, warnings: details.warnings, source_errors: details.source_errors }, null, 2)}</pre></details>
     {sortedResults.length > 0 && <section className='rf-card p-4'><h4 className='mb-2 font-semibold'>Batch Results</h4><div className='overflow-x-auto'><table className='w-full text-sm'><thead><tr className='border-b text-left'><th className='py-2'>Status</th><th>Prefix</th><th>Summary</th></tr></thead><tbody>{sortedResults.map((item, idx) => <tr key={`${item.prefix}-${idx}`} className='border-b border-slate-100'><td className='py-2'><StatusBadge status={item.status || 'UNKNOWN'} /></td><td className='font-mono'>{item.prefix}</td><td>{item.summary || '-'}</td></tr>)}</tbody></table></div></section>}
diff --git a/frontend/src/types.ts b/frontend/src/types.ts
index 936cc9a..8656311 100644
--- a/frontend/src/types.ts
+++ b/frontend/src/types.ts
@@ -27,6 +27,10 @@ export type SourceDiagnostic = {
   duration_ms?: number | null
   cached?: boolean | null
   cache_age_seconds?: number | null
+  cache_ttl_seconds?: number | null
+  fetched_at?: string | null
+  expires_at?: string | null
+  freshness?: "LIVE" | "FRESH" | "EXPIRING_SOON" | "STALE" | "UNKNOWN" | string
   http_status?: number | null
   error_type?: string | null
   details?: Record<string, unknown>