From bd5af0fe38a332de639318730c25ec0b05be026f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s=20Contreras=20Guill=C3=A9n?=
 <ancongui@Andress-MacBook-Pro-2.local>
Date: Wed, 10 Jun 2026 02:06:45 +0200
Subject: [PATCH 1/6] feat(config-server): add GitConfigBackend adapter with
 GitPython + config-server-git extra
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

New `src/pyfly/config_server/adapters/git.py`: `GitConfigBackend` that lazily
clones a Git repo (local path or remote URI) and composes a
`FilesystemConfigBackend` over the working tree for all file-read logic.
`save()` commits changes locally (no push — documented out of scope).
`refresh()` pulls from origin when a remote exists.

- Lazy import via `_require_git()` helper; friendly ImportError when absent
- `pyproject.toml`: adds `config-server-git = ["GitPython>=3.1"]` extra and
  includes it in `full`; `uv lock` resolves gitdb/smmap/gitpython
- `tests/config_server/test_git_backend.py`: six `importorskip("git")` tests
  covering fetch, list, save-commits, save-updates, refresh-no-remote, and
  missing-returns-None — all using a local on-disk repo (no network)
---
 pyproject.toml                          |   5 +-
 src/pyfly/config_server/adapters/git.py | 175 ++++++++++++++++++++++++
 tests/config_server/test_git_backend.py | 169 +++++++++++++++++++++++
 uv.lock                                 |  42 +++++-
 4 files changed, 388 insertions(+), 3 deletions(-)
 create mode 100644 src/pyfly/config_server/adapters/git.py
 create mode 100644 tests/config_server/test_git_backend.py

diff --git a/pyproject.toml b/pyproject.toml
index cb1e91ac..9a238105 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -88,6 +88,9 @@ cache = [
 client = [
     "httpx>=0.28.1",
 ]
+config-server-git = [
+    "GitPython>=3.1",
+]
 grpc = [
     "grpcio>=1.60.0",
 ]
@@ -150,7 +153,7 @@ web-fastapi = [
     "uvloop>=0.22.1; sys_platform != 'win32'",
 ]
 full = [
-    "pyfly[web,data-relational,data-document,postgresql,eda,cache,client,grpc,websocket,ecm-aws,ecm-azure,observability,security,scheduling,cli,shell,kafka,rabbitmq,redis,granian,fastapi,hypercorn,idp-azure,idp-keycloak,idp-cognito,notifications]",
+    "pyfly[web,data-relational,data-document,postgresql,eda,cache,client,grpc,websocket,ecm-aws,ecm-azure,observability,security,scheduling,cli,shell,kafka,rabbitmq,redis,granian,fastapi,hypercorn,idp-azure,idp-keycloak,idp-cognito,notifications,config-server-git]",
 ]
 
 [dependency-groups]
diff --git a/src/pyfly/config_server/adapters/git.py b/src/pyfly/config_server/adapters/git.py
new file mode 100644
index 00000000..b8a7ea48
--- /dev/null
+++ b/src/pyfly/config_server/adapters/git.py
@@ -0,0 +1,175 @@
+# Copyright 2026 Firefly Software Foundation.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Git-backed config backend — wraps a local or remote Git repository.
+
+Config files are read from the working tree of a cloned (or locally accessed)
+repository; writes are committed locally. Pushing to a remote is **out of
+scope** — call ``refresh()`` after a remote push to pull the latest commits.
+
+Requires GitPython: ``pip install pyfly[config-server-git]``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import importlib.util
+import logging
+import tempfile
+from typing import Any
+
+from pyfly.config_server.backend import ConfigSource, FilesystemConfigBackend
+
+_logger = logging.getLogger(__name__)
+
+
+def _require_git() -> Any:
+    """Import and return the ``git`` module, raising a friendly ImportError if absent."""
+    try:
+        import git
+
+        return git
+    except ImportError as exc:
+        msg = "GitConfigBackend requires GitPython — `pip install pyfly[config-server-git]`"
+        raise ImportError(msg) from exc
+
+
+class GitConfigBackend:
+    """``ConfigBackend`` backed by a Git repository.
+
+    On first use the repository is cloned (or, for a local ``file://`` / path
+    URI, the on-disk repo is reused) into *clone_dir* (or a tempdir when
+    *clone_dir* is ``None``).  The working tree is then delegated to a
+    :class:`~pyfly.config_server.backend.FilesystemConfigBackend` so all the
+    file-search and merge logic is shared.
+
+    Parameters
+    ----------
+    uri:
+        Any URI accepted by ``git clone``: ``https://``, ``git@``, or a local
+        path (``/path/to/repo`` or ``file:///path/to/repo``).
+    label:
+        Branch (or tag / SHA) to check out.  Defaults to ``"main"``.
+    clone_dir:
+        Where to clone the repository.  When *None* a temporary directory is
+        created automatically and cleaned up when the process exits.
+    """
+
+    def __init__(
+        self,
+        uri: str,
+        *,
+        label: str = "main",
+        clone_dir: str | None = None,
+    ) -> None:
+        self._uri = uri
+        self._label = label
+        self._clone_dir = clone_dir
+        self._repo: Any = None  # git.Repo, set on first _ensure_repo() call
+        self._fs: FilesystemConfigBackend | None = None
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _ensure_repo(self) -> FilesystemConfigBackend:
+        """Lazily clone the repo and return (or return the cached) FS backend."""
+        if self._fs is not None:
+            return self._fs
+
+        git = _require_git()
+
+        work_dir = self._clone_dir or tempfile.mkdtemp(prefix="pyfly-git-config-")
+        _logger.debug("GitConfigBackend: cloning %s → %s (label=%s)", self._uri, work_dir, self._label)
+        self._repo = git.Repo.clone_from(self._uri, work_dir)
+        # Checkout the requested label (branch / tag / sha).
+        try:
+            self._repo.git.checkout(self._label)
+        except git.GitCommandError as exc:
+            _logger.warning("GitConfigBackend: could not checkout %r: %s", self._label, exc)
+
+        self._fs = FilesystemConfigBackend(work_dir)
+        return self._fs
+
+    async def _run_sync(self, fn: Any, *args: Any) -> Any:
+        """Run a synchronous callable in the default executor."""
+        loop = asyncio.get_event_loop()
+        return await loop.run_in_executor(None, fn, *args)
+
+    async def _ensure_repo_async(self) -> FilesystemConfigBackend:
+        """Async wrapper that returns a typed FilesystemConfigBackend."""
+        result: FilesystemConfigBackend = await self._run_sync(self._ensure_repo)
+        return result
+
+    # ------------------------------------------------------------------
+    # ConfigBackend protocol
+    # ------------------------------------------------------------------
+
+    async def fetch(self, application: str, profile: str, label: str = "main") -> ConfigSource | None:
+        fs = await self._ensure_repo_async()
+        return await fs.fetch(application, profile, label)
+
+    async def save(self, source: ConfigSource) -> None:
+        """Write config into the working tree and create a local Git commit.
+
+        .. note::
+            Only a local commit is created.  Pushing to the remote is **out of
+            scope** — call :meth:`refresh` to pull and :meth:`save` to write,
+            then push manually if needed.
+        """
+        git = _require_git()
+
+        fs = await self._ensure_repo_async()
+        await fs.save(source)
+
+        repo: Any = self._repo
+
+        def _commit() -> None:
+            # Stage all modified / new files under the work tree.
+            repo.git.add(A=True)
+            if not repo.index.diff("HEAD") and not repo.untracked_files:
+                _logger.debug("GitConfigBackend.save: nothing to commit")
+                return
+            commit_msg = f"pyfly: update {source.application}/{source.profile}@{source.label}"
+            try:
+                repo.index.commit(commit_msg)
+            except git.GitCommandError as exc:
+                _logger.warning("GitConfigBackend.save: commit failed: %s", exc)
+
+        await self._run_sync(_commit)
+
+    async def list(self) -> list[ConfigSource]:
+        fs = await self._ensure_repo_async()
+        return await fs.list()
+
+    # ------------------------------------------------------------------
+    # Git-specific extra
+    # ------------------------------------------------------------------
+
+    async def refresh(self) -> None:
+        """Pull the latest commits from ``origin`` (no-op when no remote exists)."""
+        if importlib.util.find_spec("git") is None:
+            msg = "GitConfigBackend requires GitPython — `pip install pyfly[config-server-git]`"
+            raise ImportError(msg)
+
+        await self._ensure_repo_async()  # ensures self._repo is set
+        repo: Any = self._repo
+        if not repo.remotes:
+            _logger.debug("GitConfigBackend.refresh: no remotes — skipping pull")
+            return
+
+        def _pull() -> None:
+            repo.remotes.origin.pull()
+
+        _logger.debug("GitConfigBackend.refresh: pulling from origin")
+        await self._run_sync(_pull)
diff --git a/tests/config_server/test_git_backend.py b/tests/config_server/test_git_backend.py
new file mode 100644
index 00000000..b4e08e0e
--- /dev/null
+++ b/tests/config_server/test_git_backend.py
@@ -0,0 +1,169 @@
+# Copyright 2026 Firefly Software Foundation.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Tests for GitConfigBackend.
+
+All tests use a local (on-disk) bare/non-bare repository — no network access.
+The suite is skipped automatically when GitPython is not installed.
+"""
+
+from __future__ import annotations
+
+import pathlib
+
+import pytest
+
+git = pytest.importorskip("git")
+
+import yaml  # noqa: E402
+
+from pyfly.config_server.adapters.git import GitConfigBackend  # noqa: E402
+from pyfly.config_server.backend import ConfigSource  # noqa: E402
+
+
+def _make_repo(tmp_path: pathlib.Path, branch: str = "main") -> pathlib.Path:
+    """Create a local git repository with one committed config file."""
+    repo_dir = tmp_path / "origin"
+    repo_dir.mkdir()
+
+    repo = git.Repo.init(repo_dir)
+    # git requires at least name + email to commit.
+    repo.config_writer().set_value("user", "name", "Test").release()
+    repo.config_writer().set_value("user", "email", "test@example.com").release()
+
+    # Write an orders-prod.yaml on the repo root (label "main" maps to root
+    # in _path_candidates_for, but FilesystemConfigBackend also checks the
+    # label sub-directory; place it at root for simplicity).
+    orders_yaml = repo_dir / "orders-prod.yaml"
+    orders_yaml.write_text(yaml.safe_dump({"db.url": "postgres://prod", "workers": 4}))
+
+    repo.index.add(["orders-prod.yaml"])
+    repo.index.commit("initial config")
+
+    # Rename default branch to the requested name (git may default to
+    # "master" depending on the system git config).
+    if repo.active_branch.name != branch:
+        repo.head.reference = repo.create_head(branch)
+        repo.head.reset(index=True, working_tree=True)
+
+    return repo_dir
+
+
+@pytest.mark.asyncio
+async def test_git_backend_fetch(tmp_path: pathlib.Path) -> None:
+    """GitConfigBackend.fetch reads properties committed in the repo."""
+    origin = _make_repo(tmp_path)
+    clone_dir = str(tmp_path / "clone")
+
+    backend = GitConfigBackend(str(origin), label="main", clone_dir=clone_dir)
+    source = await backend.fetch("orders", "prod")
+
+    assert source is not None
+    assert source.application == "orders"
+    assert source.profile == "prod"
+    assert source.properties["db.url"] == "postgres://prod"
+    assert source.properties["workers"] == 4
+
+
+@pytest.mark.asyncio
+async def test_git_backend_list(tmp_path: pathlib.Path) -> None:
+    """GitConfigBackend.list enumerates committed config files."""
+    origin = _make_repo(tmp_path)
+    clone_dir = str(tmp_path / "clone")
+
+    backend = GitConfigBackend(str(origin), label="main", clone_dir=clone_dir)
+    sources = await backend.list()
+
+    assert any(s.application == "orders" and s.profile == "prod" for s in sources)
+
+
+@pytest.mark.asyncio
+async def test_git_backend_save_commits(tmp_path: pathlib.Path) -> None:
+    """GitConfigBackend.save writes the file and creates a local commit."""
+    origin = _make_repo(tmp_path)
+    clone_dir = str(tmp_path / "clone")
+
+    backend = GitConfigBackend(str(origin), label="main", clone_dir=clone_dir)
+    # First fetch to initialise the clone.
+    await backend.fetch("orders", "prod")
+
+    new_source = ConfigSource(
+        application="payments",
+        profile="prod",
+        label="main",
+        properties={"gateway": "stripe", "retries": 3},
+    )
+    await backend.save(new_source)
+
+    # The property is now readable through a fresh fetch.
+    fetched = await backend.fetch("payments", "prod")
+    assert fetched is not None
+    assert fetched.properties["gateway"] == "stripe"
+
+    # A commit must have been created.
+    import git as gitlib
+
+    repo = gitlib.Repo(clone_dir)
+    last_msg = repo.head.commit.message
+    assert "payments" in last_msg or "pyfly" in last_msg
+
+
+@pytest.mark.asyncio
+async def test_git_backend_save_updates_existing(tmp_path: pathlib.Path) -> None:
+    """GitConfigBackend.save updates an existing file (not creates a duplicate)."""
+    origin = _make_repo(tmp_path)
+    clone_dir = str(tmp_path / "clone")
+
+    backend = GitConfigBackend(str(origin), label="main", clone_dir=clone_dir)
+
+    updated = ConfigSource(
+        application="orders",
+        profile="prod",
+        label="main",
+        properties={"db.url": "postgres://prod-v2", "workers": 8},
+    )
+    await backend.save(updated)
+
+    fetched = await backend.fetch("orders", "prod")
+    assert fetched is not None
+    assert fetched.properties["db.url"] == "postgres://prod-v2"
+    assert fetched.properties["workers"] == 8
+
+
+@pytest.mark.asyncio
+async def test_git_backend_refresh_no_remote(tmp_path: pathlib.Path) -> None:
+    """refresh() is a no-op (not an error) when the clone has no remote."""
+    origin = _make_repo(tmp_path)
+    clone_dir = str(tmp_path / "clone")
+
+    backend = GitConfigBackend(str(origin), label="main", clone_dir=clone_dir)
+    await backend.fetch("orders", "prod")  # init clone
+
+    # Remove the remote so refresh() must skip gracefully.
+    import git as gitlib
+
+    repo = gitlib.Repo(clone_dir)
+    repo.delete_remote(repo.remote("origin"))
+
+    await backend.refresh()  # must not raise
+
+
+@pytest.mark.asyncio
+async def test_git_backend_missing_returns_none(tmp_path: pathlib.Path) -> None:
+    """fetch() returns None for a file that doesn't exist in the repo."""
+    origin = _make_repo(tmp_path)
+    clone_dir = str(tmp_path / "clone")
+
+    backend = GitConfigBackend(str(origin), label="main", clone_dir=clone_dir)
+    result = await backend.fetch("nonexistent", "dev")
+    assert result is None
diff --git a/uv.lock b/uv.lock
index e22ada86..1e7296b8 100644
--- a/uv.lock
+++ b/uv.lock
@@ -846,6 +846,30 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/4c/a0/614c5fe402fd88951df45f4dda2fa3b4e17a99ecd92340771929169b3b95/filelock-3.29.1-py3-none-any.whl", hash = "sha256:85199dfd706869641b72b2e8955d5416a4b2b7dc4b0e8e6d97b4cc1299a6983b", size = 40750, upload-time = "2026-06-03T15:19:02.959Z" },
 ]
 
