graph-dependency-analyzer 0.2.0__py3-none-any.whl

src/infrastructure/persistence/repository_relationship_repository.py

@@ -0,0 +1,1312 @@
+"""
+Repository Relationship Discovery — 4-pass cross-repo dependency analysis.
+
+Pass 1: Explicit relationships (HIGH confidence) — CALLS_BACKEND, USES_LIBRARY, DEPENDS_ON
+Pass 2: Inferred by path matching (MEDIUM confidence) — unmatched API ↔ ENDPOINT paths
+Pass 3: Inferred by semantic name similarity (LOW/MEDIUM) — UserService ↔ UserController
+Pass 4: Shared database/event inference (MEDIUM) — same table name or event name across repos
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Any
+
+import structlog
+
+logger = structlog.get_logger(__name__)
+
+# ---------------------------------------------------------------------------
+# Semantic synonym groups: names in the same group are treated as equivalent
+# ---------------------------------------------------------------------------
+_SYNONYM_GROUPS: list[set[str]] = [
+    {"user", "account", "member", "profile", "customer", "client"},
+    {"order", "purchase", "transaction", "checkout", "cart"},
+    {"product", "item", "sku", "good", "catalog"},
+    {"shipment", "delivery", "shipping", "dispatch", "fulfillment"},
+    {"inventory", "stock", "warehouse", "storage"},
+    {"payment", "billing", "invoice", "charge", "fee"},
+    {"notification", "alert", "message", "email", "sms"},
+    {"report", "analytics", "metric", "stat", "dashboard"},
+    {"auth", "authentication", "authorization", "permission", "role", "access"},
+    {"event", "topic", "message", "queue", "stream"},
+]
+
+# Build reverse map: word -> canonical synonym set index
+_WORD_TO_GROUP: dict[str, int] = {}
+for _i, _group in enumerate(_SYNONYM_GROUPS):
+    for _w in _group:
+        _WORD_TO_GROUP[_w] = _i
+
+# Common class-name suffixes that suggest same service
+_SERVICE_SUFFIXES = [
+    "Service", "Controller", "ApplicationService", "Facade",
+    "Api", "Client", "Repository", "Gateway", "Adapter",
+    "Handler", "Listener", "Consumer", "Producer",
+]
+
+
+# ---------------------------------------------------------------------------
+# Data classes
+# ---------------------------------------------------------------------------
+
+@dataclass
+class RepositoryRelationship:
+    from_repo: str
+    to_repo: str
+    relation_type: str          # CALLS_BACKEND | USES_LIBRARY | POSSIBLE_MATCH | SHARED_DB | SHARED_EVENT
+    confidence: str             # HIGH | MEDIUM | LOW
+    evidence: list[str]
+    details: list[dict[str, Any]] = field(default_factory=list)
+
+
+@dataclass
+class RepositoryRelationshipGraph:
+    repositories: list[str]
+    relationships: list[dict[str, Any]]
+    meta: dict[str, Any] = field(default_factory=dict)
+    external_services: list[dict[str, Any]] = field(default_factory=list)
+
+
+# ---------------------------------------------------------------------------
+# Repository
+# ---------------------------------------------------------------------------
+
+class RepositoryRelationshipRepository:
+    """Discovers relationships between indexed repositories using 4-pass strategy."""
+
+    def __init__(self, driver) -> None:
+        self.driver = driver
+
+    async def discover_all(self) -> RepositoryRelationshipGraph:
+        """Run all 5 passes and return the merged relationship graph."""
+        async with self.driver.session() as session:
+            repos = await self._fetch_repositories(session)
+            p1 = await self._pass1_explicit(session)
+            p2 = await self._pass2_path_matching(session, p1)
+            p3 = await self._pass3_semantic_names(session, repos)
+            p4 = await self._pass4_shared_artifacts(session)
+            p5, ext_services = await self._pass5_external_services(session)
+
+        relationships = p1 + p2 + p3 + p4 + p5
+
+        # Deduplicate: keep highest confidence for same (from, to, type) triple
+        deduped = _dedup_relationships(relationships)
+
+        meta = {
+            "total_repos": len(repos),
+            "explicit": len(p1),
+            "path_inferred": len(p2),
+            "semantic_inferred": len(p3),
+            "shared_artifact": len(p4),
+            "external_services": len(p5),
+            "total_after_dedup": len(deduped),
+            "ext_service_nodes": ext_services,
+        }
+
+        logger.info("repository_relationships_discovered", **meta)
+
+        return RepositoryRelationshipGraph(
+            repositories=repos,
+            relationships=[_rel_to_dict(r) for r in deduped],
+            meta=meta,
+            external_services=meta.pop("ext_service_nodes", []),
+        )
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    async def _fetch_repositories(self, session) -> list[str]:
+        result = await session.run(
+            "MATCH (n) WHERE n.repository IS NOT NULL "
+            "AND n.repository <> 'external' AND n.repository <> 'unknown' "
+            "RETURN DISTINCT n.repository AS repo ORDER BY repo"
+        )
+        rows = await result.data()
+        return [r["repo"] for r in rows if r["repo"]]
+
+    # ------------------------------------------------------------------
+    # Pass 1 — Explicit relationships (HIGH)
+    # ------------------------------------------------------------------
+
+    async def _pass1_explicit(self, session) -> list[RepositoryRelationship]:
+        results: list[RepositoryRelationship] = []
+        results.extend(await self._explicit_calls_backend(session))
+        results.extend(await self._explicit_shared_library(session))
+        results.extend(await self._explicit_depends_on(session))
+        results.extend(await self._explicit_calls_api(session))
+        return results
+
+    async def _explicit_calls_backend(self, session) -> list[RepositoryRelationship]:
+        query = """
+        MATCH (src)-[r:CALLS_BACKEND]->(ep)
+        WHERE src.repository IS NOT NULL AND ep.repository IS NOT NULL
+          AND src.repository <> ep.repository
+        RETURN DISTINCT
+            src.repository      AS from_repo,
+            ep.repository       AS to_repo,
+            r.frontend_path     AS frontend_path,
+            ep.url              AS backend_path,
+            ep.http_method      AS http_method,
+            src.file_path       AS src_file
+        LIMIT 500
+        """
+        rows = (await (await session.run(query)).data())
+        grouped: dict[tuple, list[dict]] = {}
+        for r in rows:
+            key = (r["from_repo"], r["to_repo"])
+            grouped.setdefault(key, []).append(r)
+
+        out = []
+        for (from_repo, to_repo), items in grouped.items():
+            evidence = [
+                f"CALLS_BACKEND: {i.get('http_method','?')} {i.get('frontend_path','')} → {i.get('backend_path','')}"
+                for i in items[:5]
+            ]
+            out.append(RepositoryRelationship(
+                from_repo=from_repo,
+                to_repo=to_repo,
+                relation_type="CALLS_BACKEND",
+                confidence="HIGH",
+                evidence=evidence,
+                details=items[:20],
+            ))
+        return out
+
+    async def _explicit_shared_library(self, session) -> list[RepositoryRelationship]:
+        """Repos that share the same external library may be in the same domain."""
+        query = """
+        MATCH (a)-[:USES_LIBRARY]->(lib:LIBRARY)<-[:USES_LIBRARY]-(b)
+        WHERE a.repository IS NOT NULL AND b.repository IS NOT NULL
+          AND a.repository < b.repository
+        RETURN DISTINCT
+            a.repository AS from_repo,
+            b.repository AS to_repo,
+            lib.artifact_id AS library,
+            lib.group_id    AS group_id
+        LIMIT 300
+        """
+        rows = await (await session.run(query)).data()
+        grouped: dict[tuple, list[str]] = {}
+        for r in rows:
+            key = (r["from_repo"], r["to_repo"])
+            lib = f"{r.get('group_id','')}:{r.get('library','')}"
+            grouped.setdefault(key, []).append(lib)
+
+        return [
+            RepositoryRelationship(
+                from_repo=k[0],
+                to_repo=k[1],
+                relation_type="USES_LIBRARY",
+                confidence="HIGH",
+                evidence=[f"Shared library: {lib}" for lib in libs[:5]],
+                details=[{"library": lib} for lib in libs],
+            )
+            for k, libs in grouped.items()
+        ]
+
+    async def _explicit_depends_on(self, session) -> list[RepositoryRelationship]:
+        query = """
+        MATCH (a:REPOSITORY)-[:DEPENDS_ON]->(b:REPOSITORY)
+        WHERE a.name IS NOT NULL AND b.name IS NOT NULL AND a.name <> b.name
+        RETURN DISTINCT a.name AS from_repo, b.name AS to_repo
+        LIMIT 200
+        """
+        rows = await (await session.run(query)).data()
+        return [
+            RepositoryRelationship(
+                from_repo=r["from_repo"],
+                to_repo=r["to_repo"],
+                relation_type="DEPENDS_ON",
+                confidence="HIGH",
+                evidence=["Direct DEPENDS_ON edge in graph"],
+            )
+            for r in rows
+        ]
+
+    async def _explicit_calls_api(self, session) -> list[RepositoryRelationship]:
+        """Frontend CALLS_API where the API url is explicitly attributed to a backend repo."""
+        query = """
+        MATCH (src)-[:CALLS_API]->(api:API)
+        WHERE src.repository IS NOT NULL AND api.repository IS NOT NULL
+          AND src.repository <> api.repository
+        RETURN DISTINCT
+            src.repository  AS from_repo,
+            api.repository  AS to_repo,
+            api.url         AS url
+        LIMIT 300
+        """
+        rows = await (await session.run(query)).data()
+        grouped: dict[tuple, list[str]] = {}
+        for r in rows:
+            key = (r["from_repo"], r["to_repo"])
+            grouped.setdefault(key, []).append(r.get("url", ""))
+
+        return [
+            RepositoryRelationship(
+                from_repo=k[0],
+                to_repo=k[1],
+                relation_type="CALLS_API",
+                confidence="HIGH",
+                evidence=[f"CALLS_API: {u}" for u in urls[:5]],
+                details=[{"url": u} for u in urls],
+            )
+            for k, urls in grouped.items()
+        ]
+
+    # ------------------------------------------------------------------
+    # Pass 2 — Path matching inference (MEDIUM)
+    # ------------------------------------------------------------------
+
+    async def _pass2_path_matching(
+        self,
+        session,
+        existing: list[RepositoryRelationship],
+    ) -> list[RepositoryRelationship]:
+        """
+        Match unlinked API nodes (frontend calls) to ENDPOINT nodes (backend) by
+        normalised path suffix. Skip pairs already covered by Pass 1.
+        """
+        already_linked = {(r.from_repo, r.to_repo) for r in existing if r.relation_type == "CALLS_BACKEND"}
+
+        # Fetch unmatched API nodes (no CALLS_BACKEND yet)
+        api_result = await session.run(
+            "MATCH (n:API) WHERE n.repository IS NOT NULL "
+            "AND NOT (n)-[:CALLS_BACKEND]->() "
+            "RETURN n.url AS url, n.repository AS repo, n.id AS id"
+        )
+        api_rows = await api_result.data()
+
+        ep_result = await session.run(
+            "MATCH (n:ENDPOINT) WHERE n.repository IS NOT NULL "
+            "RETURN n.url AS url, n.repository AS repo, n.http_method AS method, n.id AS id"
+        )
+        ep_rows = await ep_result.data()
+
+        if not api_rows or not ep_rows:
+            return []
+
+        # Build normalised index for endpoints
+        ep_index: list[tuple[str, dict]] = [
+            (_normalise_path(ep["url"] or ""), ep) for ep in ep_rows if ep.get("url")
+        ]
+
+        out: list[RepositoryRelationship] = []
+        grouped: dict[tuple, list[dict]] = {}
+
+        for api in api_rows:
+            api_norm = _normalise_path(api["url"] or "")
+            if not api_norm:
+                continue
+            for ep_norm, ep in ep_index:
+                if not ep_norm:
+                    continue
+                from_repo = api["repo"]
+                to_repo = ep["repo"]
+                if from_repo == to_repo:
+                    continue
+                if (from_repo, to_repo) in already_linked:
+                    continue
+
+                if api_norm == ep_norm or ep_norm.endswith("/" + api_norm) or api_norm.endswith("/" + ep_norm):
+                    key = (from_repo, to_repo)
+                    grouped.setdefault(key, []).append({
+                        "frontend_path": api["url"],
+                        "backend_path": ep["url"],
+                        "method": ep.get("method", "?"),
+                    })
+
+        for (from_repo, to_repo), matches in grouped.items():
+            evidence = [
+                f"Path match: {m['method']} {m['frontend_path']} ~ {m['backend_path']}"
+                for m in matches[:5]
+            ]
+            out.append(RepositoryRelationship(
+                from_repo=from_repo,
+                to_repo=to_repo,
+                relation_type="POSSIBLE_MATCH",
+                confidence="MEDIUM",
+                evidence=evidence,
+                details=matches[:20],
+            ))
+
+        return out
+
+    # ------------------------------------------------------------------
+    # Pass 3 — Semantic name matching (LOW/MEDIUM)
+    # ------------------------------------------------------------------
+
+    async def _pass3_semantic_names(
+        self,
+        session,
+        repos: list[str],
+    ) -> list[RepositoryRelationship]:
+        """
+        Compare class/service names across repositories using synonym groups and
+        suffix stripping. Returns LOW confidence unless multiple signals agree.
+        """
+        if len(repos) < 2:
+            return []
+
+        # Fetch all classes / components grouped by repo
+        result = await session.run(
+            "MATCH (n) WHERE n.repository IS NOT NULL AND n.name IS NOT NULL "
+            "AND (n:CLASS OR n:Component OR n:METHOD) "
+            "RETURN n.repository AS repo, n.name AS name, labels(n)[0] AS label "
+            "LIMIT 5000"
+        )
+        rows = await result.data()
+
+        # Build repo → set of normalised base names
+        repo_names: dict[str, set[str]] = {}
+        for r in rows:
+            base = _strip_suffix(r["name"] or "")
+            norm = _normalise_name(base)
+            if norm and len(norm) > 3:
+                repo_names.setdefault(r["repo"], set()).add(norm)
+
+        out: list[RepositoryRelationship] = []
+        repo_list = list(repo_names.keys())
+
+        for i, repo_a in enumerate(repo_list):
+            for repo_b in repo_list[i + 1:]:
+                shared = _find_semantic_matches(repo_names[repo_a], repo_names[repo_b])
+                if not shared:
+                    continue
+                confidence = "MEDIUM" if len(shared) >= 3 else "LOW"
+                evidence = [f"Shared concept: '{s}'" for s in list(shared)[:5]]
+                out.append(RepositoryRelationship(
+                    from_repo=repo_a,
+                    to_repo=repo_b,
+                    relation_type="POSSIBLE_MATCH",
+                    confidence=confidence,
+                    evidence=evidence,
+                    details=[{"shared_concept": s} for s in shared],
+                ))
+
+        return out
+
+    # ------------------------------------------------------------------
+    # Pass 4 — Shared database tables / events (MEDIUM)
+    # ------------------------------------------------------------------
+
+    async def _pass4_shared_artifacts(self, session) -> list[RepositoryRelationship]:
+        """
+        Detect repos that reference the same database table names or event/topic names.
+        Table names come from SQL string literals; events from class names ending in Event/Message.
+        """
+        # Tables: string literals matching SQL patterns stored in metadata
+        table_result = await session.run(
+            "MATCH (n) WHERE n.repository IS NOT NULL AND n.db_table IS NOT NULL "
+            "RETURN n.repository AS repo, n.db_table AS table_name "
+            "UNION "
+            "MATCH (n:DATABASE) WHERE n.repository IS NOT NULL AND n.database IS NOT NULL "
+            "RETURN n.repository AS repo, n.database AS table_name "
+            "LIMIT 1000"
+        )
+        table_rows = await table_result.data()
+
+        # Events / topics: nodes or string literals that look like events
+        event_result = await session.run(
+            "MATCH (n) WHERE n.repository IS NOT NULL AND n.name IS NOT NULL "
+            "AND (n.name ENDS WITH 'Event' OR n.name ENDS WITH 'Message' "
+            "  OR n.name ENDS WITH 'Topic' OR n.name ENDS WITH 'Command') "
+            "RETURN n.repository AS repo, n.name AS event_name "
+            "LIMIT 1000"
+        )
+        event_rows = await event_result.data()
+
+        out = []
+        out.extend(_group_shared_artifact(table_rows, "table_name", "SHARED_DB", "Shared DB table"))
+        out.extend(_group_shared_artifact(event_rows, "event_name", "SHARED_EVENT", "Shared event/topic"))
+        return out
+
+
+    # ------------------------------------------------------------------
+    # Pass 5a — DB schema cross-repo linking (HIGH confidence)
+    # ------------------------------------------------------------------
+
+    async def _pass5a_db_schema_links(
+        self, session
+    ) -> list[RepositoryRelationship]:
+        """
+        Link application repos to database schema repos by matching table/collection names.
+
+        Strategy:
+        1. Find all DB_TABLE / DB_COLLECTION nodes and which repo defined them (schema repos)
+        2. Find all string literals and READS_TABLE/WRITES_TABLE refs from application repos
+        3. When an app repo references a table name owned by a schema repo → HIGH confidence link
+        4. Also match JPA @Table names and SQL query embedded in .properties files
+        """
+        out: list[RepositoryRelationship] = []
+
+        # Step 1: all DB schema objects with their owning repo
+        tbl_result = await session.run(
+            """
+            MATCH (n)
+            WHERE n.repository IS NOT NULL
+              AND n.repository <> 'unknown' AND n.repository <> 'external'
+              AND labels(n)[0] IN ['DB_TABLE','DB_VIEW','DB_COLLECTION','DB_PROCEDURE','DB_PACKAGE']
+            RETURN DISTINCT
+                n.repository AS schema_repo,
+                n.name       AS obj_name,
+                coalesce(n.qualified_name, n.name) AS qname,
+                labels(n)[0] AS obj_type
+            LIMIT 5000
+            """
+        )
+        tbl_rows = await tbl_result.data()
+
+        if not tbl_rows:
+            return []
+
+        # Build index: normalised_name -> {schema_repo, qname, obj_type}
+        schema_index: dict[str, dict] = {}
+        for row in tbl_rows:
+            norm = (row.get("obj_name") or "").upper().strip()
+            qnorm = (row.get("qname") or "").upper().strip()
+            entry = {
+                "schema_repo": row["schema_repo"],
+                "qname": row["qname"],
+                "obj_type": row["obj_type"],
+            }
+            for key in [norm, qnorm]:
+                if key and key not in schema_index:
+                    schema_index[key] = entry
+
+        # Step 2: Find all READS_TABLE/WRITES_TABLE edges from app repos
+        ref_result = await session.run(
+            """
+            MATCH (src)-[r:READS_TABLE|WRITES_TABLE|CALLS_PROCEDURE]->(tgt)
+            WHERE src.repository IS NOT NULL
+              AND src.repository <> 'unknown'
+            RETURN DISTINCT
+                src.repository AS app_repo,
+                tgt.id         AS target_id,
+                type(r)        AS ref_type
+            LIMIT 5000
+            """
+        )
+        ref_rows = await ref_result.data()
+
+        # Also gather CLASS nodes that have table names via JPA
+        jpa_result = await session.run(
+            """
+            MATCH (n:DB_TABLE)
+            WHERE n.repository IS NOT NULL AND n.repository <> 'unknown'
+            RETURN DISTINCT n.repository AS app_repo, n.name AS tbl_name
+            LIMIT 2000
+            """
+        )
+        jpa_rows = await jpa_result.data()
+
+        # Step 3: match refs to schema objects
+        grouped: dict[tuple, list[str]] = {}
+
+        def add_match(app_repo: str, schema_repo: str, evidence: str):
+            if app_repo == schema_repo:
+                return
+            key = (app_repo, schema_repo)
+            grouped.setdefault(key, []).append(evidence)
+
+        for row in ref_rows:
+            target = (row.get("target_id") or "").upper().strip()
+            app_repo = row.get("app_repo", "")
+            if not target or not app_repo:
+                continue
+            entry = schema_index.get(target)
+            if not entry:
+                # try last part after dot
+                short = target.split(".")[-1]
+                entry = schema_index.get(short)
+            if entry:
+                add_match(
+                    app_repo, entry["schema_repo"],
+                    f"{row['ref_type']}: {target} ({entry['obj_type']})"
+                )
+
+        # JPA @Table cross-repo
+        for row in jpa_rows:
+            tbl = (row.get("tbl_name") or "").upper().strip()
+            app_repo = row.get("app_repo", "")
+            entry = schema_index.get(tbl)
+            if entry and entry["schema_repo"] != app_repo:
+                add_match(app_repo, entry["schema_repo"],
+                          f"JPA @Table: {tbl}")
+
+        for (app_repo, schema_repo), evidences in grouped.items():
+            conf = "HIGH" if len(evidences) >= 3 else "MEDIUM"
+            out.append(RepositoryRelationship(
+                from_repo=app_repo,
+                to_repo=schema_repo,
+                relation_type="USES_DB_SCHEMA",
+                confidence=conf,
+                evidence=list(dict.fromkeys(evidences))[:6],
+                details=[{"table": e} for e in evidences[:10]],
+            ))
+
+        return out
+
+    # ------------------------------------------------------------------
+    # Pass 5 — External service detection (HIGH/MEDIUM confidence)
+    # ------------------------------------------------------------------
+
+    async def _pass5_external_services(
+        self, session
+    ) -> tuple[list[RepositoryRelationship], list[dict]]:
+        """
+        Detect connections between repositories and external services:
+        - AI providers (Claude/Anthropic, OpenAI, Azure OpenAI, Gemini)
+        - Azure services (Cosmos DB, Synapse, Service Bus, Blob, SQL, Event Hub)
+        - Databases (PostgreSQL, MySQL, Oracle, MongoDB, Redis, Cassandra)
+        - Analytics (Databricks, BigQuery, Snowflake, Redshift)
+        - Messaging (Kafka, RabbitMQ, SQS)
+        - Observability (Datadog, New Relic, Elastic)
+        - Other SaaS (Stripe, Twilio, SendGrid, Auth0, Okta)
+
+        Detection sources (in priority):
+        1. Maven/Gradle LIBRARY nodes — artifact_id / group_id patterns
+        2. NPM_PACKAGE nodes — package name patterns
+        3. DATABASE nodes — JDBC URL / connection string patterns
+        4. API nodes — URL hostname patterns
+        5. String literals — SDK initialisation patterns in code
+        """
+        relationships: list[RepositoryRelationship] = []
+        ext_nodes: list[dict] = []
+
+        # ── Pass 5a: DB schema cross-repo linking ──────────────────────────
+        # Match app repos that reference table/collection names that belong to
+        # a dedicated schema repo (wms-oracle, etc.)
+        db_rels = await self._pass5a_db_schema_links(session)
+        relationships.extend(db_rels)
+
+        # Fetch all libraries with their owning repo
+        lib_result = await session.run(
+            "MATCH (n)-[:USES_LIBRARY]->(lib:LIBRARY) "
+            "WHERE n.repository IS NOT NULL "
+            "RETURN DISTINCT n.repository AS repo, lib.group_id AS group_id, "
+            "lib.artifact_id AS artifact_id "
+            "LIMIT 2000"
+        )
+        lib_rows = await lib_result.data()
+
+        npm_result = await session.run(
+            "MATCH (n)-[:USES_PACKAGE]->(pkg:NPM_PACKAGE) "
+            "WHERE n.repository IS NOT NULL "
+            "RETURN DISTINCT n.repository AS repo, pkg.name AS pkg_name "
+            "LIMIT 2000"
+        )
+        npm_rows = await npm_result.data()
+
+        # DATABASE nodes — find which repos connect to each DB node via any edge,
+        # or via the repository property if it was correctly populated.
+        # Exclude 'unknown' which is a placeholder from pre-fix indexing runs.
+        db_result = await session.run(
+            """
+            MATCH (owner)-[]->(n:DATABASE)
+            WHERE owner.repository IS NOT NULL
+              AND owner.repository <> 'unknown'
+              AND owner.repository <> 'external'
+            RETURN DISTINCT owner.repository AS repo, n.url AS url,
+                   n.host AS host, n.db_type AS db_type, n.database AS database
+            UNION
+            MATCH (n:DATABASE)
+            WHERE n.repository IS NOT NULL
+              AND n.repository <> 'unknown'
+              AND n.repository <> 'external'
+            RETURN DISTINCT n.repository AS repo, n.url AS url,
+                   n.host AS host, n.db_type AS db_type, n.database AS database
+            LIMIT 500
+            """
+        )
+        db_rows = await db_result.data()
+
+        api_result = await session.run(
+            """
+            MATCH (n:API)
+            WHERE n.repository IS NOT NULL
+            RETURN DISTINCT n.repository AS repo, n.url AS url
+            UNION
+            MATCH (owner)-[]->(n:API)
+            WHERE owner.repository IS NOT NULL AND n.repository IS NULL
+            RETURN DISTINCT owner.repository AS repo, n.url AS url
+            LIMIT 2000
+            """
+        )
+        api_rows = await api_result.data()
+
+        # Infer services from Java package names (e.g. config.entra → Azure AD)
+        pkg_result = await session.run(
+            """
+            MATCH (n:CLASS)
+            WHERE n.repository IS NOT NULL AND n.qualified_name IS NOT NULL
+            RETURN DISTINCT n.repository AS repo, n.qualified_name AS qname
+            LIMIT 5000
+            """
+        )
+        pkg_rows = await pkg_result.data()
+
+        str_rows: list[dict] = []  # string_literals not stored as node property
+
+        # Collect all signal per repo
+        repo_signals: dict[str, list[tuple[str, str, str]]] = {}
+        # Each entry: (service_id, service_label, evidence_str)
+
+        def add_signal(repo: str, svc_id: str, svc_label: str, evidence: str) -> None:
+            repo_signals.setdefault(repo, []).append((svc_id, svc_label, evidence))
+
+        # ── Maven/Gradle libraries ──────────────────────────────────────────
+        for row in lib_rows:
+            repo = row.get("repo") or ""
+            gid  = (row.get("group_id") or "").lower()
+            aid  = (row.get("artifact_id") or "").lower()
+            combined = f"{gid}:{aid}"
+
+            svc = _classify_library(gid, aid)
+            if svc:
+                add_signal(repo, svc["id"], svc["label"],
+                           f"Maven/Gradle lib: {combined}")
+
+        # ── NPM packages ────────────────────────────────────────────────────
+        for row in npm_rows:
+            repo = row.get("repo") or ""
+            pkg  = (row.get("pkg_name") or "").lower()
+            svc  = _classify_npm_package(pkg)
+            if svc:
+                add_signal(repo, svc["id"], svc["label"],
+                           f"NPM package: {pkg}")
+
+        # ── Database nodes ──────────────────────────────────────────────────
+        for row in db_rows:
+            repo    = row.get("repo") or ""
+            url     = (row.get("url") or "").lower()
+            host    = (row.get("host") or "").lower()
+            db_type = (row.get("db_type") or "").lower()
+            svc = _classify_db_url(url, host, db_type)
+            if svc:
+                add_signal(repo, svc["id"], svc["label"],
+                           f"DB connection: {host or url[:60]}")
+
+        # ── API URL nodes ───────────────────────────────────────────────────
+        for row in api_rows:
+            repo = row.get("repo") or ""
+            url  = (row.get("url") or "").lower()
+            svc  = _classify_api_url(url)
+            if svc:
+                add_signal(repo, svc["id"], svc["label"],
+                           f"API call: {url[:80]}")
+
+        # ── String literals (not stored; skipped) ──────────────────────────
+        _ = str_rows
+
+        # ── Java package / qualified-name inference ─────────────────────────
+        # e.g. "config.entra" → Azure AD, "repositories" → database, "kafka" → Kafka
+        _PKG_RULES: list[tuple[str, dict]] = [
+            # AI
+            ("anthropic",     {"id": "anthropic-claude", "label": "Anthropic Claude"}),
+            ("openai",        {"id": "openai",           "label": "OpenAI"}),
+            ("gemini",        {"id": "google-gemini",    "label": "Google Gemini"}),
+            ("vertexai",      {"id": "google-vertex-ai", "label": "Google Vertex AI"}),
+            # Azure (specific first)
+            ("entra",         {"id": "azure-ad",         "label": "Azure AD (Entra)"}),
+            ("keyvault",      {"id": "azure-keyvault",   "label": "Azure Key Vault"}),
+            ("cosmos",        {"id": "azure-cosmos-db",  "label": "Azure Cosmos DB"}),
+            ("servicebus",    {"id": "azure-service-bus","label": "Azure Service Bus"}),
+            ("eventhub",      {"id": "azure-event-hubs", "label": "Azure Event Hubs"}),
+            ("blobstorage",   {"id": "azure-blob",       "label": "Azure Blob Storage"}),
+            ("synapse",       {"id": "azure-synapse",    "label": "Azure Synapse"}),
+            ("azure",         {"id": "azure",            "label": "Azure SDK"}),
+            # AWS
+            ("dynamodb",      {"id": "aws-dynamodb",     "label": "AWS DynamoDB"}),
+            ("awss3",         {"id": "aws-s3",           "label": "AWS S3"}),
+            ("awslambda",     {"id": "aws-lambda",       "label": "AWS Lambda"}),
+            ("cloudwatch",    {"id": "aws-cloudwatch",   "label": "AWS CloudWatch"}),
+            ("secretsmanager",{"id": "aws-secrets",      "label": "AWS Secrets Manager"}),
+            # Google Cloud
+            ("pubsub",        {"id": "google-pubsub",    "label": "Google Pub/Sub"}),
+            ("firestore",     {"id": "firestore",        "label": "Google Firestore"}),
+            ("bigquery",      {"id": "bigquery",         "label": "BigQuery"}),
+            # Databases
+            ("postgres",      {"id": "postgresql",       "label": "PostgreSQL"}),
+            ("mysql",         {"id": "mysql",            "label": "MySQL"}),
+            ("mariadb",       {"id": "mariadb",          "label": "MariaDB"}),
+            ("oracle",        {"id": "oracle-db",        "label": "Oracle DB"}),
+            ("db2",           {"id": "ibm-db2",          "label": "IBM DB2"}),
+            ("hana",          {"id": "sap-hana",         "label": "SAP HANA"}),
+            ("mongo",         {"id": "mongodb",          "label": "MongoDB"}),
+            ("redis",         {"id": "redis",            "label": "Redis"}),
+            ("cassandra",     {"id": "cassandra",        "label": "Cassandra"}),
+            ("couchbase",     {"id": "couchbase",        "label": "Couchbase"}),
+            # Messaging
+            ("kafka",         {"id": "kafka",            "label": "Apache Kafka"}),
+            ("rabbitmq",      {"id": "rabbitmq",         "label": "RabbitMQ"}),
+            ("activemq",      {"id": "activemq",         "label": "Apache ActiveMQ"}),
+            ("ibmmq",         {"id": "ibm-mq",           "label": "IBM MQ"}),
+            # Observability
+            ("elasticsearch", {"id": "elasticsearch",    "label": "Elasticsearch"}),
+            ("datadog",       {"id": "datadog",          "label": "Datadog"}),
+            ("newrelic",      {"id": "newrelic",         "label": "New Relic"}),
+            ("prometheus",    {"id": "prometheus",       "label": "Prometheus"}),
+            ("splunk",        {"id": "splunk",           "label": "Splunk"}),
+            ("grafana",       {"id": "grafana",          "label": "Grafana"}),
+            # Secrets
+            ("hashicorp",     {"id": "hashicorp-vault",  "label": "HashiCorp Vault"}),
+            # Auth
+            ("okta",          {"id": "okta",             "label": "Okta"}),
+            ("auth0",         {"id": "auth0",            "label": "Auth0"}),
+            # Analytics
+            ("databricks",    {"id": "databricks",       "label": "Databricks"}),
+            ("snowflake",     {"id": "snowflake",        "label": "Snowflake"}),
+            # SaaS
+            ("stripe",        {"id": "stripe",           "label": "Stripe"}),
+            ("twilio",        {"id": "twilio",           "label": "Twilio"}),
+            ("sendgrid",      {"id": "sendgrid",         "label": "SendGrid"}),
+            ("salesforce",    {"id": "salesforce",       "label": "Salesforce"}),
+            ("servicenow",    {"id": "servicenow",       "label": "ServiceNow"}),
+            # IBM
+            ("websphere",     {"id": "ibm",              "label": "IBM WebSphere"}),
+        ]
+        for row in pkg_rows:
+            repo  = row.get("repo") or ""
+            qname = (row.get("qname") or "").lower()
+            for keyword, svc in _PKG_RULES:
+                if keyword in qname:
+                    add_signal(repo, svc["id"], svc["label"],
+                               f"Java package: {row.get('qname','')[:80]}")
+                    break  # one match per class is enough
+
+        # ── Build relationships & ext_nodes ─────────────────────────────────
+        seen_ext: dict[str, dict] = {}
+        for repo, signals in repo_signals.items():
+            # Deduplicate services for this repo
+            seen_for_repo: dict[str, list[str]] = {}
+            for svc_id, svc_label, evidence in signals:
+                seen_for_repo.setdefault(svc_id, []).append(evidence)
+                if svc_id not in seen_ext:
+                    cat = _service_category(svc_id)
+                    seen_ext[svc_id] = {
+                        "id":       svc_id,
+                        "label":    svc_label,
+                        "category": cat,
+                        "node_type": "EXTERNAL_SERVICE",
+                    }
+
+            for svc_id, evidences in seen_for_repo.items():
+                conf = "HIGH" if len(evidences) >= 2 else "MEDIUM"
+                relationships.append(RepositoryRelationship(
+                    from_repo=repo,
+                    to_repo=svc_id,
+                    relation_type="USES_SERVICE",
+                    confidence=conf,
+                    evidence=list(dict.fromkeys(evidences))[:5],
+                    details=[{"service": svc_id}],
+                ))
+
+        ext_nodes = list(seen_ext.values())
+        return relationships, ext_nodes
+
+
+# ---------------------------------------------------------------------------
+# External service classification tables
+# ---------------------------------------------------------------------------
+
+# Each entry: (group_id_pattern, artifact_id_pattern) → service descriptor
+_MAVEN_SERVICE_RULES: list[tuple[str, str, dict]] = [
+    # ── AI providers ──────────────────────────────────────────────────────────
+    ("com.anthropic",          "",                           {"id": "anthropic-claude",  "label": "Anthropic Claude"}),
+    ("com.openai",             "",                           {"id": "openai",            "label": "OpenAI"}),
+    ("",                       "azure-ai-openai",            {"id": "azure-openai",      "label": "Azure OpenAI"}),
+    ("com.azure.ai",           "",                           {"id": "azure-ai",          "label": "Azure AI"}),
+    ("com.google.cloud",       "google-cloud-aiplatform",    {"id": "google-vertex-ai",  "label": "Google Vertex AI"}),
+    ("com.google.ai.client",   "",                           {"id": "google-gemini",     "label": "Google Gemini"}),
+    # ── Azure ─────────────────────────────────────────────────────────────────
+    ("com.azure",              "azure-cosmos",               {"id": "azure-cosmos-db",   "label": "Azure Cosmos DB"}),
+    ("com.azure",              "azure-storage-blob",         {"id": "azure-blob",        "label": "Azure Blob Storage"}),
+    ("com.azure",              "azure-messaging-servicebus", {"id": "azure-service-bus", "label": "Azure Service Bus"}),
+    ("com.azure",              "azure-messaging-eventhubs",  {"id": "azure-event-hubs",  "label": "Azure Event Hubs"}),
+    ("com.azure",              "azure-messaging-eventgrid",  {"id": "azure-event-grid",  "label": "Azure Event Grid"}),
+    ("com.azure",              "azure-data-tables",          {"id": "azure-table",       "label": "Azure Table Storage"}),
+    ("com.azure",              "azure-security-keyvault",    {"id": "azure-keyvault",    "label": "Azure Key Vault"}),
+    ("com.azure",              "azure-spring-cloud",         {"id": "azure-appconfig",   "label": "Azure App Config"}),
+    ("com.microsoft.azure",    "azure-sqldb-spark",          {"id": "azure-synapse",     "label": "Azure Synapse"}),
+    ("com.microsoft.sqlserver","mssql-jdbc",                 {"id": "azure-sql",         "label": "Azure SQL / MSSQL"}),
+    # ── Databases — on-premise & cloud ───────────────────────────────────────
+    ("org.postgresql",         "",                           {"id": "postgresql",        "label": "PostgreSQL"}),
+    ("mysql",                  "mysql-connector",            {"id": "mysql",             "label": "MySQL"}),
+    ("org.mariadb.jdbc",       "",                           {"id": "mariadb",           "label": "MariaDB"}),
+    ("com.oracle",             "",                           {"id": "oracle-db",         "label": "Oracle DB"}),
+    ("com.ibm.db2",            "",                           {"id": "ibm-db2",           "label": "IBM DB2"}),
+    ("com.h2database",         "",                           {"id": "h2",                "label": "H2 Database"}),
+    ("com.sap.cloud.db.jdbc",  "",                           {"id": "sap-hana",          "label": "SAP HANA"}),
+    ("org.mongodb",            "",                           {"id": "mongodb",           "label": "MongoDB"}),
+    ("io.lettuce",             "",                           {"id": "redis",             "label": "Redis"}),
+    ("redis.clients",          "jedis",                      {"id": "redis",             "label": "Redis"}),
+    ("com.datastax",           "",                           {"id": "cassandra",         "label": "Cassandra"}),
+    # ── AWS services ──────────────────────────────────────────────────────────
+    ("software.amazon.awssdk", "s3",                         {"id": "aws-s3",            "label": "AWS S3"}),
+    ("software.amazon.awssdk", "dynamodb",                   {"id": "aws-dynamodb",      "label": "AWS DynamoDB"}),
+    ("software.amazon.awssdk", "rds",                        {"id": "aws-rds",           "label": "AWS RDS"}),
+    ("software.amazon.awssdk", "lambda",                     {"id": "aws-lambda",        "label": "AWS Lambda"}),
+    ("software.amazon.awssdk", "sns",                        {"id": "aws-sns",           "label": "AWS SNS"}),
+    ("software.amazon.awssdk", "sqs",                        {"id": "aws-sqs",           "label": "AWS SQS"}),
+    ("software.amazon.awssdk", "secretsmanager",             {"id": "aws-secrets",       "label": "AWS Secrets Manager"}),
+    ("software.amazon.awssdk", "cloudwatch",                 {"id": "aws-cloudwatch",    "label": "AWS CloudWatch"}),
+    ("software.amazon.awssdk", "",                           {"id": "aws",               "label": "AWS SDK"}),
+    ("com.amazonaws",          "",                           {"id": "aws",               "label": "AWS SDK"}),
+    # ── Google Cloud ──────────────────────────────────────────────────────────
+    ("com.google.cloud",       "google-cloud-storage",       {"id": "gcs",               "label": "Google Cloud Storage"}),
+    ("com.google.cloud",       "google-cloud-pubsub",        {"id": "google-pubsub",     "label": "Google Pub/Sub"}),
+    ("com.google.cloud",       "google-cloud-firestore",     {"id": "firestore",         "label": "Google Firestore"}),
+    ("com.google.cloud",       "google-cloud-spanner",       {"id": "cloud-spanner",     "label": "Cloud Spanner"}),
+    ("com.google.cloud",       "google-cloud-secretmanager", {"id": "gcp-secrets",       "label": "GCP Secret Manager"}),
+    ("com.google.cloud",       "google-cloud-bigquery",      {"id": "bigquery",          "label": "BigQuery"}),
+    # ── Messaging ─────────────────────────────────────────────────────────────
+    ("org.apache.kafka",       "",                           {"id": "kafka",             "label": "Apache Kafka"}),
+    ("org.apache.activemq",    "",                           {"id": "activemq",          "label": "Apache ActiveMQ"}),
+    ("com.rabbitmq",           "",                           {"id": "rabbitmq",          "label": "RabbitMQ"}),
+    ("com.ibm.mq",             "",                           {"id": "ibm-mq",            "label": "IBM MQ"}),
+    # ── Analytics ─────────────────────────────────────────────────────────────
+    ("com.databricks",         "",                           {"id": "databricks",        "label": "Databricks"}),
+    ("net.snowflake",          "",                           {"id": "snowflake",         "label": "Snowflake"}),
+    # ── Observability ─────────────────────────────────────────────────────────
+    ("com.datadoghq",          "",                           {"id": "datadog",           "label": "Datadog"}),
+    ("com.newrelic",           "",                           {"id": "newrelic",          "label": "New Relic"}),
+    ("co.elastic",             "",                           {"id": "elasticsearch",     "label": "Elasticsearch"}),
+    ("io.micrometer",          "micrometer-registry-prometheus", {"id": "prometheus",    "label": "Prometheus"}),
+    ("com.splunk",             "",                           {"id": "splunk",            "label": "Splunk"}),
+    # ── Secrets / Config ──────────────────────────────────────────────────────
+    ("com.bettercloud",        "vault-java-driver",          {"id": "hashicorp-vault",   "label": "HashiCorp Vault"}),
+    # ── Auth ──────────────────────────────────────────────────────────────────
+    ("com.okta",               "",                           {"id": "okta",              "label": "Okta"}),
+    ("com.auth0",              "",                           {"id": "auth0",             "label": "Auth0"}),
+    # ── SaaS ──────────────────────────────────────────────────────────────────
+    ("com.force.api",          "",                           {"id": "salesforce",        "label": "Salesforce"}),
+    ("com.sforce",             "",                           {"id": "salesforce",        "label": "Salesforce"}),
+    # ── IBM ───────────────────────────────────────────────────────────────────
+    ("com.ibm",                "",                           {"id": "ibm",               "label": "IBM"}),
+]
+
+_NPM_SERVICE_RULES: list[tuple[str, dict]] = [
+    # ── AI ────────────────────────────────────────────────────────────────────
+    ("@anthropic-ai/sdk",           {"id": "anthropic-claude", "label": "Anthropic Claude"}),
+    ("anthropic",                   {"id": "anthropic-claude", "label": "Anthropic Claude"}),
+    ("openai",                      {"id": "openai",           "label": "OpenAI"}),
+    ("@azure/openai",               {"id": "azure-openai",     "label": "Azure OpenAI"}),
+    ("@google-cloud/aiplatform",    {"id": "google-vertex-ai", "label": "Google Vertex AI"}),
+    ("@google/generative-ai",       {"id": "google-gemini",    "label": "Google Gemini"}),
+    # ── Azure ─────────────────────────────────────────────────────────────────
+    ("@azure/cosmos",               {"id": "azure-cosmos-db",  "label": "Azure Cosmos DB"}),
+    ("@azure/storage-blob",         {"id": "azure-blob",       "label": "Azure Blob Storage"}),
+    ("@azure/service-bus",          {"id": "azure-service-bus","label": "Azure Service Bus"}),
+    ("@azure/event-hubs",           {"id": "azure-event-hubs", "label": "Azure Event Hubs"}),
+    ("@azure/eventgrid",            {"id": "azure-event-grid", "label": "Azure Event Grid"}),
+    ("@azure/synapse-analytics",    {"id": "azure-synapse",    "label": "Azure Synapse"}),
+    ("@azure/keyvault",             {"id": "azure-keyvault",   "label": "Azure Key Vault"}),
+    ("@azure/app-configuration",    {"id": "azure-appconfig",  "label": "Azure App Config"}),
+    ("@azure/msal",                 {"id": "azure-ad",         "label": "Azure AD (Entra)"}),
+    ("mssql",                       {"id": "azure-sql",        "label": "Azure SQL / MSSQL"}),
+    # ── Databases — on-premise & cloud ───────────────────────────────────────
+    ("pg",                          {"id": "postgresql",       "label": "PostgreSQL"}),
+    ("mysql2",                      {"id": "mysql",            "label": "MySQL"}),
+    ("mariadb",                     {"id": "mariadb",          "label": "MariaDB"}),
+    ("mongodb",                     {"id": "mongodb",          "label": "MongoDB"}),
+    ("mongoose",                    {"id": "mongodb",          "label": "MongoDB"}),
+    ("ioredis",                     {"id": "redis",            "label": "Redis"}),
+    ("redis",                       {"id": "redis",            "label": "Redis"}),
+    ("cassandra-driver",            {"id": "cassandra",        "label": "Cassandra"}),
+    ("@datastax/astra-db-ts",       {"id": "cassandra",        "label": "Cassandra / Astra"}),
+    ("@google-cloud/firestore",     {"id": "firestore",        "label": "Google Firestore"}),
+    # ── AWS services ──────────────────────────────────────────────────────────
+    ("@aws-sdk/client-s3",          {"id": "aws-s3",           "label": "AWS S3"}),
+    ("@aws-sdk/client-dynamodb",    {"id": "aws-dynamodb",     "label": "AWS DynamoDB"}),
+    ("@aws-sdk/client-lambda",      {"id": "aws-lambda",       "label": "AWS Lambda"}),
+    ("@aws-sdk/client-sns",         {"id": "aws-sns",          "label": "AWS SNS"}),
+    ("@aws-sdk/client-sqs",         {"id": "aws-sqs",          "label": "AWS SQS"}),
+    ("@aws-sdk/client-secrets-manager", {"id": "aws-secrets",  "label": "AWS Secrets Manager"}),
+    ("@aws-sdk/client-cloudwatch",  {"id": "aws-cloudwatch",   "label": "AWS CloudWatch"}),
+    ("@aws-sdk/client-rds",         {"id": "aws-rds",          "label": "AWS RDS"}),
+    # ── Google Cloud ──────────────────────────────────────────────────────────
+    ("@google-cloud/storage",       {"id": "gcs",              "label": "Google Cloud Storage"}),
+    ("@google-cloud/pubsub",        {"id": "google-pubsub",    "label": "Google Pub/Sub"}),
+    ("@google-cloud/spanner",       {"id": "cloud-spanner",    "label": "Cloud Spanner"}),
+    ("@google-cloud/secret-manager",{"id": "gcp-secrets",      "label": "GCP Secret Manager"}),
+    ("@google-cloud/bigquery",      {"id": "bigquery",         "label": "BigQuery"}),
+    # ── Messaging ─────────────────────────────────────────────────────────────
+    ("kafkajs",                     {"id": "kafka",            "label": "Apache Kafka"}),
+    ("kafka-node",                  {"id": "kafka",            "label": "Apache Kafka"}),
+    ("amqplib",                     {"id": "rabbitmq",         "label": "RabbitMQ"}),
+    ("activemq-stomp",              {"id": "activemq",         "label": "Apache ActiveMQ"}),
+    ("ibmmq",                       {"id": "ibm-mq",           "label": "IBM MQ"}),
+    # ── Analytics ─────────────────────────────────────────────────────────────
+    ("@databricks/sql",             {"id": "databricks",       "label": "Databricks"}),
+    # ── Observability ─────────────────────────────────────────────────────────
+    ("dd-trace",                    {"id": "datadog",          "label": "Datadog"}),
+    ("newrelic",                    {"id": "newrelic",         "label": "New Relic"}),
+    ("@elastic/elasticsearch",      {"id": "elasticsearch",    "label": "Elasticsearch"}),
+    ("prom-client",                 {"id": "prometheus",       "label": "Prometheus"}),
+    ("splunk-logging",              {"id": "splunk",           "label": "Splunk"}),
+    ("@grafana/data",               {"id": "grafana",          "label": "Grafana"}),
+    # ── Secrets ───────────────────────────────────────────────────────────────
+    ("node-vault",                  {"id": "hashicorp-vault",  "label": "HashiCorp Vault"}),
+    # ── Auth ──────────────────────────────────────────────────────────────────
+    ("@auth0/auth0-react",          {"id": "auth0",            "label": "Auth0"}),
+    ("@auth0/auth0-spa-js",         {"id": "auth0",            "label": "Auth0"}),
+    ("@okta/okta-react",            {"id": "okta",             "label": "Okta"}),
+    ("@okta/okta-auth-js",          {"id": "okta",             "label": "Okta"}),
+    # ── Payments & comms ──────────────────────────────────────────────────────
+    ("stripe",                      {"id": "stripe",           "label": "Stripe"}),
+    ("twilio",                      {"id": "twilio",           "label": "Twilio"}),
+    ("@sendgrid/mail",              {"id": "sendgrid",         "label": "SendGrid"}),
+    # ── SaaS CRM ──────────────────────────────────────────────────────────────
+    ("jsforce",                     {"id": "salesforce",       "label": "Salesforce"}),
+    ("@salesforce/core",            {"id": "salesforce",       "label": "Salesforce"}),
+    # ── AWS catch-all (must be LAST) ──────────────────────────────────────────
+    ("@aws-sdk",                    {"id": "aws",              "label": "AWS SDK"}),
+    ("aws-sdk",                     {"id": "aws",              "label": "AWS SDK"}),
+]
+
+# Hostname / URL fragment → service  (ORDER MATTERS — more specific first)
+_URL_SERVICE_RULES: list[tuple[str, dict]] = [
+    # ── AI ────────────────────────────────────────────────────────────────────
+    ("api.anthropic.com",           {"id": "anthropic-claude",  "label": "Anthropic Claude"}),
+    ("api.openai.com",              {"id": "openai",            "label": "OpenAI"}),
+    ("openai.azure.com",            {"id": "azure-openai",      "label": "Azure OpenAI"}),
+    ("cognitiveservices.azure.com", {"id": "azure-ai",          "label": "Azure AI"}),
+    ("generativelanguage.googleapis.com", {"id": "google-gemini","label": "Google Gemini"}),
+    ("aiplatform.googleapis.com",   {"id": "google-vertex-ai",  "label": "Google Vertex AI"}),
+    # ── Azure (specific before generic) ───────────────────────────────────────
+    ("cosmos.azure.com",            {"id": "azure-cosmos-db",   "label": "Azure Cosmos DB"}),
+    ("blob.core.windows.net",       {"id": "azure-blob",        "label": "Azure Blob Storage"}),
+    ("file.core.windows.net",       {"id": "azure-blob",        "label": "Azure File Storage"}),
+    ("core.windows.net",            {"id": "azure-blob",        "label": "Azure Blob Storage"}),
+    ("servicebus.windows.net",      {"id": "azure-service-bus", "label": "Azure Service Bus"}),
+    ("eventhub.windows.net",        {"id": "azure-event-hubs",  "label": "Azure Event Hubs"}),
+    ("eventgrid.azure.net",         {"id": "azure-event-grid",  "label": "Azure Event Grid"}),
+    ("database.windows.net",        {"id": "azure-sql",         "label": "Azure SQL"}),
+    ("vault.azure.net",             {"id": "azure-keyvault",    "label": "Azure Key Vault"}),
+    ("appconfig.azure.net",         {"id": "azure-appconfig",   "label": "Azure App Config"}),
+    ("login.microsoftonline.com",   {"id": "azure-ad",          "label": "Azure AD (Entra)"}),
+    ("sts.windows.net",             {"id": "azure-ad",          "label": "Azure AD (Entra)"}),
+    ("graph.microsoft.com",         {"id": "azure-ad",          "label": "Azure AD (Entra)"}),
+    ("azuresynapse.net",            {"id": "azure-synapse",     "label": "Azure Synapse"}),
+    # ── AWS (specific before generic) ─────────────────────────────────────────
+    ("s3.amazonaws.com",            {"id": "aws-s3",            "label": "AWS S3"}),
+    ("s3.",                         {"id": "aws-s3",            "label": "AWS S3"}),
+    ("rds.amazonaws.com",           {"id": "aws-rds",           "label": "AWS RDS"}),
+    ("lambda.amazonaws.com",        {"id": "aws-lambda",        "label": "AWS Lambda"}),
+    ("sns.amazonaws.com",           {"id": "aws-sns",           "label": "AWS SNS"}),
+    ("amazonaws.com/sqs",           {"id": "aws-sqs",           "label": "AWS SQS"}),
+    ("secretsmanager.amazonaws.com",{"id": "aws-secrets",       "label": "AWS Secrets Manager"}),
+    ("cloudwatch.amazonaws.com",    {"id": "aws-cloudwatch",    "label": "AWS CloudWatch"}),
+    ("es.amazonaws.com",            {"id": "elasticsearch",     "label": "Elasticsearch"}),
+    ("amazonaws.com",               {"id": "aws",               "label": "AWS"}),
+    # ── Google Cloud ──────────────────────────────────────────────────────────
+    ("storage.googleapis.com",      {"id": "gcs",               "label": "Google Cloud Storage"}),
+    ("pubsub.googleapis.com",       {"id": "google-pubsub",     "label": "Google Pub/Sub"}),
+    ("firestore.googleapis.com",    {"id": "firestore",         "label": "Google Firestore"}),
+    ("spanner.googleapis.com",      {"id": "cloud-spanner",     "label": "Cloud Spanner"}),
+    ("secretmanager.googleapis.com",{"id": "gcp-secrets",       "label": "GCP Secret Manager"}),
+    ("bigquery.googleapis.com",     {"id": "bigquery",          "label": "BigQuery"}),
+    ("run.app",                     {"id": "cloud-run",         "label": "Google Cloud Run"}),
+    # ── Analytics ─────────────────────────────────────────────────────────────
+    ("azdatabricks.net",            {"id": "databricks",        "label": "Databricks"}),
+    ("databricks.com",              {"id": "databricks",        "label": "Databricks"}),
+    ("snowflakecomputing.com",      {"id": "snowflake",         "label": "Snowflake"}),
+    # ── Observability ─────────────────────────────────────────────────────────
+    ("datadoghq.com",               {"id": "datadog",           "label": "Datadog"}),
+    ("newrelic.com",                {"id": "newrelic",          "label": "New Relic"}),
+    ("elastic.co",                  {"id": "elasticsearch",     "label": "Elasticsearch"}),
+    ("hec.splunk.com",              {"id": "splunk",            "label": "Splunk"}),
+    ("splunk.com",                  {"id": "splunk",            "label": "Splunk"}),
+    ("grafana.com",                 {"id": "grafana",           "label": "Grafana"}),
+    # ── Secrets ───────────────────────────────────────────────────────────────
+    ("vault.hashicorp.com",         {"id": "hashicorp-vault",   "label": "HashiCorp Vault"}),
+    # ── Messaging ─────────────────────────────────────────────────────────────
+    ("kafka",                       {"id": "kafka",             "label": "Apache Kafka"}),
+    # ── Auth ──────────────────────────────────────────────────────────────────
+    ("auth0.com",                   {"id": "auth0",             "label": "Auth0"}),
+    ("okta.com",                    {"id": "okta",              "label": "Okta"}),
+    # ── SaaS ──────────────────────────────────────────────────────────────────
+    ("stripe.com",                  {"id": "stripe",            "label": "Stripe"}),
+    ("twilio.com",                  {"id": "twilio",            "label": "Twilio"}),
+    ("sendgrid.net",                {"id": "sendgrid",          "label": "SendGrid"}),
+    ("salesforce.com",              {"id": "salesforce",        "label": "Salesforce"}),
+    ("force.com",                   {"id": "salesforce",        "label": "Salesforce"}),
+    ("service-now.com",             {"id": "servicenow",        "label": "ServiceNow"}),
+    ("servicenow.com",              {"id": "servicenow",        "label": "ServiceNow"}),
+]
+
+# JDBC URL / host / db_type patterns → service
+_DB_SERVICE_RULES: list[tuple[str, dict]] = [
+    # Azure SQL (most specific first)
+    ("database.windows.net", {"id": "azure-sql",      "label": "Azure SQL / MSSQL"}),
+    ("sqlserver",            {"id": "azure-sql",      "label": "Azure SQL / MSSQL"}),
+    # Other relational
+    ("postgresql",           {"id": "postgresql",     "label": "PostgreSQL"}),
+    ("postgres",             {"id": "postgresql",     "label": "PostgreSQL"}),
+    ("mysql",                {"id": "mysql",          "label": "MySQL"}),
+    ("mariadb",              {"id": "mariadb",        "label": "MariaDB"}),
+    ("oracle",               {"id": "oracle-db",      "label": "Oracle DB"}),
+    ("db2",                  {"id": "ibm-db2",        "label": "IBM DB2"}),
+    ("h2",                   {"id": "h2",             "label": "H2 Database"}),
+    ("hana",                 {"id": "sap-hana",       "label": "SAP HANA"}),
+    ("sybase",               {"id": "sybase",         "label": "Sybase"}),
+    # NoSQL
+    ("mongodb",              {"id": "mongodb",        "label": "MongoDB"}),
+    ("redis",                {"id": "redis",          "label": "Redis"}),
+    ("cassandra",            {"id": "cassandra",      "label": "Cassandra"}),
+    ("cosmos",               {"id": "azure-cosmos-db","label": "Azure Cosmos DB"}),
+    ("couchbase",            {"id": "couchbase",      "label": "Couchbase"}),
+    ("neo4j",                {"id": "neo4j",          "label": "Neo4j"}),
+    # AWS RDS (by hostname)
+    ("rds.amazonaws.com",    {"id": "aws-rds",        "label": "AWS RDS"}),
+    # Analytics
+    ("databricks",           {"id": "databricks",     "label": "Databricks"}),
+    ("synapse",              {"id": "azure-synapse",  "label": "Azure Synapse"}),
+    ("snowflake",            {"id": "snowflake",      "label": "Snowflake"}),
+    ("bigquery",             {"id": "bigquery",       "label": "BigQuery"}),
+    ("redshift",             {"id": "aws-redshift",   "label": "AWS Redshift"}),
+]
+
+# Category per service id (for colour grouping in the graph)
+_SERVICE_CATEGORIES: dict[str, str] = {
+    # AI
+    "anthropic-claude": "ai",
+    "openai":           "ai",
+    "azure-openai":     "ai",
+    "azure-ai":         "ai",
+    "google-vertex-ai": "ai",
+    "google-gemini":    "ai",
+    # Azure
+    "azure":            "azure",
+    "azure-cosmos-db":  "azure",
+    "azure-blob":       "azure",
+    "azure-service-bus":"azure",
+    "azure-event-hubs": "azure",
+    "azure-event-grid": "azure",
+    "azure-table":      "azure",
+    "azure-synapse":    "analytics",
+    "azure-keyvault":   "azure",
+    "azure-appconfig":  "azure",
+    "azure-ad":         "auth",
+    "azure-sql":        "database",
+    # AWS
+    "aws":              "cloud",
+    "aws-s3":           "cloud",
+    "aws-lambda":       "cloud",
+    "aws-cloudwatch":   "observability",
+    "aws-sqs":          "messaging",
+    "aws-sns":          "messaging",
+    "aws-dynamodb":     "database",
+    "aws-rds":          "database",
+    "aws-redshift":     "analytics",
+    "aws-secrets":      "azure",  # grouped with secrets/config
+    # Google Cloud
+    "gcs":              "cloud",
+    "google-pubsub":    "messaging",
+    "firestore":        "database",
+    "cloud-spanner":    "database",
+    "gcp-secrets":      "cloud",
+    "cloud-run":        "cloud",
+    # Databases
+    "postgresql":       "database",
+    "mysql":            "database",
+    "mariadb":          "database",
+    "oracle-db":        "database",
+    "ibm-db2":          "database",
+    "h2":               "database",
+    "sap-hana":         "database",
+    "sybase":           "database",
+    "mongodb":          "database",
+    "redis":            "database",
+    "cassandra":        "database",
+    "couchbase":        "database",
+    "neo4j":            "database",
+    # Messaging
+    "kafka":            "messaging",
+    "rabbitmq":         "messaging",
+    "activemq":         "messaging",
+    "ibm-mq":           "messaging",
+    # Analytics
+    "databricks":       "analytics",
+    "bigquery":         "analytics",
+    "snowflake":        "analytics",
+    # Observability
+    "datadog":          "observability",
+    "newrelic":         "observability",
+    "elasticsearch":    "observability",
+    "prometheus":       "observability",
+    "grafana":          "observability",
+    "splunk":           "observability",
+    # Auth
+    "auth0":            "auth",
+    "okta":             "auth",
+    "hashicorp-vault":  "auth",
+    # SaaS
+    "stripe":           "saas",
+    "twilio":           "saas",
+    "sendgrid":         "saas",
+    "salesforce":       "saas",
+    "servicenow":       "saas",
+    # IBM
+    "ibm":              "cloud",
+    "ibm-mq":           "messaging",
+}
+
+
+def _classify_library(group_id: str, artifact_id: str) -> dict | None:
+    for g, a, svc in _MAVEN_SERVICE_RULES:
+        if g and not group_id.startswith(g):
+            continue
+        if a and a not in artifact_id:
+            continue
+        if g or a:
+            return svc
+    return None
+
+
+def _classify_npm_package(pkg: str) -> dict | None:
+    for pattern, svc in _NPM_SERVICE_RULES:
+        if pkg == pattern or pkg.startswith(pattern):
+            return svc
+    return None
+
+
+def _classify_db_url(url: str, host: str, db_type: str) -> dict | None:
+    combined = f"{url} {host} {db_type}".lower()
+    for pattern, svc in _DB_SERVICE_RULES:
+        if pattern in combined:
+            return svc
+    return None
+
+
+def _classify_api_url(url: str) -> dict | None:
+    url_l = url.lower()
+    for pattern, svc in _URL_SERVICE_RULES:
+        if pattern in url_l:
+            return svc
+    return None
+
+
+def _service_category(svc_id: str) -> str:
+    return _SERVICE_CATEGORIES.get(svc_id, "external")
+
+
+# ---------------------------------------------------------------------------
+# Pure helper functions
+# ---------------------------------------------------------------------------
+
+def _normalise_path(path: str) -> str:
+    """Lowercase, strip leading slash, collapse path params, strip query string."""
+    p = (path or "").strip().lstrip("/").lower().split("?")[0]
+    p = re.sub(r'(?:\{[^}]+\}|:[^/]+|\d+)', '{p}', p)
+    return p.strip("/")
+
+
+def _strip_suffix(name: str) -> str:
+    """Remove common class-name suffixes to get the domain concept."""
+    for suffix in _SERVICE_SUFFIXES:
+        if name.endswith(suffix) and len(name) > len(suffix):
+            return name[: -len(suffix)]
+    return name
+
+
+def _normalise_name(name: str) -> str:
+    """Convert CamelCase/snake_case/kebab to lowercase words joined."""
+    # Insert space before uppercase sequences
+    s = re.sub(r'([A-Z]+)([A-Z][a-z])', r'\1 \2', name)
+    s = re.sub(r'([a-z\d])([A-Z])', r'\1 \2', s)
+    s = s.replace("_", " ").replace("-", " ").lower().strip()
+    return s
+
+
+def _synonym_group(word: str) -> int | None:
+    return _WORD_TO_GROUP.get(word.lower())
+
+
+def _find_semantic_matches(names_a: set[str], names_b: set[str]) -> list[str]:
+    """Return list of concept strings that appear in both sets (with synonym expansion)."""
+    shared = []
+    for na in names_a:
+        for nb in names_b:
+            if na == nb:
+                shared.append(na)
+                break
+            # Check synonym overlap: any word in na shares a group with any word in nb
+            words_a = set(na.split())
+            words_b = set(nb.split())
+            for wa in words_a:
+                ga = _synonym_group(wa)
+                if ga is None:
+                    continue
+                for wb in words_b:
+                    if _synonym_group(wb) == ga:
+                        shared.append(f"{na} ~ {nb}")
+                        break
+                else:
+                    continue
+                break
+    return list(dict.fromkeys(shared))  # preserve order, deduplicate
+
+
+def _group_shared_artifact(
+    rows: list[dict],
+    key_field: str,
+    relation_type: str,
+    label: str,
+) -> list[RepositoryRelationship]:
+    """Group artifact rows by artifact name; emit relationship for each pair of repos sharing it."""
+    artifact_to_repos: dict[str, set[str]] = {}
+    for r in rows:
+        artifact = (r.get(key_field) or "").strip()
+        repo = r.get("repo", "")
+        if artifact and repo:
+            artifact_to_repos.setdefault(artifact, set()).add(repo)
+
+    out = []
+    for artifact, repo_set in artifact_to_repos.items():
+        repo_list = sorted(repo_set)
+        for i, ra in enumerate(repo_list):
+            for rb in repo_list[i + 1:]:
+                out.append(RepositoryRelationship(
+                    from_repo=ra,
+                    to_repo=rb,
+                    relation_type=relation_type,
+                    confidence="MEDIUM",
+                    evidence=[f"{label}: {artifact}"],
+                    details=[{key_field: artifact}],
+                ))
+    return out
+
+
+def _dedup_relationships(
+    rels: list[RepositoryRelationship],
+) -> list[RepositoryRelationship]:
+    """
+    For the same (from, to, type) keep only the highest-confidence entry.
+    Merge evidence lists.
+    """
+    _order = {"HIGH": 0, "MEDIUM": 1, "LOW": 2}
+    best: dict[tuple, RepositoryRelationship] = {}
+    for r in rels:
+        key = (r.from_repo, r.to_repo, r.relation_type)
+        existing = best.get(key)
+        if existing is None or _order[r.confidence] < _order[existing.confidence]:
+            best[key] = r
+        else:
+            # Merge evidence
+            existing.evidence = list(dict.fromkeys(existing.evidence + r.evidence))[:10]
+            existing.details = (existing.details + r.details)[:20]
+    return list(best.values())
+
+
+def _rel_to_dict(r: RepositoryRelationship) -> dict[str, Any]:
+    return {
+        "from": r.from_repo,
+        "to": r.to_repo,
+        "type": r.relation_type,
+        "confidence": r.confidence,
+        "evidence": r.evidence,
+        "details": r.details,
+    }