From 042c709dbaa3e765b0eae53dcf408cd67d49b95d Mon Sep 17 00:00:00 2001
From: Bedram Tamang <tmgbedu@gmail.com>
Date: Fri, 10 Jul 2026 12:08:59 -0700
Subject: [PATCH 1/2] Relocate providers/helpers into foundation and support

Move the framework's provider base and app provider out of the top-level
providers/ package and the shared helpers into support/:

- providers/app_provider.py    -> foundation/app_provider.py
- providers/Provider.py        -> support/providers/provider.py
- providers/__init__.py        -> support/providers/__init__.py
- helpers/dataclass.py         -> support/dataclass.py
- remove helpers/app.py
- support/__init__.py now re-exports Provider

Update every import across the framework and tests to the new
locations, including relative-import call sites in configuration,
storage and broadcasting providers.
---
 .../src/fastapi_startkit/ai/providers/ai_provider.py |  2 +-
 fastapi_startkit/src/fastapi_startkit/application.py |  2 +-
 .../src/fastapi_startkit/broadcasting/provider.py    |  2 +-
 .../fastapi_startkit/configuration/Configuration.py  |  2 +-
 .../configuration/providers/ConfigurationProvider.py |  2 +-
 .../fastapi/providers/fastapi_provider.py            |  2 +-
 .../{providers => foundation}/app_provider.py        |  2 +-
 fastapi_startkit/src/fastapi_startkit/helpers/app.py | 12 ------------
 .../src/fastapi_startkit/inertia/provider.py         |  2 +-
 .../logging/providers/log_provider.py                |  2 +-
 .../masoniteorm/providers/DatabaseProvider.py        |  2 +-
 .../fastapi_startkit/mcp/providers/mcp_provider.py   |  2 +-
 .../src/fastapi_startkit/providers/__init__.py       |  3 ---
 .../src/fastapi_startkit/skills/provider.py          |  2 +-
 .../fastapi_startkit/storage/providers/provider.py   |  2 +-
 .../src/fastapi_startkit/support/__init__.py         |  3 ++-
 .../{helpers => support}/dataclass.py                |  0
 .../fastapi_startkit/support/providers/__init__.py   |  3 +++
 .../Provider.py => support/providers/provider.py}    |  5 ++---
 .../src/fastapi_startkit/vite/providers/provider.py  |  2 +-
 fastapi_startkit/tests/ai/test_provider.py           |  2 +-
 fastapi_startkit/tests/core/test_application.py      |  2 +-
 fastapi_startkit/tests/core/test_providers.py        |  2 +-
 fastapi_startkit/tests/mcp/test_mcp_provider.py      |  2 +-
 fastapi_startkit/tests/vite/test_template_binding.py |  2 +-
 25 files changed, 26 insertions(+), 38 deletions(-)
 rename fastapi_startkit/src/fastapi_startkit/{providers => foundation}/app_provider.py (81%)
 delete mode 100644 fastapi_startkit/src/fastapi_startkit/helpers/app.py
 delete mode 100644 fastapi_startkit/src/fastapi_startkit/providers/__init__.py
 rename fastapi_startkit/src/fastapi_startkit/{helpers => support}/dataclass.py (100%)
 create mode 100644 fastapi_startkit/src/fastapi_startkit/support/providers/__init__.py
 rename fastapi_startkit/src/fastapi_startkit/{providers/Provider.py => support/providers/provider.py} (90%)

diff --git a/fastapi_startkit/src/fastapi_startkit/ai/providers/ai_provider.py b/fastapi_startkit/src/fastapi_startkit/ai/providers/ai_provider.py
index 2eee207f..d4bc82bb 100644
--- a/fastapi_startkit/src/fastapi_startkit/ai/providers/ai_provider.py
+++ b/fastapi_startkit/src/fastapi_startkit/ai/providers/ai_provider.py
@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from fastapi_startkit.providers import Provider
+from fastapi_startkit.support import Provider
 
 
 class AIProvider(Provider):
diff --git a/fastapi_startkit/src/fastapi_startkit/application.py b/fastapi_startkit/src/fastapi_startkit/application.py
index 44932dc2..4cd1d14c 100644
--- a/fastapi_startkit/src/fastapi_startkit/application.py
+++ b/fastapi_startkit/src/fastapi_startkit/application.py
@@ -1,6 +1,6 @@
 import os
 import shlex
-from fastapi_startkit.providers.app_provider import AppProvider
+from fastapi_startkit.foundation.app_provider import AppProvider
 from pathlib import Path
 from typing import TYPE_CHECKING, Optional
 from typing import Type, Callable, Any, List, TypeVar, Generic
diff --git a/fastapi_startkit/src/fastapi_startkit/broadcasting/provider.py b/fastapi_startkit/src/fastapi_startkit/broadcasting/provider.py
index 4ae4096e..b72e0a5a 100644
--- a/fastapi_startkit/src/fastapi_startkit/broadcasting/provider.py
+++ b/fastapi_startkit/src/fastapi_startkit/broadcasting/provider.py
@@ -5,7 +5,7 @@
 import sys
 from pathlib import Path
 
-from ..providers import Provider
+from fastapi_startkit.support import Provider
 from .config import BroadcastingConfig
 from .manager import BroadcastManager
 from .reverb.server import ReverbServer
diff --git a/fastapi_startkit/src/fastapi_startkit/configuration/Configuration.py b/fastapi_startkit/src/fastapi_startkit/configuration/Configuration.py
index 849efb39..44fc49cc 100644
--- a/fastapi_startkit/src/fastapi_startkit/configuration/Configuration.py
+++ b/fastapi_startkit/src/fastapi_startkit/configuration/Configuration.py
@@ -51,7 +51,7 @@ def merge_with(self, path, external_config):
         self.set(path, merged_config)
 
     def set(self, path, value):
-        from fastapi_startkit.helpers.dataclass import Dataclass
+        from fastapi_startkit.support.dataclass import Dataclass
 
         self._config[path] = Dataclass.to_dict(value)
 
diff --git a/fastapi_startkit/src/fastapi_startkit/configuration/providers/ConfigurationProvider.py b/fastapi_startkit/src/fastapi_startkit/configuration/providers/ConfigurationProvider.py
index 772a9e11..10cb518a 100644
--- a/fastapi_startkit/src/fastapi_startkit/configuration/providers/ConfigurationProvider.py
+++ b/fastapi_startkit/src/fastapi_startkit/configuration/providers/ConfigurationProvider.py
@@ -1,4 +1,4 @@
-from ...providers import Provider
+from fastapi_startkit.support import Provider
 
 from ..Configuration import Configuration
 
diff --git a/fastapi_startkit/src/fastapi_startkit/fastapi/providers/fastapi_provider.py b/fastapi_startkit/src/fastapi_startkit/fastapi/providers/fastapi_provider.py
index 8639e782..f6e106a7 100644
--- a/fastapi_startkit/src/fastapi_startkit/fastapi/providers/fastapi_provider.py
+++ b/fastapi_startkit/src/fastapi_startkit/fastapi/providers/fastapi_provider.py
@@ -3,7 +3,7 @@
 
 from fastapi_startkit.fastapi.commands import ServeCommand
 from fastapi_startkit.fastapi.config import FastAPIConfig
-from fastapi_startkit.providers import Provider
+from fastapi_startkit.support import Provider
 
 
 class FastAPIProvider(Provider):
diff --git a/fastapi_startkit/src/fastapi_startkit/providers/app_provider.py b/fastapi_startkit/src/fastapi_startkit/foundation/app_provider.py
similarity index 81%
rename from fastapi_startkit/src/fastapi_startkit/providers/app_provider.py
rename to fastapi_startkit/src/fastapi_startkit/foundation/app_provider.py
index f6b984ce..2f43a87f 100644
--- a/fastapi_startkit/src/fastapi_startkit/providers/app_provider.py
+++ b/fastapi_startkit/src/fastapi_startkit/foundation/app_provider.py
@@ -1,5 +1,5 @@
 from fastapi_startkit.console.publish_command import PublishCommand
-from fastapi_startkit.providers import Provider
+from fastapi_startkit.support import Provider
 
 
 class AppProvider(Provider):
diff --git a/fastapi_startkit/src/fastapi_startkit/helpers/app.py b/fastapi_startkit/src/fastapi_startkit/helpers/app.py
deleted file mode 100644
index df9f1ae5..00000000
--- a/fastapi_startkit/src/fastapi_startkit/helpers/app.py
+++ /dev/null
@@ -1,12 +0,0 @@
-def storage_path(path: str = "") -> str:
-    """Get the path to the storage directory."""
-    from fastapi_startkit.application import app
-
-    return app().storage_path(path)
-
-
-def public_path(path: str = "") -> str:
-    """Get the path to the public directory."""
-    from fastapi_startkit.application import app
-
-    return app().public_path(path)
diff --git a/fastapi_startkit/src/fastapi_startkit/inertia/provider.py b/fastapi_startkit/src/fastapi_startkit/inertia/provider.py
index fe2f8b11..92c090a8 100644
--- a/fastapi_startkit/src/fastapi_startkit/inertia/provider.py
+++ b/fastapi_startkit/src/fastapi_startkit/inertia/provider.py
@@ -1,6 +1,6 @@
 import json
 from markupsafe import Markup
-from fastapi_startkit.providers import Provider
+from fastapi_startkit.support import Provider
 from .inertia import Inertia
 from .middleware import InertiaMiddleware
 
diff --git a/fastapi_startkit/src/fastapi_startkit/logging/providers/log_provider.py b/fastapi_startkit/src/fastapi_startkit/logging/providers/log_provider.py
index 338f5039..e65a8838 100644
--- a/fastapi_startkit/src/fastapi_startkit/logging/providers/log_provider.py
+++ b/fastapi_startkit/src/fastapi_startkit/logging/providers/log_provider.py
@@ -1,6 +1,6 @@
 from pathlib import Path
 
-from fastapi_startkit.providers import Provider
+from fastapi_startkit.support import Provider
 from ..ChannelFactory import ChannelFactory
 from ..config.logging import LoggingConfig
 from ..factory import DriverFactory
diff --git a/fastapi_startkit/src/fastapi_startkit/masoniteorm/providers/DatabaseProvider.py b/fastapi_startkit/src/fastapi_startkit/masoniteorm/providers/DatabaseProvider.py
index 9f81a926..9b055cac 100644
--- a/fastapi_startkit/src/fastapi_startkit/masoniteorm/providers/DatabaseProvider.py
+++ b/fastapi_startkit/src/fastapi_startkit/masoniteorm/providers/DatabaseProvider.py
@@ -14,7 +14,7 @@
 from fastapi_startkit.masoniteorm.connections.manager import DatabaseManager
 from fastapi_startkit.masoniteorm import Migrator
 from fastapi_startkit.masoniteorm import Model
-from fastapi_startkit.providers.Provider import Provider
+from fastapi_startkit.support import Provider
 
 
 class DatabaseProvider(Provider):
diff --git a/fastapi_startkit/src/fastapi_startkit/mcp/providers/mcp_provider.py b/fastapi_startkit/src/fastapi_startkit/mcp/providers/mcp_provider.py
index 4ac8fbe4..7bcedfa9 100644
--- a/fastapi_startkit/src/fastapi_startkit/mcp/providers/mcp_provider.py
+++ b/fastapi_startkit/src/fastapi_startkit/mcp/providers/mcp_provider.py
@@ -1,4 +1,4 @@
-from fastapi_startkit.providers import Provider
+from fastapi_startkit.support import Provider
 
 
 class McpProvider(Provider):
diff --git a/fastapi_startkit/src/fastapi_startkit/providers/__init__.py b/fastapi_startkit/src/fastapi_startkit/providers/__init__.py
deleted file mode 100644
index 74248cfd..00000000
--- a/fastapi_startkit/src/fastapi_startkit/providers/__init__.py
+++ /dev/null
@@ -1,3 +0,0 @@
-from .Provider import Provider
-
-__all__ = ["Provider"]
diff --git a/fastapi_startkit/src/fastapi_startkit/skills/provider.py b/fastapi_startkit/src/fastapi_startkit/skills/provider.py
index ab65b604..2934a0ac 100644
--- a/fastapi_startkit/src/fastapi_startkit/skills/provider.py
+++ b/fastapi_startkit/src/fastapi_startkit/skills/provider.py
@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from fastapi_startkit.providers import Provider
+from fastapi_startkit.support import Provider
 
 
 class AISkillProvider(Provider):
diff --git a/fastapi_startkit/src/fastapi_startkit/storage/providers/provider.py b/fastapi_startkit/src/fastapi_startkit/storage/providers/provider.py
index 694e620a..28e4c949 100644
--- a/fastapi_startkit/src/fastapi_startkit/storage/providers/provider.py
+++ b/fastapi_startkit/src/fastapi_startkit/storage/providers/provider.py
@@ -1,5 +1,5 @@
 from pathlib import Path
-from ...providers import Provider
+from fastapi_startkit.support import Provider
 from ..storage import StorageManager
 from ...configuration import config
 from ..drivers import LocalDriver, S3Driver
diff --git a/fastapi_startkit/src/fastapi_startkit/support/__init__.py b/fastapi_startkit/src/fastapi_startkit/support/__init__.py
index 683a7c08..817078af 100644
--- a/fastapi_startkit/src/fastapi_startkit/support/__init__.py
+++ b/fastapi_startkit/src/fastapi_startkit/support/__init__.py
@@ -1,5 +1,6 @@
 from .collection import Collection, collect
 from .string import Str, Stringable
 from .uri import Uri, Uriable
+from fastapi_startkit.support.providers import Provider
 
-__all__ = ["Collection", "collect", "Str", "Stringable", "Uri", "Uriable"]
+__all__ = ["Collection", "collect", "Str", "Stringable", "Uri", "Uriable", "Provider"]
diff --git a/fastapi_startkit/src/fastapi_startkit/helpers/dataclass.py b/fastapi_startkit/src/fastapi_startkit/support/dataclass.py
similarity index 100%
rename from fastapi_startkit/src/fastapi_startkit/helpers/dataclass.py
rename to fastapi_startkit/src/fastapi_startkit/support/dataclass.py
diff --git a/fastapi_startkit/src/fastapi_startkit/support/providers/__init__.py b/fastapi_startkit/src/fastapi_startkit/support/providers/__init__.py
new file mode 100644
index 00000000..9e18bc21
--- /dev/null
+++ b/fastapi_startkit/src/fastapi_startkit/support/providers/__init__.py
@@ -0,0 +1,3 @@
+from fastapi_startkit.support.providers.provider import Provider
+
+__all__ = ["Provider"]
diff --git a/fastapi_startkit/src/fastapi_startkit/providers/Provider.py b/fastapi_startkit/src/fastapi_startkit/support/providers/provider.py
similarity index 90%
rename from fastapi_startkit/src/fastapi_startkit/providers/Provider.py
rename to fastapi_startkit/src/fastapi_startkit/support/providers/provider.py
index d2e6a831..e980abfc 100644
--- a/fastapi_startkit/src/fastapi_startkit/providers/Provider.py
+++ b/fastapi_startkit/src/fastapi_startkit/support/providers/provider.py
@@ -1,11 +1,10 @@
 from typing import TYPE_CHECKING
 
 from fastapi_startkit.support import Str
-
-from fastapi_startkit.helpers.dataclass import Dataclass
+from fastapi_startkit.support.dataclass import Dataclass
 
 if TYPE_CHECKING:
-    from ..application import Application
+    from fastapi_startkit.application import Application
 
 
 class Provider:
diff --git a/fastapi_startkit/src/fastapi_startkit/vite/providers/provider.py b/fastapi_startkit/src/fastapi_startkit/vite/providers/provider.py
index cf56b890..c4630694 100644
--- a/fastapi_startkit/src/fastapi_startkit/vite/providers/provider.py
+++ b/fastapi_startkit/src/fastapi_startkit/vite/providers/provider.py
@@ -1,7 +1,7 @@
 import os
 
 
-from fastapi_startkit.providers import Provider
+from fastapi_startkit.support import Provider
 from ..config.vite import ViteConfig
 
 from ..vite import Vite
diff --git a/fastapi_startkit/tests/ai/test_provider.py b/fastapi_startkit/tests/ai/test_provider.py
index 3f050763..af238f74 100644
--- a/fastapi_startkit/tests/ai/test_provider.py
+++ b/fastapi_startkit/tests/ai/test_provider.py
@@ -5,7 +5,7 @@
 
 from fastapi_startkit.ai import AIConfig
 from fastapi_startkit.ai.providers.ai_provider import AIProvider
-from fastapi_startkit.providers import Provider
+from fastapi_startkit.support import Provider
 
 
 class TestAIProvider(unittest.TestCase):
diff --git a/fastapi_startkit/tests/core/test_application.py b/fastapi_startkit/tests/core/test_application.py
index c0544146..efc2223a 100644
--- a/fastapi_startkit/tests/core/test_application.py
+++ b/fastapi_startkit/tests/core/test_application.py
@@ -6,7 +6,7 @@
 
 from fastapi_startkit.application import Application
 from fastapi_startkit.container.container import Container
-from fastapi_startkit.providers import Provider
+from fastapi_startkit.support import Provider
 
 
 # ---------------------------------------------------------------------------
diff --git a/fastapi_startkit/tests/core/test_providers.py b/fastapi_startkit/tests/core/test_providers.py
index 98047fd5..68cfbfa5 100644
--- a/fastapi_startkit/tests/core/test_providers.py
+++ b/fastapi_startkit/tests/core/test_providers.py
@@ -4,7 +4,7 @@
 
 from fastapi_startkit.application import Application
 from fastapi_startkit.container.container import Container
-from fastapi_startkit.providers import Provider
+from fastapi_startkit.support import Provider
 
 
 # ---------------------------------------------------------------------------
diff --git a/fastapi_startkit/tests/mcp/test_mcp_provider.py b/fastapi_startkit/tests/mcp/test_mcp_provider.py
index af870b3f..79495006 100644
--- a/fastapi_startkit/tests/mcp/test_mcp_provider.py
+++ b/fastapi_startkit/tests/mcp/test_mcp_provider.py
@@ -1,7 +1,7 @@
 """Tests for McpProvider."""
 
 from fastapi_startkit.mcp import McpProvider
-from fastapi_startkit.providers import Provider
+from fastapi_startkit.support import Provider
 
 
 def test_mcp_provider_is_a_provider():
diff --git a/fastapi_startkit/tests/vite/test_template_binding.py b/fastapi_startkit/tests/vite/test_template_binding.py
index 20060339..a7425951 100644
--- a/fastapi_startkit/tests/vite/test_template_binding.py
+++ b/fastapi_startkit/tests/vite/test_template_binding.py
@@ -4,7 +4,7 @@
 import pytest
 
 from fastapi_startkit.application import Application
-from fastapi_startkit.providers import Provider
+from fastapi_startkit.support import Provider
 from fastapi_startkit.vite import ViteProvider
 from fastapi_startkit.vite.config.vite import ViteConfig
 

From d2b29f056541b814d91279c35ed15d2611ce5ff4 Mon Sep 17 00:00:00 2001
From: Bedram Tamang <tmgbedu@gmail.com>
Date: Fri, 10 Jul 2026 12:23:17 -0700
Subject: [PATCH 2/2] Fix example apps importing removed
 fastapi_startkit.providers

Point the console providers in example/console-app and example/database-app
at the new fastapi_startkit.support.Provider location so the example test
suites stop failing with ModuleNotFoundError.

Since the old fastapi_startkit.providers path is removed with no compat
shim, bump the framework minor version (0.47.0 -> 0.48.0) and document
the breaking import changes in a new CHANGELOG.
---
 example/console-app/providers/console.py        |  2 +-
 .../database-app/providers/console_provider.py  |  2 +-
 fastapi_startkit/CHANGELOG.md                   | 17 +++++++++++++++++
 fastapi_startkit/pyproject.toml                 |  2 +-
 4 files changed, 20 insertions(+), 3 deletions(-)
 create mode 100644 fastapi_startkit/CHANGELOG.md

diff --git a/example/console-app/providers/console.py b/example/console-app/providers/console.py
index c7187755..b4d9c057 100644
--- a/example/console-app/providers/console.py
+++ b/example/console-app/providers/console.py
@@ -1,5 +1,5 @@
 from commands.example_command import ExampleCommand
-from fastapi_startkit.providers import Provider
+from fastapi_startkit.support import Provider
 
 
 class ConsoleServiceProvider(Provider):
diff --git a/example/database-app/providers/console_provider.py b/example/database-app/providers/console_provider.py
index 160a20bc..f0683c95 100644
--- a/example/database-app/providers/console_provider.py
+++ b/example/database-app/providers/console_provider.py
@@ -1,4 +1,4 @@
-from fastapi_startkit.providers import Provider
+from fastapi_startkit.support import Provider
 
 class ConsoleProvider(Provider):
     def register(self) -> None:
diff --git a/fastapi_startkit/CHANGELOG.md b/fastapi_startkit/CHANGELOG.md
new file mode 100644
index 00000000..25551653
--- /dev/null
+++ b/fastapi_startkit/CHANGELOG.md
@@ -0,0 +1,17 @@
+# Changelog
+
+## 0.48.0
+
+### Breaking changes
+
+The top-level `fastapi_startkit.providers` package has been removed. Its
+contents moved into `foundation` and `support`, and there is **no**
+backward-compatibility shim — consumers must update their imports:
+
+| Old import | New import |
+|---|---|
+| `from fastapi_startkit.providers import Provider` | `from fastapi_startkit.support import Provider` |
+| `from fastapi_startkit.providers.app_provider import ...` | `from fastapi_startkit.foundation.app_provider import ...` |
+| `from fastapi_startkit.helpers.dataclass import ...` | `from fastapi_startkit.support.dataclass import ...` |
+
+`fastapi_startkit.helpers.app` has been removed.
diff --git a/fastapi_startkit/pyproject.toml b/fastapi_startkit/pyproject.toml
index fa6a8589..dd882fcc 100644
--- a/fastapi_startkit/pyproject.toml
+++ b/fastapi_startkit/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "fastapi-startkit"
-version = "0.47.0"
+version = "0.48.0"
 description = "A modular, provider-driven framework for building async Python web applications with FastAPI — bundling a service container, configuration system, an async-first ORM, facades, and a Cleo-powered console."
 keywords = [
     "fastapi",