docs: update complete user example and quickstart documentation for manage.py integration

- Replace references from `main.py` to `manage.py` as the CLI entry point.
- Enhance configuration setup by introducing `customize()` method for service-specific defaults.
- Update project layout to reflect the new structure and clarify the organization of files.
- Add command options for running the application in the quickstart guide.

Author: HosseinNejatiJavaremi

docs/getting-started/complete_user_example.md

@@ -6,38 +6,48 @@ description: End-to-end ArchiPy application — entities, DTOs, adapters, reposi
 # Complete User Example
 
 This page walks through every layer of a real ArchiPy application for a **User** domain, from the database
-entity all the way to the FastAPI endpoint and `main.py`. Each section corresponds to one layer in the
+entity all the way to the FastAPI endpoint and `manage.py`. Each section corresponds to one layer in the
 [four-layer architecture](../getting-started/concepts.md).
 
 ---
 
 ## Project Layout
 
 ```
-my_app/
-├── configs/
-│   ├── app_config.py
-│   └── containers.py
-├── models/
-│   ├── dtos/
+project-root/
+├── my_app/
+│   ├── configs/
+│   │   ├── app_config.py
+│   │   └── containers.py
+│   ├── models/
+│   │   ├── dtos/
+│   │   │   └── user/
+│   │   │       ├── domain/v1/user_dtos.py      # versioned — cross service boundary
+│   │   │       └── repository/user_dtos.py     # internal — never versioned
+│   │   ├── entities/user.py
+│   │   └── errors/user_errors.py
+│   ├── repositories/
 │   │   └── user/
-│   │       ├── domain/v1/user_dtos.py      # versioned — cross service boundary
-│   │       └── repository/user_dtos.py     # internal — never versioned
-│   ├── entities/user.py
-│   └── errors/user_errors.py
-├── repositories/
-│   └── user/
-│       ├── adapters/
-│       │   ├── user_db_adapter.py
-│       │   └── user_cache_adapter.py
-│       └── user_repository.py
-├── logics/
-│   └── user/
-│       ├── user_registration_logic.py
-│       └── user_query_logic.py
-├── services/
-│   └── user/v1/user_service.py
-└── main.py
+│   │       ├── adapters/
+│   │       │   ├── user_db_adapter.py
+│   │       │   └── user_cache_adapter.py
+│   │       └── user_repository.py
+│   ├── logics/
+│   │   └── user/
+│   │       ├── user_registration_logic.py
+│   │       └── user_query_logic.py
+│   └── services/
+│       └── user/v1/user_service.py
+│
+├── features/                           # BDD acceptance tests (behave)
+│   ├── user_registration.feature
+│   ├── steps/
+│   │   └── user_steps.py
+│   ├── scenario_context.py
+│   ├── scenario_context_pool_manager.py
+│   └── environment.py
+│
+└── manage.py                           # CLI entry point — click commands
 ```
 
 ---
@@ -47,17 +57,23 @@ my_app/
 ```python
 # configs/app_config.py
 from archipy.configs.base_config import BaseConfig
+from archipy.configs.environment_type import EnvironmentType
 
 
 class AppConfig(BaseConfig):
     """Application-specific configuration.
 
     All ArchiPy sections (REDIS, POSTGRES, FASTAPI, …) are inherited from BaseConfig.
-    Add custom fields below.
+    Override `customize` to apply app-specific defaults after loading.
     """
 
-    APP_NAME: str = "my-service"
-    DEBUG: bool = False
+    def customize(self) -> None:
+        """Apply app-specific configuration overrides."""
+        super().customize()
+        self.FASTAPI.PROJECT_NAME = "my-service"
+        self.FASTAPI.SERVE_HOST = "0.0.0.0"  # noqa: S104
+        self.FASTAPI.SERVE_PORT = 8000
+        self.FASTAPI.RELOAD = self.ENVIRONMENT == EnvironmentType.LOCAL
 
 
 config = AppConfig()
@@ -653,27 +669,55 @@ def create_router(container: UserContainer) -> APIRouter:
 
 ---
 
-## Entry Point
+## Entry Point: `manage.py`
 
 ```python
-# main.py
-from archipy.helpers.utils.app_utils import AppUtils
+# manage.py
+import click
+import uvicorn
 