+[[package]]
+name = "gitdb"
+version = "4.0.12"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "smmap" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/72/94/63b0fc47eb32792c7ba1fe1b694daec9a63620db1e313033d18140c2320a/gitdb-4.0.12.tar.gz", hash = "sha256:5ef71f855d191a3326fcfbc0d5da835f26b13fbcba60c32c21091c349ffdb571", size = 394684, upload-time = "2025-01-02T07:20:46.413Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/a0/61/5c78b91c3143ed5c14207f463aecfc8f9dbb5092fb2869baf37c273b2705/gitdb-4.0.12-py3-none-any.whl", hash = "sha256:67073e15955400952c6565cc3e707c554a4eea2e428946f7a4c162fab9bd9bcf", size = 62794, upload-time = "2025-01-02T07:20:43.624Z" },
+]
+
+[[package]]
+name = "gitpython"
+version = "3.1.50"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "gitdb" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/33/f6/354ae6491228b5eb40e10d89c4d13c651fe1cf7556e35ebdded50cff57ce/gitpython-3.1.50.tar.gz", hash = "sha256:80da2d12504d52e1f998772dc5baf6e553f8d2fcfe1fcc226c9d9a2ee3372dcc", size = 219798, upload-time = "2026-05-06T04:01:26.571Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/20/7a/1c6e3562dfd8950adbb11ffbc65d21e7c89d01a6e4f137fa981056de25c5/gitpython-3.1.50-py3-none-any.whl", hash = "sha256:d352abe2908d07355014abdd21ddf798c2a961469239afec4962e9da884858f9", size = 212507, upload-time = "2026-05-06T04:01:23.799Z" },
+]
+
 [[package]]
 name = "granian"
 version = "2.7.4"
@@ -2156,6 +2180,9 @@ cli = [
 client = [
     { name = "httpx" },
 ]
+config-server-git = [
+    { name = "gitpython" },
+]
 data-document = [
     { name = "beanie" },
 ]
@@ -2191,6 +2218,7 @@ full = [
     { name = "croniter" },
     { name = "cryptography" },
     { name = "fastapi" },
+    { name = "gitpython" },
     { name = "granian" },
     { name = "grpcio" },
     { name = "httpx" },
@@ -2329,6 +2357,7 @@ requires-dist = [
     { name = "croniter", marker = "extra == 'scheduling'", specifier = ">=6.2.2" },
     { name = "cryptography", marker = "extra == 'security'", specifier = ">=48.0.0" },
     { name = "fastapi", marker = "extra == 'fastapi'", specifier = ">=0.136.1" },
+    { name = "gitpython", marker = "extra == 'config-server-git'", specifier = ">=3.1" },
     { name = "granian", marker = "extra == 'granian'", specifier = ">=2.7.4" },
     { name = "grpcio", marker = "extra == 'grpc'", specifier = ">=1.60.0" },
     { name = "httpx", marker = "extra == 'client'", specifier = ">=0.28.1" },
@@ -2347,7 +2376,7 @@ requires-dist = [
     { name = "prometheus-client", marker = "extra == 'observability'", specifier = ">=0.25.0" },
     { name = "pydantic", specifier = ">=2.13.3" },
     { name = "pyfly", extras = ["fastapi", "granian"], marker = "extra == 'web-fastapi'" },
-    { name = "pyfly", extras = ["web", "data-relational", "data-document", "postgresql", "eda", "cache", "client", "grpc", "websocket", "ecm-aws", "ecm-azure", "observability", "security", "scheduling", "cli", "shell", "kafka", "rabbitmq", "redis", "granian", "fastapi", "hypercorn", "idp-azure", "idp-keycloak", "idp-cognito", "notifications"], marker = "extra == 'full'" },
+    { name = "pyfly", extras = ["web", "data-relational", "data-document", "postgresql", "eda", "cache", "client", "grpc", "websocket", "ecm-aws", "ecm-azure", "observability", "security", "scheduling", "cli", "shell", "kafka", "rabbitmq", "redis", "granian", "fastapi", "hypercorn", "idp-azure", "idp-keycloak", "idp-cognito", "notifications", "config-server-git"], marker = "extra == 'full'" },
     { name = "pyfly", extras = ["web", "granian"], marker = "extra == 'web-fast'" },
     { name = "pyjwt", extras = ["crypto"], marker = "extra == 'security'", specifier = ">=2.12.1" },
     { name = "pyotp", marker = "extra == 'security'", specifier = ">=2.9.0" },
@@ -2366,7 +2395,7 @@ requires-dist = [
     { name = "uvloop", marker = "sys_platform != 'win32' and extra == 'web-fastapi'", specifier = ">=0.22.1" },
     { name = "websockets", marker = "extra == 'websocket'", specifier = ">=12.0" },
 ]
-provides-extras = ["web", "data-relational", "testing", "testcontainers", "data-document", "postgresql", "eda", "fastapi", "granian", "hypercorn", "kafka", "rabbitmq", "redis", "cache", "client", "grpc", "websocket", "idp-azure", "idp-keycloak", "idp-cognito", "ecm-aws", "ecm-azure", "observability", "scheduling", "pii", "security", "notifications", "cli", "shell", "web-fast", "web-fastapi", "full"]
+provides-extras = ["web", "data-relational", "testing", "testcontainers", "data-document", "postgresql", "eda", "fastapi", "granian", "hypercorn", "kafka", "rabbitmq", "redis", "cache", "client", "config-server-git", "grpc", "websocket", "idp-azure", "idp-keycloak", "idp-cognito", "ecm-aws", "ecm-azure", "observability", "scheduling", "pii", "security", "notifications", "cli", "shell", "web-fast", "web-fastapi", "full"]
 
 [package.metadata.requires-dev]
 dev = [
@@ -2863,6 +2892,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/14/78/0f68b93564b8c6b6987a0696c582ba2591a381ab2f733a501909e949f241/smart_open-7.6.1-py3-none-any.whl", hash = "sha256:b4de6aebef023aca91cc9fb372052e1343ba3f152de215bd22391a663e3ddd21", size = 64845, upload-time = "2026-05-09T06:23:35.386Z" },
 ]
 
+[[package]]
+name = "smmap"
+version = "5.0.3"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/1f/ea/49c993d6dfdd7338c9b1000a0f36817ed7ec84577ae2e52f890d1a4ff909/smmap-5.0.3.tar.gz", hash = "sha256:4d9debb8b99007ae47165abc08670bd74cb74b5227dda7f643eccc4e9eb5642c", size = 22506, upload-time = "2026-03-09T03:43:26.1Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/c1/d4/59e74daffcb57a07668852eeeb6035af9f32cbfd7a1d2511f17d2fe6a738/smmap-5.0.3-py3-none-any.whl", hash = "sha256:c106e05d5a61449cf6ba9a1e650227ecfb141590d2a98412103ff35d89fc7b2f", size = 24390, upload-time = "2026-03-09T03:43:24.361Z" },
+]
+
 [[package]]
 name = "spacy"
 version = "3.8.14"

From a5e541c56771d671b36e92c39f7d92a2046a05f0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s=20Contreras=20Guill=C3=A9n?=
 <ancongui@Andress-MacBook-Pro-2.local>
Date: Wed, 10 Jun 2026 02:06:51 +0200
Subject: [PATCH 2/6] feat(config-server): make ConfigClient
 transport-injectable + ASGITransport e2e test
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`client.py`: adds optional `http_client: Any | None = None` ctor param.
When injected, `fetch()` uses it without closing (caller owns lifecycle);
when omitted, builds+closes its own httpx.AsyncClient as before.

`tests/config_server/test_config_client_e2e.py`: three async tests that
drive `ConfigClient` through `httpx.ASGITransport(app=starlette_app)` with
no mocking — a real round-trip through routing, JSON serialisation, and
reverse-merge precedence (app+profile beats application+default; common-only
key survives).
---
 src/pyfly/config_server/client.py             |  37 +++--
 tests/config_server/test_config_client_e2e.py | 144 ++++++++++++++++++
 2 files changed, 171 insertions(+), 10 deletions(-)
 create mode 100644 tests/config_server/test_config_client_e2e.py

diff --git a/src/pyfly/config_server/client.py b/src/pyfly/config_server/client.py
index 5df03f52..a8d8f378 100644
--- a/src/pyfly/config_server/client.py
+++ b/src/pyfly/config_server/client.py
@@ -11,7 +11,14 @@
 
 
 class ConfigClient:
-    """Minimal HTTP client for a Spring-Cloud-Config-style server."""
+    """Minimal HTTP client for a Spring-Cloud-Config-style server.
+
+    An optional *http_client* (an ``httpx.AsyncClient`` instance) may be
+    injected for testing or connection-pool sharing.  When provided the caller
+    owns the client's lifecycle — it is **not** closed by :meth:`fetch`.  When
+    omitted, a fresh ``httpx.AsyncClient`` is created and closed per call as
+    before (unchanged public behaviour).
+    """
 
     def __init__(
         self,
@@ -22,6 +29,7 @@ def __init__(
         label: str = "main",
         username: str | None = None,
         password: str | None = None,
+        http_client: Any | None = None,
     ) -> None:
         self._url = url.rstrip("/")
         self._application = application
@@ -29,6 +37,7 @@ def __init__(
         self._label = label
         self._username = username
         self._password = password
+        self._http_client = http_client
 
     async def fetch(self) -> dict[str, Any]:
         try:
@@ -41,7 +50,8 @@ async def fetch(self) -> dict[str, Any]:
         auth: tuple[str, str] | None = (
             (self._username, self._password) if self._username is not None and self._password is not None else None
         )
-        async with httpx.AsyncClient(timeout=15.0) as client:
+
+        async def _do_get(client: Any) -> dict[str, Any]:
             resp = await client.get(path, auth=auth)
             if resp.status_code != 200:
                 _logger.warning(
@@ -52,11 +62,18 @@ async def fetch(self) -> dict[str, Any]:
                     self._label,
                 )
                 return {}
-            data = resp.json()
-        # Spring orders propertySources HIGHEST priority first, so apply them
-        # in reverse (lowest first) and let higher-priority sources overwrite —
-        # the forward order let the lowest-priority source win (audit #86).
-        merged: dict[str, Any] = {}
-        for source in reversed(data.get("propertySources", [])):
-            merged.update(source.get("source") or {})
-        return merged
+            data: dict[str, Any] = resp.json()
+            # Spring orders propertySources HIGHEST priority first, so apply them
+            # in reverse (lowest first) and let higher-priority sources overwrite —
+            # the forward order let the lowest-priority source win (audit #86).
+            merged: dict[str, Any] = {}
+            for source in reversed(data.get("propertySources", [])):
+                merged.update(source.get("source") or {})
+            return merged
+
+        if self._http_client is not None:
+            # Injected client — caller owns lifecycle; do NOT close it.
+            return await _do_get(self._http_client)
+
+        async with httpx.AsyncClient(timeout=15.0) as client:
+            return await _do_get(client)
diff --git a/tests/config_server/test_config_client_e2e.py b/tests/config_server/test_config_client_e2e.py
new file mode 100644
index 00000000..a30e377d
--- /dev/null
+++ b/tests/config_server/test_config_client_e2e.py
@@ -0,0 +1,144 @@
+# Copyright 2026 Firefly Software Foundation.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""End-to-end test: ConfigClient → Starlette (ASGITransport) → ConfigServer.
+
+The test uses ``httpx.ASGITransport`` so there is no network socket involved,
+but the full request/response path — HTTP routing, JSON serialisation, and
+``ConfigClient.fetch()``'s reverse-merge of ``propertySources`` — is exercised
+for real.  Nothing is mocked.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+httpx = pytest.importorskip("httpx")
+starlette = pytest.importorskip("starlette")
+
+from starlette.applications import Starlette  # noqa: E402
+
+from pyfly.config_server.adapters.starlette import make_starlette_config_server_routes  # noqa: E402
+from pyfly.config_server.backend import ConfigSource, InMemoryConfigBackend  # noqa: E402
+from pyfly.config_server.client import ConfigClient  # noqa: E402
+from pyfly.config_server.server import ConfigServer  # noqa: E402
+
+
+@pytest.mark.asyncio
+async def test_e2e_reverse_merge_precedence() -> None:
+    """ConfigClient merges propertySources in reverse so app+profile wins.
+
+    Seed layout
+    -----------
+    ``orders / prod``  → ``{"host": "prod.db", "port": 5432, "timeout": 30}``
+    ``application / default`` → ``{"host": "default.db", "port": 5432, "shared_key": "common"}``
+
+    Expected merged result (app+profile overrides application+default):
+    - ``host`` == ``"prod.db"``          (app+profile wins over application+default)
+    - ``port`` == 5432                    (same in both — no conflict)
+    - ``timeout`` == 30                   (only in app+profile)
+    - ``shared_key`` == ``"common"``      (only in application+default — survives)
+    """
+    # 1. Build the in-process config server.
+    backend = InMemoryConfigBackend()
+    await backend.save(
+        ConfigSource(
+            application="orders",
+            profile="prod",
+            label="main",
+            properties={"host": "prod.db", "port": 5432, "timeout": 30},
+        )
+    )
+    await backend.save(
+        ConfigSource(
+            application="application",
+            profile="default",
+            label="main",
+            properties={"host": "default.db", "port": 5432, "shared_key": "common"},
+        )
+    )
+    server = ConfigServer(backend=backend)
+    app = Starlette(routes=make_starlette_config_server_routes(server))
+
+    # 2. Create an httpx client wired directly to the ASGI app — no socket.
+    transport = httpx.ASGITransport(app=app)  # type: ignore[arg-type]
+    async with httpx.AsyncClient(transport=transport, base_url="http://config") as http_client:
+        client = ConfigClient(
+            url="http://config",
+            application="orders",
+            profile="prod",
+            label="main",
+            http_client=http_client,
+        )
+        result = await client.fetch()
+
+    # 3. Assert precedence is respected.
+    assert result["host"] == "prod.db", "app+profile must override application+default"
+    assert result["port"] == 5432
+    assert result["timeout"] == 30, "key only in app+profile must survive"
+    assert result["shared_key"] == "common", "key only in application+default must be inherited"
+
+
+@pytest.mark.asyncio
+async def test_e2e_missing_config_returns_empty() -> None:
+    """A 404 from the server should yield an empty dict, not raise."""
+    backend = InMemoryConfigBackend()
+    server = ConfigServer(backend=backend)
+    app = Starlette(routes=make_starlette_config_server_routes(server))
+
+    transport = httpx.ASGITransport(app=app)  # type: ignore[arg-type]
+    async with httpx.AsyncClient(transport=transport, base_url="http://config") as http_client:
+        client = ConfigClient(
+            url="http://config",
+            application="missing",
+            profile="ghost",
+            label="main",
+            http_client=http_client,
+        )
+        result = await client.fetch()
+
+    assert result == {}
+
+
+@pytest.mark.asyncio
+async def test_e2e_injected_client_not_closed() -> None:
+    """The injected http_client must not be closed after fetch()."""
+    backend = InMemoryConfigBackend()
+    await backend.save(
+        ConfigSource(
+            application="svc",
+            profile="default",
+            label="main",
+            properties={"k": "v"},
+        )
+    )
+    server = ConfigServer(backend=backend)
+    app = Starlette(routes=make_starlette_config_server_routes(server))
+
+    transport = httpx.ASGITransport(app=app)  # type: ignore[arg-type]
+    http_client = httpx.AsyncClient(transport=transport, base_url="http://config")
+    try:
+        client = ConfigClient(
+            url="http://config",
+            application="svc",
+            profile="default",
+            label="main",
+            http_client=http_client,
+        )
+        result = await client.fetch()
+        assert result == {"k": "v"}
+        # Client still open — a second fetch must succeed.
+        result2 = await client.fetch()
+        assert result2 == {"k": "v"}
+    finally:
+        await http_client.aclose()

From 417114b249cb02f14c304bf399a8bfe95cfc13c2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s=20Contreras=20Guill=C3=A9n?=
 <ancongui@Andress-MacBook-Pro-2.local>
Date: Wed, 10 Jun 2026 02:06:58 +0200
Subject: [PATCH 3/6] feat(config-server): add tiered search_locations to
 FilesystemConfigBackend

`backend.py`: `FilesystemConfigBackend` accepts optional
`search_locations: list[str | Path] | None = None` (highest-precedence first,
e.g. [domain, core, common]).  When set, `fetch()` iterates locations from
lowest to highest and merges properties so higher-precedence keys win and
lower-precedence fills gaps.  `save()` and `list()` always target `_root`
(the primary location).  Single-root behaviour unchanged when None.

`tests/config_server/test_tiered_overlay.py`: seven tests covering
domain-overrides-common, three-tier chain, missing-in-all, partial presence,
save-to-primary, list-uses-primary, and single-root-unchanged.
---
 src/pyfly/config_server/backend.py         |  78 ++++++++++-
 tests/config_server/test_tiered_overlay.py | 154 +++++++++++++++++++++
 2 files changed, 231 insertions(+), 1 deletion(-)
 create mode 100644 tests/config_server/test_tiered_overlay.py

diff --git a/src/pyfly/config_server/backend.py b/src/pyfly/config_server/backend.py
index d585c439..e0828ef2 100644
--- a/src/pyfly/config_server/backend.py
+++ b/src/pyfly/config_server/backend.py
@@ -53,11 +53,37 @@ class FilesystemConfigBackend:
     """Loads config from ``<root>/<application>-<profile>.{yaml,yml,json}``.
 
     The label maps to a subdirectory: ``<root>/<label>/<application>-<profile>.yaml``.
+
+    **Tiered search locations**
+
+    Pass *search_locations* (a list of directory paths, highest-precedence
+    first) to merge config from multiple directories.  The convention is::
+
+        search_locations=[domain_dir, core_dir, common_dir]
+
+    so the domain layer overrides core which overrides common.  Keys that exist
+    only in a lower-precedence location are inherited (fill-in semantics).
+    ``save()`` and ``list()`` operate on the **first** (primary / highest-
+    precedence) location; the single-root behaviour is unchanged when
+    *search_locations* is ``None``.
     """
 
-    def __init__(self, root: str | pathlib.Path) -> None:
+    def __init__(
+        self,
+        root: str | pathlib.Path,
+        *,
+        search_locations: list[str | pathlib.Path] | None = None,
+    ) -> None:
         self._root = pathlib.Path(root)
         self._root.mkdir(parents=True, exist_ok=True)
+        if search_locations is not None:
+            # The primary location (index 0 = highest precedence) is the caller-
+            # supplied root; remaining locations follow in order.
+            self._locations: list[pathlib.Path] = [pathlib.Path(p) for p in search_locations]
+            for loc in self._locations:
+                loc.mkdir(parents=True, exist_ok=True)
+        else:
+            self._locations = []
 
     def _path_candidates(self, application: str, profile: str, label: str) -> list[pathlib.Path]:
         base = self._root / label if label else self._root
@@ -70,7 +96,55 @@ def _path_candidates(self, application: str, profile: str, label: str) -> list[p
             self._root / f"{application}-{profile}.json",
         ]
 
+    def _path_candidates_for(
+        self, root: pathlib.Path, application: str, profile: str, label: str
+    ) -> list[pathlib.Path]:
+        """Like ``_path_candidates`` but for an arbitrary *root*."""
+        base = root / label if label else root
+        return [
+            base / f"{application}-{profile}.yaml",
+            base / f"{application}-{profile}.yml",
+            base / f"{application}-{profile}.json",
+            root / f"{application}-{profile}.yaml",
+            root / f"{application}-{profile}.yml",
+            root / f"{application}-{profile}.json",
+        ]
+
+    async def _fetch_from_root(
+        self, root: pathlib.Path, application: str, profile: str, label: str
+    ) -> ConfigSource | None:
+        """Attempt to read a single file match from *root*."""
+        for candidate in self._path_candidates_for(root, application, profile, label):
+            if not candidate.exists():
+                continue
+            text = await asyncio.get_event_loop().run_in_executor(None, candidate.read_text)
+            properties = await asyncio.get_event_loop().run_in_executor(
+                None, _parse_text, text, candidate.suffix.lstrip(".")
+            )
+            return ConfigSource(application=application, profile=profile, label=label, properties=properties)
+        return None
+
     async def fetch(self, application: str, profile: str, label: str = "main") -> ConfigSource | None:
+        if self._locations:
+            # Tiered mode: iterate locations from lowest to highest precedence
+            # and accumulate properties, so higher-precedence locations win.
+            merged: dict[str, Any] = {}
+            found = False
+            for loc in reversed(self._locations):
+                source = await self._fetch_from_root(loc, application, profile, label)
+                if source is not None:
+                    merged.update(source.properties)
+                    found = True
+            if not found:
+                return None
+            return ConfigSource(
+                application=application,
+                profile=profile,
+                label=label,
+                properties=merged,
+            )
+
+        # Single-root mode (original behaviour).
         for candidate in self._path_candidates(application, profile, label):
             if not candidate.exists():
                 continue
@@ -84,6 +158,7 @@ async def fetch(self, application: str, profile: str, label: str = "main") -> Co
     async def save(self, source: ConfigSource) -> None:
         import json
 
+        # Always write to _root (the primary / highest-precedence location).
         candidates = self._path_candidates(source.application, source.profile, source.label)
         existing = [c for c in candidates if c.exists()]
 
@@ -113,6 +188,7 @@ async def save(self, source: ConfigSource) -> None:
                 other.unlink(missing_ok=True)
 
     async def list(self) -> list[ConfigSource]:
+        # Always list from _root (the primary location).
         results: list[ConfigSource] = []
         for path in self._root.rglob("*"):
             if not path.is_file() or path.suffix.lstrip(".") not in {"yaml", "yml", "json"}:
diff --git a/tests/config_server/test_tiered_overlay.py b/tests/config_server/test_tiered_overlay.py
new file mode 100644
index 00000000..595e0a83
--- /dev/null
+++ b/tests/config_server/test_tiered_overlay.py
@@ -0,0 +1,154 @@
+# Copyright 2026 Firefly Software Foundation.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Tests for FilesystemConfigBackend tiered search_locations overlay.
+
+Convention: pass locations highest-precedence first, e.g.::
+
+    FilesystemConfigBackend(domain, search_locations=[domain, core, common])
+
+Higher-precedence locations override lower; keys present only in a lower
+location are inherited (fill-in semantics).
+"""
+
+from __future__ import annotations
+
+import pathlib
+
+import pytest
+import yaml
+
+from pyfly.config_server.backend import ConfigSource, FilesystemConfigBackend
+
+
+def _write(directory: pathlib.Path, app: str, profile: str, data: dict) -> None:
+    """Write a YAML config file at <directory>/<app>-<profile>.yaml."""
+    directory.mkdir(parents=True, exist_ok=True)
+    (directory / f"{app}-{profile}.yaml").write_text(yaml.safe_dump(data))
+
+
+@pytest.mark.asyncio
+async def test_domain_overrides_common(tmp_path: pathlib.Path) -> None:
+    """A key present in both domain and common takes the domain value."""
+    common = tmp_path / "common"
+    domain = tmp_path / "domain"
+    _write(common, "orders", "prod", {"host": "common.db", "timeout": 5, "common_only": "yes"})
+    _write(domain, "orders", "prod", {"host": "domain.db", "domain_only": "yes"})
+
+    backend = FilesystemConfigBackend(domain, search_locations=[domain, common])
+    source = await backend.fetch("orders", "prod")
+
+    assert source is not None
+    assert source.properties["host"] == "domain.db", "domain must override common"
+    assert source.properties["timeout"] == 5, "common-only key must be inherited"
+    assert source.properties["common_only"] == "yes", "common-only key must be inherited"
+    assert source.properties["domain_only"] == "yes", "domain-only key must be present"
+
+
+@pytest.mark.asyncio
+async def test_three_tier_override_chain(tmp_path: pathlib.Path) -> None:
+    """Three tiers: domain > core > common."""
+    common = tmp_path / "common"
+    core = tmp_path / "core"
+    domain = tmp_path / "domain"
+
+    _write(common, "svc", "default", {"log_level": "INFO", "timeout": 30, "common_key": "c"})
+    _write(core, "svc", "default", {"log_level": "WARN", "core_key": "k"})
+    _write(domain, "svc", "default", {"log_level": "DEBUG", "domain_key": "d"})
+
+    backend = FilesystemConfigBackend(domain, search_locations=[domain, core, common])
+    source = await backend.fetch("svc", "default")
+
+    assert source is not None
+    # Highest precedence wins.
+    assert source.properties["log_level"] == "DEBUG"
+    # All layers contribute unique keys.
+    assert source.properties["timeout"] == 30
+    assert source.properties["common_key"] == "c"
+    assert source.properties["core_key"] == "k"
+    assert source.properties["domain_key"] == "d"
+
+
+@pytest.mark.asyncio
+async def test_missing_in_all_locations_returns_none(tmp_path: pathlib.Path) -> None:
+    """fetch() returns None when no location has a matching file."""
+    common = tmp_path / "common"
+    domain = tmp_path / "domain"
+    common.mkdir()
+    domain.mkdir()
+
+    backend = FilesystemConfigBackend(domain, search_locations=[domain, common])
+    result = await backend.fetch("missing", "dev")
+    assert result is None
+
+
+@pytest.mark.asyncio
+async def test_partial_presence_only_in_lower(tmp_path: pathlib.Path) -> None:
+    """A file that exists only in a lower-precedence location is still returned."""
+    common = tmp_path / "common"
+    domain = tmp_path / "domain"
+    domain.mkdir()
+    _write(common, "shared", "default", {"base_url": "http://common"})
+
+    backend = FilesystemConfigBackend(domain, search_locations=[domain, common])
+    source = await backend.fetch("shared", "default")
+
+    assert source is not None
+    assert source.properties["base_url"] == "http://common"
+
+
+@pytest.mark.asyncio
+async def test_save_writes_to_primary_location(tmp_path: pathlib.Path) -> None:
+    """save() writes to the primary (first / highest-precedence) location."""
+    common = tmp_path / "common"
+    domain = tmp_path / "domain"
+    common.mkdir()
+    domain.mkdir()
+
+    backend = FilesystemConfigBackend(domain, search_locations=[domain, common])
+    await backend.save(ConfigSource(application="svc", profile="prod", properties={"key": "val"}))
+
+    # File must appear in domain, not common.
+    matches = list(domain.rglob("svc-prod.*"))
+    assert matches, "file should be written to domain (primary) location"
+    common_matches = list(common.rglob("svc-prod.*"))
+    assert not common_matches, "file must NOT be written to common"
+
+
+@pytest.mark.asyncio
+async def test_list_uses_primary_location(tmp_path: pathlib.Path) -> None:
+    """list() only enumerates files in the primary location."""
+    common = tmp_path / "common"
+    domain = tmp_path / "domain"
+    _write(common, "shared", "default", {"x": 1})
+    _write(domain, "orders", "prod", {"y": 2})
+
+    backend = FilesystemConfigBackend(domain, search_locations=[domain, common])
+    sources = await backend.list()
+
+    apps = {s.application for s in sources}
+    assert "orders" in apps
+    # "shared" lives only in common; list() must not return it.
+    assert "shared" not in apps
+
+
+@pytest.mark.asyncio
+async def test_single_root_unchanged(tmp_path: pathlib.Path) -> None:
+    """Existing single-root behaviour is intact when search_locations is None."""
+    _write(tmp_path, "orders", "dev", {"db": "sqlite"})
+
+    backend = FilesystemConfigBackend(tmp_path)
+    source = await backend.fetch("orders", "dev")
+
+    assert source is not None
+    assert source.properties["db"] == "sqlite"

From 7c9d6440a92425771bcb7676eae8bf42f5fe0b69 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s=20Contreras=20Guill=C3=A9n?=
 <ancongui@Andress-MacBook-Pro-2.local>
Date: Wed, 10 Jun 2026 02:07:07 +0200
Subject: [PATCH 4/6] fix(config-server): wire git/tiered backends in
 auto_configuration + fix docs

auto_configuration.py: extracts `_build_backend()` that selects GitConfigBackend
when backend.type=git (gracefully falls back to FS when GitPython absent),
or tiered FilesystemConfigBackend when search-locations is set, or the
original single-root FS backend otherwise.

__init__.py: replaces the over-promising "subclass ConfigBackend to plug in
Git, Consul, etcd, Vault" with an accurate statement: Filesystem and Git
backends ship; implement ConfigBackend for Consul/Vault/etc.  Adds
GitConfigBackend to __all__ via lazy __getattr__ to avoid hard import.

docs/modules/config-server.md: adds GitConfigBackend section, tiered
search-locations section, corrected custom-backend wording, and http_client
injection example for ConfigClient.
---
 docs/modules/config-server.md                 | 114 +++++++++++++++++-
 src/pyfly/config_server/__init__.py           |  25 +++-
 src/pyfly/config_server/auto_configuration.py |  70 ++++++++++-
 3 files changed, 205 insertions(+), 4 deletions(-)

diff --git a/docs/modules/config-server.md b/docs/modules/config-server.md
index 5061099d..52ba6a29 100644
--- a/docs/modules/config-server.md
+++ b/docs/modules/config-server.md
@@ -11,6 +11,11 @@ client services over HTTP.
 1. [Introduction](#introduction)
 2. [ConfigSource](#configsource)
 3. [Backends](#backends)
+   - [InMemoryConfigBackend](#inmemoryconfigbackend)
+   - [FilesystemConfigBackend](#filesystemconfigbackend)
+   - [Tiered search locations](#tiered-search-locations)
+   - [GitConfigBackend](#gitconfigbackend)
+   - [Custom backends](#custom-backends)
 4. [ConfigServer](#configserver)
 5. [ConfigClient](#configclient)
 
@@ -74,6 +79,12 @@ backend = InMemoryConfigBackend()                 # great for tests
 backend = FilesystemConfigBackend("/etc/pyfly")   # reads/writes files
 ```
 
+### InMemoryConfigBackend
+
+Dict-backed, thread-safe via `asyncio.Lock`. Ideal for unit tests.
+
+### FilesystemConfigBackend
+
 **`FilesystemConfigBackend`** stores each bundle as
 `<root>/<label>/<application>-<profile>.{yaml,yml,json}` (falling back to
 `<root>/<application>-<profile>.*` when the labeled file is absent). `fetch()`
@@ -86,9 +97,80 @@ When auto-configured, the backend `root` is **configurable and persistent** via
 so saved config survives restarts. Only when neither is set does it fall back to a
 throwaway tempdir (`config_server/auto_configuration.py`).
 
-Implement `ConfigBackend` to back the server with a database, S3, Git, etc.:
+### Tiered search locations
+
+Pass `search_locations` (a list of directories, **highest-precedence first**) to
+merge config from multiple layers.  The convention is `[domain, core, common]` so
+domain settings override core, which override common; keys present only in a
+lower-precedence location are **inherited** (fill-in semantics).
+
+```python
+backend = FilesystemConfigBackend(
+    domain_dir,
+    search_locations=[domain_dir, core_dir, common_dir],
+)
+```
+
+Configure via YAML (comma-separated or YAML list):
+
+```yaml
+pyfly:
+  config-server:
+    backend:
+      search-locations:
+        - /etc/pyfly/domain
+        - /etc/pyfly/core
+        - /etc/pyfly/common
+```
+
+`save()` and `list()` always operate on the **first** (primary / highest-
+precedence) location.
+
+### GitConfigBackend
+
+A Git-backed backend that clones a repository and delegates file reads to
+`FilesystemConfigBackend` over the working tree.
+
+```python
+from pyfly.config_server.adapters.git import GitConfigBackend
+
+backend = GitConfigBackend(
+    "https://github.com/my-org/config-repo.git",
+    label="main",          # branch / tag / SHA
+    clone_dir="/tmp/cfg",  # optional; defaults to a tempdir
+)
+```
+
+Requires GitPython: `pip install pyfly[config-server-git]`.
+
+**Saving** writes the file into the working tree and commits it locally.
+Pushing to the remote is **out of scope** — call `await backend.refresh()` to
+pull the latest commits from `origin`.
+
+Configure via YAML:
+
+```yaml
+pyfly:
+  config-server:
+    backend:
+      type: git
+      git:
+        uri: "https://github.com/my-org/config-repo.git"
+        label: main
+        clone-dir: /var/lib/pyfly/git-config   # optional
+```
+
+When `backend.type=git` is set but GitPython is not installed, the server logs
+a warning and falls back to `FilesystemConfigBackend`.
+
+### Custom backends
+
+Implement `ConfigBackend` to back the server with Consul, Vault, etcd,
+a database, S3, or any other store:
 
 ```python
+from pyfly.config_server.backend import ConfigBackend, ConfigSource
+
 @runtime_checkable
 class ConfigBackend(Protocol):
     async def fetch(self, application: str, profile: str, label: str = "main") -> ConfigSource | None: ...
@@ -155,6 +237,7 @@ client = ConfigClient(
     label="main",               # optional, defaults to "main"
     username=None,              # optional HTTP basic auth
     password=None,
+    http_client=None,           # optional: inject an httpx.AsyncClient
 )
 properties = await client.fetch()   # flattened {dotted_key: value} dict
 ```
@@ -164,6 +247,35 @@ properties = await client.fetch()   # flattened {dotted_key: value} dict
 in **reverse** order (Spring lists highest priority first) so the highest-priority
 source wins. A non-200 response logs a warning and returns `{}`.
 
+### Transport injection
+
+Pass `http_client` (an `httpx.AsyncClient`) to reuse a connection pool or to
+drive the client against an ASGI app in tests:
+
+```python
+import httpx
+from starlette.applications import Starlette
+
+from pyfly.config_server.adapters.starlette import make_starlette_config_server_routes
+
+app = Starlette(routes=make_starlette_config_server_routes(server))
+
+async with httpx.AsyncClient(
+    transport=httpx.ASGITransport(app=app),
+    base_url="http://config",
+) as http_client:
+    client = ConfigClient(
+        url="http://config",
+        application="orders",
+        profile="prod",
+        http_client=http_client,
+    )
+    props = await client.fetch()
+```
+
+When `http_client` is injected the caller owns its lifecycle — `fetch()` does
+**not** close it.
+
 **Invoked automatically at startup.** You normally do not call `ConfigClient` directly:
 `PyFlyApplication` invokes it during bootstrap when `pyfly.cloud.config.uri` (or
 `pyfly.config.import`) is set, merging the result into the application `Config` as a
diff --git a/src/pyfly/config_server/__init__.py b/src/pyfly/config_server/__init__.py
index c9dad947..c087596a 100644
--- a/src/pyfly/config_server/__init__.py
+++ b/src/pyfly/config_server/__init__.py
@@ -9,8 +9,19 @@
 * **Client side** (``ConfigClient``): fetches config at startup, merges into
   the application's :class:`pyfly.core.Config`.
 
-The default backend is filesystem-based; subclass :class:`ConfigBackend` to
-plug in Git, Consul, etcd, Vault, etc.
+Two backends ship out of the box:
+
+* :class:`~pyfly.config_server.backend.FilesystemConfigBackend` — reads/writes
+  YAML/JSON files under a configurable directory tree; supports tiered
+  search locations (e.g. ``[domain, core, common]``) with higher-precedence
+  locations overriding lower ones.
+* :class:`~pyfly.config_server.adapters.git.GitConfigBackend` — clones a Git
+  repository and delegates file reads to ``FilesystemConfigBackend`` over the
+  working tree.  Requires ``pip install pyfly[config-server-git]``.
+
+To add Consul, Vault, etcd, or any other store, implement
+:class:`~pyfly.config_server.backend.ConfigBackend` (a ``Protocol`` with
+``fetch``, ``save``, and ``list`` methods).
 """
 
 from __future__ import annotations
@@ -30,5 +41,15 @@
     "ConfigServer",
     "ConfigSource",
     "FilesystemConfigBackend",
+    "GitConfigBackend",
     "InMemoryConfigBackend",
 ]
+
+
+def __getattr__(name: str) -> object:
+    if name == "GitConfigBackend":
+        from pyfly.config_server.adapters.git import GitConfigBackend  # noqa: PLC0415
+
+        return GitConfigBackend
+    msg = f"module {__name__!r} has no attribute {name!r}"
+    raise AttributeError(msg)
diff --git a/src/pyfly/config_server/auto_configuration.py b/src/pyfly/config_server/auto_configuration.py
index dc1171e1..1d298b4b 100644
--- a/src/pyfly/config_server/auto_configuration.py
+++ b/src/pyfly/config_server/auto_configuration.py
@@ -4,14 +4,82 @@
 
 from __future__ import annotations
 
+import logging
 import tempfile
+from typing import Any
 
-from pyfly.config_server.backend import FilesystemConfigBackend
+from pyfly.config_server.backend import ConfigBackend, FilesystemConfigBackend
 from pyfly.config_server.server import ConfigServer
 from pyfly.container.bean import bean
 from pyfly.context.conditions import auto_configuration, conditional_on_property
 from pyfly.core.config import Config
 
+_logger = logging.getLogger(__name__)
+
+
+def _build_backend(config: Config) -> ConfigBackend:
+    """Select and construct the appropriate backend from config.
+
+    Decision tree
+    -------------
+    1. ``pyfly.config-server.backend.type == "git"``
+       → :class:`~pyfly.config_server.adapters.git.GitConfigBackend`
+       (requires ``pyfly[config-server-git]``; falls back to filesystem with a
+       warning when GitPython is not installed).
+    2. ``pyfly.config-server.backend.search-locations`` is set
+       → :class:`~pyfly.config_server.backend.FilesystemConfigBackend` with
+       the tiered *search_locations* list (highest-precedence location first;
+       e.g. ``[domain, core, common]``).
+    3. Otherwise
+       → :class:`~pyfly.config_server.backend.FilesystemConfigBackend` with
+       a single *root* taken from ``pyfly.config-server.backend.root`` (or the
+       legacy ``pyfly.config-server.native.search-locations``), falling back to
+       a throwaway tempdir.
+    """
+    backend_type = str(config.get("pyfly.config-server.backend.type") or "").lower()
+
+    if backend_type == "git":
+        git_uri: Any = config.get("pyfly.config-server.backend.git.uri")
+        if git_uri:
+            try:
+                from pyfly.config_server.adapters.git import GitConfigBackend  # noqa: PLC0415
+
+                git_label = str(config.get("pyfly.config-server.backend.git.label") or "main")
+                git_clone_dir: Any = config.get("pyfly.config-server.backend.git.clone-dir")
+                _logger.info("config-server: using GitConfigBackend (uri=%s label=%s)", git_uri, git_label)
+                return GitConfigBackend(
+                    str(git_uri),
+                    label=git_label,
+                    clone_dir=str(git_clone_dir) if git_clone_dir else None,
+                )
+            except ImportError:
+                _logger.warning(
+                    "config-server: backend.type=git requested but GitPython is not installed "
+                    "(pip install pyfly[config-server-git]); falling back to FilesystemConfigBackend"
+                )
+        else:
+            _logger.warning(
+                "config-server: backend.type=git but pyfly.config-server.backend.git.uri is not set; "
+                "falling back to FilesystemConfigBackend"
+            )
+
+    # Tiered multi-location filesystem backend.
+    search_locations_raw: Any = config.get("pyfly.config-server.backend.search-locations")
+    if search_locations_raw:
+        locations: list[str | Any]
+        if isinstance(search_locations_raw, list):
+            locations = [str(loc) for loc in search_locations_raw]
+        else:
+            # Support comma-separated string for YAML scalar values.
+            locations = [loc.strip() for loc in str(search_locations_raw).split(",") if loc.strip()]
+        if locations:
+            _logger.info("config-server: using FilesystemConfigBackend with search-locations=%s", locations)
+            return FilesystemConfigBackend(locations[0], search_locations=locations)
+
+    # Single-root filesystem backend (original behaviour).
+    root = config.get("pyfly.config-server.backend.root") or config.get("pyfly.config-server.native.search-locations")
+    return FilesystemConfigBackend(str(root) if root else tempfile.mkdtemp(prefix="pyfly-config-"))
+
 
 @auto_configuration
 @conditional_on_property("pyfly.config-server.enabled", having_value="true")

From 3e7669dda39093ac13241dbcb6b7cfdc1788672d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s=20Contreras=20Guill=C3=A9n?=
 <ancongui@Andress-MacBook-Pro-2.local>
Date: Wed, 10 Jun 2026 02:20:30 +0200
Subject: [PATCH 5/6] fix(sp12): wire _build_backend into the config_backend
 bean (git/tiered selection now applies); clean up git tempdir + guard
 concurrent clone
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Fix 1: config_backend @bean now calls _build_backend(config) and returns ConfigBackend (Protocol); config_server bean widened to accept ConfigBackend — pyfly.config-server.backend.type=git and backend.search-locations are no longer silently ignored at boot.
- Fix 2: GitConfigBackend registers atexit(shutil.rmtree) when it creates its own tempdir; docstring corrected to recommend explicit clone_dir in production.
- Fix 3: _ensure_repo_async acquires asyncio.Lock before cloning with a double-checked guard so concurrent first-fetch calls cannot both dispatch git-clone to the same directory.
- Fix 4: asyncio.get_event_loop() → asyncio.get_running_loop() in FilesystemConfigBackend._fetch_from_root/fetch/save and GitConfigBackend._run_sync (all run inside coroutines).
- Tests: new tests/config_server/test_backend_selection.py covers _build_backend with backend.type=git (GitConfigBackend + live fetch), search-locations (tiered merge), default single-root, and no-config tempdir fallback; all 38 config_server tests pass.
---
 src/pyfly/config_server/adapters/git.py       |  51 ++++-
 src/pyfly/config_server/auto_configuration.py |  12 +-
 src/pyfly/config_server/backend.py            |  10 +-
 tests/config_server/test_backend_selection.py | 191 ++++++++++++++++++
 4 files changed, 240 insertions(+), 24 deletions(-)
 create mode 100644 tests/config_server/test_backend_selection.py

diff --git a/src/pyfly/config_server/adapters/git.py b/src/pyfly/config_server/adapters/git.py
index b8a7ea48..79dd5ba5 100644
--- a/src/pyfly/config_server/adapters/git.py
+++ b/src/pyfly/config_server/adapters/git.py
@@ -23,8 +23,10 @@
 from __future__ import annotations
 
 import asyncio
+import atexit
 import importlib.util
 import logging
+import shutil
 import tempfile
 from typing import Any
 
@@ -62,7 +64,10 @@ class GitConfigBackend:
         Branch (or tag / SHA) to check out.  Defaults to ``"main"``.
     clone_dir:
         Where to clone the repository.  When *None* a temporary directory is
-        created automatically and cleaned up when the process exits.
+        created automatically and registered with ``atexit`` for cleanup when
+        the process exits.  **In production it is strongly recommended to pass
+        an explicit ``clone_dir``** so the clone persists across restarts and
+        the location can be managed by the operator.
     """
 
     def __init__(
@@ -77,19 +82,22 @@ def __init__(
         self._clone_dir = clone_dir
         self._repo: Any = None  # git.Repo, set on first _ensure_repo() call
         self._fs: FilesystemConfigBackend | None = None
+        # Lock guards the lazy-init path so that two concurrent first-fetches
+        # cannot both attempt to clone into the same directory.
+        self._init_lock = asyncio.Lock()
 
     # ------------------------------------------------------------------
     # Internal helpers
     # ------------------------------------------------------------------
 
-    def _ensure_repo(self) -> FilesystemConfigBackend:
-        """Lazily clone the repo and return (or return the cached) FS backend."""
-        if self._fs is not None:
-            return self._fs
+    def _ensure_repo(self, work_dir: str) -> FilesystemConfigBackend:
+        """Clone the repo into *work_dir* and return the FS backend.
 
+        Must only be called once (the caller holds ``_init_lock`` and checks
+        ``self._fs is None`` before dispatching this to the executor).
+        """
         git = _require_git()
 
-        work_dir = self._clone_dir or tempfile.mkdtemp(prefix="pyfly-git-config-")
         _logger.debug("GitConfigBackend: cloning %s → %s (label=%s)", self._uri, work_dir, self._label)
         self._repo = git.Repo.clone_from(self._uri, work_dir)
         # Checkout the requested label (branch / tag / sha).
@@ -103,13 +111,36 @@ def _ensure_repo(self) -> FilesystemConfigBackend:
 
     async def _run_sync(self, fn: Any, *args: Any) -> Any:
         """Run a synchronous callable in the default executor."""
-        loop = asyncio.get_event_loop()
+        loop = asyncio.get_running_loop()
         return await loop.run_in_executor(None, fn, *args)
 
     async def _ensure_repo_async(self) -> FilesystemConfigBackend:
-        """Async wrapper that returns a typed FilesystemConfigBackend."""
-        result: FilesystemConfigBackend = await self._run_sync(self._ensure_repo)
-        return result
+        """Return the cached FS backend, initialising (cloning) on the first call.
+
+        An ``asyncio.Lock`` guards the init path so that two concurrent first
+        callers cannot both attempt to ``git clone`` into the same directory.
+        The fast-path (already initialised) skips the lock entirely.
+        """
+        # Fast-path: already initialised — no lock needed.
+        if self._fs is not None:
+            return self._fs
+
+        async with self._init_lock:
+            # Re-check after acquiring the lock: a concurrent coroutine may
+            # have completed the clone while we were waiting.
+            if self._fs is not None:
+                return self._fs
+
+            if self._clone_dir:
+                work_dir = self._clone_dir
+            else:
+                work_dir = tempfile.mkdtemp(prefix="pyfly-git-config-")
+                # Register cleanup so the tempdir is removed when the process
+                # exits normally (Fix 2 — prevents tempdir leaks).
+                atexit.register(shutil.rmtree, work_dir, True)
+
+            result: FilesystemConfigBackend = await self._run_sync(self._ensure_repo, work_dir)
+            return result
 
     # ------------------------------------------------------------------
     # ConfigBackend protocol
diff --git a/src/pyfly/config_server/auto_configuration.py b/src/pyfly/config_server/auto_configuration.py
index 1d298b4b..c2b65ab0 100644
--- a/src/pyfly/config_server/auto_configuration.py
+++ b/src/pyfly/config_server/auto_configuration.py
@@ -85,15 +85,9 @@ def _build_backend(config: Config) -> ConfigBackend:
 @conditional_on_property("pyfly.config-server.enabled", having_value="true")
 class ConfigServerAutoConfiguration:
     @bean
-    def config_backend(self, config: Config) -> FilesystemConfigBackend:
-        # Persist under a configured root so saved config survives restarts and an
-        # operator can point the server at a real config directory (audit #88).
-        # Fall back to a throwaway tempdir only when nothing is configured.
-        root = config.get("pyfly.config-server.backend.root") or config.get(
-            "pyfly.config-server.native.search-locations"
-        )
-        return FilesystemConfigBackend(str(root) if root else tempfile.mkdtemp(prefix="pyfly-config-"))
+    def config_backend(self, config: Config) -> ConfigBackend:
+        return _build_backend(config)
 
     @bean
-    def config_server(self, backend: FilesystemConfigBackend) -> ConfigServer:
+    def config_server(self, backend: ConfigBackend) -> ConfigServer:
         return ConfigServer(backend=backend)
diff --git a/src/pyfly/config_server/backend.py b/src/pyfly/config_server/backend.py
index e0828ef2..512fc569 100644
--- a/src/pyfly/config_server/backend.py
+++ b/src/pyfly/config_server/backend.py
@@ -117,8 +117,8 @@ async def _fetch_from_root(
         for candidate in self._path_candidates_for(root, application, profile, label):
             if not candidate.exists():
                 continue
-            text = await asyncio.get_event_loop().run_in_executor(None, candidate.read_text)
-            properties = await asyncio.get_event_loop().run_in_executor(
+            text = await asyncio.get_running_loop().run_in_executor(None, candidate.read_text)
+            properties = await asyncio.get_running_loop().run_in_executor(
                 None, _parse_text, text, candidate.suffix.lstrip(".")
             )
             return ConfigSource(application=application, profile=profile, label=label, properties=properties)
@@ -148,8 +148,8 @@ async def fetch(self, application: str, profile: str, label: str = "main") -> Co
         for candidate in self._path_candidates(application, profile, label):
             if not candidate.exists():
                 continue
-            text = await asyncio.get_event_loop().run_in_executor(None, candidate.read_text)
-            properties = await asyncio.get_event_loop().run_in_executor(
+            text = await asyncio.get_running_loop().run_in_executor(None, candidate.read_text)
+            properties = await asyncio.get_running_loop().run_in_executor(
                 None, _parse_text, text, candidate.suffix.lstrip(".")
             )
             return ConfigSource(application=application, profile=profile, label=label, properties=properties)
@@ -179,7 +179,7 @@ async def save(self, source: ConfigSource) -> None:
             text = json.dumps(source.properties, indent=2)
 
         path.parent.mkdir(parents=True, exist_ok=True)
-        await asyncio.get_event_loop().run_in_executor(None, path.write_text, text)
+        await asyncio.get_running_loop().run_in_executor(None, path.write_text, text)
 
         # Guarantee exactly one file backs this (application, profile, label) so
         # future fetches/saves can't diverge across stale duplicate formats.
diff --git a/tests/config_server/test_backend_selection.py b/tests/config_server/test_backend_selection.py
new file mode 100644
index 00000000..b6aab879
--- /dev/null
+++ b/tests/config_server/test_backend_selection.py
@@ -0,0 +1,191 @@
+# Copyright 2026 Firefly Software Foundation.
+# Licensed under the Apache License, Version 2.0.
+"""Tests for _build_backend() — verifies that auto_configuration wires up the
+correct backend type based on pyfly.config-server.backend.* config keys.
+
+These tests MUST fail against the old dead-code wiring (where config_backend
+always built a single-root FilesystemConfigBackend) and PASS after the fix.
+"""
+
+from __future__ import annotations
+
+import pathlib
+
+import pytest
+import yaml
+
+from pyfly.config_server.auto_configuration import _build_backend
+from pyfly.config_server.backend import ConfigBackend, FilesystemConfigBackend
+from pyfly.core.config import Config
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _cfg(**flat: object) -> Config:
+    """Build a :class:`Config` from flat key→value pairs (dot-keys expanded)."""
+    data: dict[str, object] = {}
+    for k, v in flat.items():
+        parts = k.split(".")
+        node = data
+        for part in parts[:-1]:
+            node = node.setdefault(part, {})  # type: ignore[assignment]
+        node[parts[-1]] = v  # type: ignore[index]
+    return Config(data)  # type: ignore[arg-type]
+
+
+def _make_git_repo(tmp_path: pathlib.Path) -> pathlib.Path:
+    """Create a minimal local git repo with one committed config file.
+
+    Returns the path to the repo root.  Skips automatically when GitPython is
+    not installed — the caller is responsible for calling
+    ``pytest.importorskip("git")`` before invoking this helper.
+    """
+    import git as gitlib  # noqa: PLC0415
+
+    repo_dir = tmp_path / "origin"
+    repo_dir.mkdir()
+    repo = gitlib.Repo.init(repo_dir)
+    repo.config_writer().set_value("user", "name", "Test").release()
+    repo.config_writer().set_value("user", "email", "test@example.com").release()
+
+    cfg_file = repo_dir / "svc-default.yaml"
+    cfg_file.write_text(yaml.safe_dump({"env": "git-backend", "workers": 2}))
+    repo.index.add(["svc-default.yaml"])
+    repo.index.commit("initial config")
+
+    # Ensure the branch is named "main".
+    if repo.active_branch.name != "main":
+        repo.head.reference = repo.create_head("main")
+        repo.head.reset(index=True, working_tree=True)
+
+    return repo_dir
+
+
+# ---------------------------------------------------------------------------
+# Fix 1 test A — backend.type=git → GitConfigBackend
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_build_backend_git_type_produces_git_backend(tmp_path: pathlib.Path) -> None:
+    """_build_backend with backend.type=git returns a GitConfigBackend that reads
+    properties committed in the repository.
+
+    This test would FAIL against the old wiring (which always returned a plain
+    FilesystemConfigBackend) because it verifies that a fetch on the returned
+    backend reads data from a git-cloned working tree.
+    """
+    pytest.importorskip("git")
+
+    origin = _make_git_repo(tmp_path)
+    clone_dir = str(tmp_path / "clone")
+
+    config = _cfg(
+        **{
+            "pyfly.config-server.backend.type": "git",
+            "pyfly.config-server.backend.git.uri": str(origin),
+            "pyfly.config-server.backend.git.label": "main",
+            "pyfly.config-server.backend.git.clone-dir": clone_dir,
+        }
+    )
+
+    backend = _build_backend(config)
+
+    # Must satisfy the ConfigBackend protocol.
+    assert isinstance(backend, ConfigBackend), "returned object does not satisfy ConfigBackend protocol"
+
+    # Must NOT be a plain FilesystemConfigBackend — that would indicate the
+    # old dead-code path is still in effect.
+    from pyfly.config_server.adapters.git import GitConfigBackend  # noqa: PLC0415
+
+    assert isinstance(backend, GitConfigBackend), (
+        f"_build_backend should return GitConfigBackend when backend.type=git, but got {type(backend).__name__}"
+    )
+
+    # Data round-trip: fetch should return properties from the git repo.
+    source = await backend.fetch("svc", "default")
+    assert source is not None, "fetch() returned None — git clone may have failed"
+    assert source.properties.get("env") == "git-backend"
+    assert source.properties.get("workers") == 2
+
+
+# ---------------------------------------------------------------------------
+# Fix 1 test B — backend.search-locations → tiered FilesystemConfigBackend
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_build_backend_search_locations_merges_tiers(tmp_path: pathlib.Path) -> None:
+    """_build_backend with backend.search-locations returns a tiered
+    FilesystemConfigBackend that actually merges properties from multiple
+    directories.
+
+    This test would FAIL against the old wiring because the old code built a
+    single-root backend (ignoring search-locations), so it would miss the
+    keys from the lower-precedence directory.
+    """
+    # Set up two directories: domain (high precedence) and common (low).
+    domain = tmp_path / "domain"
+    common = tmp_path / "common"
+    domain.mkdir()
+    common.mkdir()
+
+    # Write domain config — overrides "host", adds "domain_only".
+    (domain / "app-prod.yaml").write_text(yaml.safe_dump({"host": "domain.db", "domain_only": True}))
+    # Write common config — defines "host" (overridden) and "timeout".
+    (common / "app-prod.yaml").write_text(yaml.safe_dump({"host": "common.db", "timeout": 30}))
+
+    config = _cfg(
+        **{
+            "pyfly.config-server.backend.search-locations": [str(domain), str(common)],
+        }
+    )
+
+    backend = _build_backend(config)
+
+    assert isinstance(backend, FilesystemConfigBackend), (
+        "_build_backend should return FilesystemConfigBackend for search-locations config, "
+        f"but got {type(backend).__name__}"
+    )
+
+    source = await backend.fetch("app", "prod")
+    assert source is not None, "fetch() returned None — check search-locations are accessible"
+
+    # Domain overrides common.
+    assert source.properties["host"] == "domain.db", "domain host must override common"
+    # common-only key is inherited (fill-in semantics).
+    assert source.properties["timeout"] == 30, "timeout key from common must be present"
+    # domain-only key present.
+    assert source.properties["domain_only"] is True
+
+
+# ---------------------------------------------------------------------------
+# Fix 1 test C — default (no type, no search-locations) → single-root FS backend
+# ---------------------------------------------------------------------------
+
+
+def test_build_backend_default_returns_filesystem_backend(tmp_path: pathlib.Path) -> None:
+    """_build_backend with no special keys returns a single-root
+    FilesystemConfigBackend (original behaviour preserved).
+    """
+    root = str(tmp_path / "cfgroot")
+
+    config = _cfg(**{"pyfly.config-server.backend.root": root})
+
+    backend = _build_backend(config)
+
+    assert isinstance(backend, FilesystemConfigBackend), (
+        f"_build_backend default path should return FilesystemConfigBackend, but got {type(backend).__name__}"
+    )
+    # The root directory must have been created.
+    assert pathlib.Path(root).is_dir(), "backend root directory should be created"
+
+
+def test_build_backend_no_config_uses_tempdir() -> None:
+    """_build_backend with completely empty config falls back to a tempdir-rooted
+    FilesystemConfigBackend without raising.
+    """
+    backend = _build_backend(Config())  # type: ignore[arg-type]
+    assert isinstance(backend, FilesystemConfigBackend)

From 27d11f648e63a79812a4a18b83b19e8ddd137134 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s=20Contreras=20Guill=C3=A9n?=
 <ancongui@Andress-MacBook-Pro-2.local>
Date: Wed, 10 Jun 2026 02:23:29 +0200
Subject: [PATCH 6/6] =?UTF-8?q?chore(release):=20v26.06.92=20=E2=80=94=20c?=
 =?UTF-8?q?onfig=20server=20backends=20(SP-12:=20Git=20backend,=20tiered?=
 =?UTF-8?q?=20overlay,=20ConfigClient=20e2e)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 CHANGELOG.md          | 20 ++++++++++++++++++++
 README.md             |  2 +-
 pyproject.toml        |  2 +-
 src/pyfly/__init__.py |  2 +-
 uv.lock               |  2 +-
 5 files changed, 24 insertions(+), 4 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index d1f1ac33..3d98d12c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,26 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ---
 
+## v26.06.92 (2026-06-10)
+
+### Added / Fixed (config server backends — parity initiative SP-12)
+
+- **Git-backed config backend**: `GitConfigBackend` (new `pyfly[config-server-git]` extra, GitPython) clones a
+  config repo (works for local paths too), checks out a label/branch, and serves config from the working tree;
+  `save()` commits locally; all blocking git work runs off the event loop. Selectable via
+  `pyfly.config-server.backend.type=git` (+ `.git.uri`/`.git.label`), with a graceful filesystem fallback when
+  GitPython is absent.
+- **Tiered search-locations overlay**: `FilesystemConfigBackend(root, search_locations=[...])` merges matching
+  config across multiple base directories (a common/core/domain convention — highest precedence first), wired
+  via `pyfly.config-server.backend.search-locations`. Single-root behavior is unchanged.
+- **ConfigClient real e2e test**: `ConfigClient` now accepts an injectable `http_client`, enabling a true
+  round-trip test through `httpx.ASGITransport` → the Starlette config-server routes → backend, asserting the
+  reverse-merge precedence (app+profile overrides application+default; inherited keys survive).
+- **Fixes**: wired the backend-selection logic into the auto-config bean (it was previously dead code, so
+  `backend.type`/`search-locations` were silently ignored); cleaned up the Git clone tempdir (atexit) and
+  guarded concurrent clone with a lock; corrected an over-promising docstring/doc that implied shipped
+  Consul/Vault backends. Docs updated.
+
 ## v26.06.91 (2026-06-10)
 
 ### Added (plugins parity — parity initiative SP-11)
diff --git a/README.md b/README.md
index 7d5ec000..eebf9a0b 100644
--- a/README.md
+++ b/README.md
@@ -11,7 +11,7 @@
   <a href="https://github.com/fireflyframework"><img src="https://img.shields.io/badge/Firefly_Framework-official-ff6600?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZmlsbD0id2hpdGUiIGQ9Ik0xMiAyQzYuNDggMiAyIDYuNDggMiAxMnM0LjQ4IDEwIDEwIDEwIDEwLTQuNDggMTAtMTBTMTcuNTIgMiAxMiAyeiIvPjwvc3ZnPg==" alt="Firefly Framework"></a>
   <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.12%2B-blue?logo=python&logoColor=white" alt="Python 3.12+"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-green" alt="License: Apache 2.0"></a>
-  <a href="#"><img src="https://img.shields.io/badge/version-26.06.91-brightgreen" alt="Version: 26.06.91"></a>
+  <a href="#"><img src="https://img.shields.io/badge/version-26.06.92-brightgreen" alt="Version: 26.06.92"></a>
   <a href="#"><img src="https://img.shields.io/badge/type--checked-mypy%20strict-blue?logo=python&logoColor=white" alt="Type Checked: mypy strict"></a>
   <a href="#"><img src="https://img.shields.io/badge/code%20style-ruff-purple?logo=ruff&logoColor=white" alt="Code Style: Ruff"></a>
   <a href="#"><img src="https://img.shields.io/badge/async-first-brightgreen" alt="Async First"></a>
diff --git a/pyproject.toml b/pyproject.toml
index 9a238105..05cb8ec4 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -7,7 +7,7 @@ name = "pyfly"
 # CalVer YY.MM.PATCH — package metadata uses PEP 440 normalized form (26.5.4);
 # git tag, GitHub release and human-readable display use leading-zero form
 # (v26.05.04) to match the Java/.NET/Go siblings.
-version = "26.6.91"
+version = "26.6.92"
 description = "The official Python implementation of the Firefly Framework — DI, CQRS, EDA, hexagonal architecture, and more."
 readme = "README.md"
 license = "Apache-2.0"
diff --git a/src/pyfly/__init__.py b/src/pyfly/__init__.py
index d10380fd..1690f3b9 100644
--- a/src/pyfly/__init__.py
+++ b/src/pyfly/__init__.py
@@ -13,4 +13,4 @@
 # limitations under the License.
 """PyFly — Enterprise Python Framework."""
 
-__version__ = "26.06.91"
+__version__ = "26.06.92"
diff --git a/uv.lock b/uv.lock
index 1e7296b8..292fbd55 100644
--- a/uv.lock
+++ b/uv.lock
@@ -2160,7 +2160,7 @@ wheels = [
 
 [[package]]
 name = "pyfly"
-version = "26.6.91"
+version = "26.6.92"
 source = { editable = "." }
 dependencies = [
     { name = "pydantic" },