docs: reorganize documentation structure and update links for clarity

Author: HosseinNejatiJavaremi

docs/404.md

@@ -12,12 +12,12 @@ It may have been moved, renamed, or deleted.
 ## Find What You Need
 
 - [Get Started](index.md) — overview and quick example
-- [Installation](installation.md) — install ArchiPy and optional extras
+- [Installation](getting-started/installation.md) — install ArchiPy and optional extras
 - [Quickstart](getting-started/quickstart.md) — five-minute step-by-step guide
 - [Concepts](getting-started/concepts.md) — Clean Architecture layers and import rules
-- [Tutorials](examples/index.md) — guides for every adapter and helper
+- [Tutorials](tutorials/index.md) — guides for every adapter and helper
 - [API Reference](api_reference/index.md) — full reference for all public classes
-- [FAQ](faq.md) — frequently asked questions
+- [FAQ](community/faq.md) — frequently asked questions
 
 !!! tip "Search the docs"
 Use the search bar at the top of the page to find any topic instantly.

docs/api_reference/configs.md

@@ -52,7 +52,7 @@ members_order: alphabetical
 
 ## Config Templates {#config-templates}
 
-For practical examples, see the [Configuration Management Guide](../examples/config_management.md).
+For practical examples, see the [Configuration Management Guide](../tutorials/config_management.md).
 
 ### Database Configs
 

docs/api_reference/index.md

@@ -99,12 +99,12 @@ ArchiPy follows semantic versioning and marks API stability as follows:
 - 🟡 **Beta**: APIs that are stabilizing but may have breaking changes
 - 🔴 **Alpha**: Experimental APIs that may change significantly
 
-See the [Changelog](../changelog.md) for version history and breaking changes.
+See the [Changelog](../community/changelog.md) for version history and breaking changes.
 
 ## Contributing
 
 For information about contributing to ArchiPy's development, please see:
 
-- [Contributing Guide](../contributing.md)
-- [Development Guide](../contributing.md)
+- [Contributing Guide](../community/contributing.md)
+- [Development Guide](../community/contributing.md)
 - [Documentation Guide](../contributing-docs.md)

docs/changelog.md docs/community/changelog.mddocs/changelog.md renamed to docs/community/changelog.md

@@ -224,7 +224,7 @@ New adapters follow a consistent checklist. Use this as your guide when contribu
    real-service scenarios.
 
 7. **Document the adapter** — create both:
-    - `docs/examples/adapters/<name>.md` — example guide (5 required sections)
+    - `docs/tutorials/adapters/<name>.md` — example guide (5 required sections)
     - `docs/api_reference/adapters/<name>.md` — API reference with mkdocstrings
 
 8. **Update `mkdocs.yml`** — add both new pages under the appropriate `nav:` keys.
@@ -251,7 +251,7 @@ This section outlines the standards and practices for ArchiPy documentation.
 - `docs/` - Markdown documentation files
     - `index.md` - Get Started page
     - `api_reference/` - API documentation
-    - `examples/` - Usage examples
+    - `tutorials/` - Usage examples
     - `assets/` - Images and other static assets
 
 ### Format and Style

docs/CODE_OF_CONDUCT.md docs/community/code_of_conduct.mddocs/CODE_OF_CONDUCT.md renamed to docs/community/code_of_conduct.md

@@ -128,7 +128,7 @@ uv add "archipy[redis]"
 uv add "archipy[postgres,sqlalchemy]"
 ```
 
-See the [Installation](installation.md) page for the full extras table.
+See the [Installation](../getting-started/installation.md) page for the full extras table.
 
 ### What is the `mocks.py` file in adapters?
 
@@ -160,7 +160,7 @@ uv add "archipy[fakeredis]"     # in-memory Redis for tests
 uv add "archipy[testcontainers]" # Docker-backed real DBs for integration tests
 ```
 
-See the [Testing Strategy](examples/testing_strategy.md) guide for full patterns.
+See the [Testing Strategy](../tutorials/testing_strategy.md) guide for full patterns.
 
 ### How do I run BDD tests?
 
@@ -174,7 +174,7 @@ Or target a single feature file:
 uv run behave features/my_feature.feature
 ```
 
-See the [BDD Testing](examples/testing_strategy.md) guide for Gherkin syntax and step definitions.
+See the [BDD Testing](../tutorials/testing_strategy.md) guide for Gherkin syntax and step definitions.
 
 ### What is the difference between unit tests and integration tests in ArchiPy?
 
@@ -253,7 +253,7 @@ class AppConfig(BaseConfig):
 | `@timing`     | `helpers.decorators.timing`               | Execution time logging          |
 | `@deprecated` | `helpers.decorators.deprecation_warnings` | Deprecation warning             |
 
-See the [Decorators tutorial](examples/helpers/decorators.md) for examples.
+See the [Decorators tutorial](../tutorials/helpers/decorators.md) for examples.
 
 ### What is the difference between `@singleton` decorator and `SingletonMeta` metaclass?
 
@@ -267,8 +267,8 @@ Both enforce the singleton pattern but suit different use cases:
 
 ## See Also
 
-- [Concepts](getting-started/concepts.md) — Clean Architecture layers and import rules
-- [Installation](installation.md) — optional extras and prerequisites
-- [Testing Strategy](examples/testing_strategy.md) — unit, integration, and BDD test patterns
-- [Configuration Management](examples/config_management.md) — environment variables, `.env` files, nested config
-- [Error Handling](examples/error_handling.md) — domain exceptions and chaining
+- [Concepts](../getting-started/concepts.md) — Clean Architecture layers and import rules
+- [Installation](../getting-started/installation.md) — optional extras and prerequisites
+- [Testing Strategy](../tutorials/testing_strategy.md) — unit, integration, and BDD test patterns
+- [Configuration Management](../tutorials/config_management.md) — environment variables, `.env` files, nested config
+- [Error Handling](../tutorials/error_handling.md) — domain exceptions and chaining

docs/contributing.md docs/community/contributing.mddocs/contributing.md renamed to docs/community/contributing.md

@@ -145,7 +145,7 @@ is_valid = PasswordUtils.verify_password(plain_password, hashed)
 
 ## See Also
 
-- [Configuration Management](examples/config_management.md) — environment variables and secrets management
-- [JWT Utilities](examples/helpers/utils.md) — encoding and decoding JSON Web Tokens
-- [Installation](installation.md) — optional extras and dependencies
+- [Configuration Management](../tutorials/config_management.md) — environment variables and secrets management
+- [JWT Utilities](../tutorials/helpers/utils.md) — encoding and decoding JSON Web Tokens
+- [Installation](../getting-started/installation.md) — optional extras and dependencies
 - [Contributing](contributing.md) — responsible disclosure and code review process

docs/faq.md docs/community/faq.mddocs/faq.md renamed to docs/community/faq.md

@@ -726,7 +726,7 @@ python manage.py run --port 9000 --reload
 
 - [Concepts](concepts.md) — four-layer architecture and import rules
 - [Project Structure](project_structure.md) — reference folder layout
-- [Dependency Injection](../examples/dependency_injection.md) — DI container patterns in depth
-- [Configuration Management](../examples/config_management.md) — environment variables and `.env` files
-- [Error Handling](../examples/error_handling.md) — custom errors and HTTP mapping
-- [Testing Strategy](../examples/testing_strategy.md) — BDD testing with mock adapters
+- [Dependency Injection](../tutorials/dependency_injection.md) — DI container patterns in depth
+- [Configuration Management](../tutorials/config_management.md) — environment variables and `.env` files
+- [Error Handling](../tutorials/error_handling.md) — custom errors and HTTP mapping
+- [Testing Strategy](../tutorials/testing_strategy.md) — BDD testing with mock adapters