-import configs.app_config  # noqa: F401 — importing triggers BaseConfig.set_global
+import configs.app_config  # noqa: F401 — triggers BaseConfig.set_global
+from archipy.configs.base_config import BaseConfig
+from archipy.helpers.utils.app_utils import AppUtils
 from configs.containers import UserContainer
 from services.user.v1.user_service import create_router as create_user_v1_router
 
-user_container = UserContainer()
 
-app = AppUtils.create_fastapi_app()
-app.include_router(create_user_v1_router(user_container))
+def create_app():
+    """Create and configure the FastAPI application."""
+    user_container = UserContainer()
+    app = AppUtils.create_fastapi_app()
+    app.include_router(create_user_v1_router(user_container))
+    return app
 
-if __name__ == "__main__":
-    import uvicorn
-    from archipy.configs.base_config import BaseConfig
 
+@click.group()
+def cli():
+    """Management commands for my_app."""
+
+
+@cli.command()
+@click.option("--host", default=None, show_default=True, help="Bind host (defaults to FAST_API.SERVE_HOST).")
+@click.option("--port", default=None, type=int, show_default=True, help="Bind port (defaults to FAST_API.SERVE_PORT).")
+@click.option("--reload/--no-reload", default=None, help="Enable auto-reload (defaults to FAST_API.RELOAD).")
+def run(host: str | None, port: int | None, reload: bool | None) -> None:
+    """Start the FastAPI development server."""
     config = BaseConfig.global_config()
-    uvicorn.run(app, host="0.0.0.0", port=8000)  # noqa: S104
+    serve_host = host or config.FAST_API.SERVE_HOST
+    serve_port = port or config.FAST_API.SERVE_PORT
+    serve_reload = config.FAST_API.RELOAD if reload is None else reload
+    uvicorn.run("manage:create_app", factory=True, host=serve_host, port=serve_port, reload=serve_reload)
+
+
+if __name__ == "__main__":
+    cli()
+```
+
+Run the server with:
+
+```bash
+python manage.py run
+python manage.py run --port 9000 --reload
 ```
 
 ---

docs/getting-started/quickstart.md

@@ -34,12 +34,14 @@ uv add "archipy[redis,cache]"
 
 ## Step 3 — Define the Configuration
 
-Create a configuration class that extends `BaseConfig`. Add only the fields your service needs:
+Create a configuration class that extends `BaseConfig`. Override `customize()` to apply service-specific defaults after all sources are loaded:
 
 ```python
 # configs/app_config.py
 import logging
+
 from archipy.configs.base_config import BaseConfig
+from archipy.configs.environment_type import EnvironmentType
 
 logger = logging.getLogger(__name__)
 
@@ -48,11 +50,14 @@ class AppConfig(BaseConfig):
     """Service-level configuration.
 
     All ArchiPy config sections (REDIS, FASTAPI, etc.) are inherited.
-    Add custom fields below.
+    Override `customize` to set service-specific defaults.
     """
 
-    APP_NAME: str = "my-service"
-    DEBUG: bool = False
+    def customize(self) -> None:
+        """Apply service-specific configuration overrides."""
+        super().customize()
+        self.FASTAPI.PROJECT_NAME = "my-service"
+        self.FASTAPI.RELOAD = self.ENVIRONMENT == EnvironmentType.LOCAL
 
 
 config = AppConfig()
@@ -111,21 +116,36 @@ name = get_user_name("42")
 ## Step 6 — Run the App
 
 ```python
-# main.py
+# manage.py
 import logging
+
+import click
+
 import configs.app_config  # noqa: F401 — triggers BaseConfig.set_global
 from logics.user_logic import get_user_name
 
 logging.basicConfig(level="INFO")
 logger = logging.getLogger(__name__)
 
-if __name__ == "__main__":
+
+@click.group()
+def cli():
+    """Management commands for my_service."""
+
+
+@cli.command()
+def run() -> None:
+    """Run a quick cache demonstration."""
     logger.info(get_user_name("42"))
     logger.info(get_user_name("42"))  # returns from cache
+
+
+if __name__ == "__main__":
+    cli()
 ```
 
 ```bash
-uv run main.py
+python manage.py run
 ```
 
 You should see: