django-abstract 0.1.0__tar.gz

django_abstract-0.1.0/.github/FUNDING.yml

@@ -0,0 +1,15 @@
+# These are supported funding model platforms
+
+github: 'MojahiD-0-YouneSS' # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
+patreon: # Replace with a single Patreon username
+open_collective: # Replace with a single Open Collective username
+ko_fi: # Replace with a single Ko-fi username
+tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+liberapay: # Replace with a single Liberapay username
+issuehunt: # Replace with a single IssueHunt username
+lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
+polar: # Replace with a single Polar username
+buy_me_a_coffee: # Replace with a single Buy Me a Coffee username
+thanks_dev: # Replace with a single thanks.dev username
+custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']

django_abstract-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 YOUNESS MOJAHID
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

django_abstract-0.1.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include LICENSE
+include README.md
+recursive-include src/django_abstract/templates *
+recursive-include src/django_abstract/static *
+recursive-include src/django_abstract/migrations *

django_abstract-0.1.0/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: django-abstract
+Version: 0.1.0
+Summary: A django app, that ofers abstracted logic for Django.
+Author-email: Youness Mojahid <mojahidyouness0@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2025 YOUNESS MOJAHID
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Framework :: Django :: 6.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: django>=5.2
+Description-Content-Type: text/markdown
+
+<div align="center">
+  <h1>🛡️ Django Abstract</h1>
+  <p><strong>An Enterprise-Grade Architectural Layer for Django</strong></p>
+  <p>Clean Architecture | Dependency Injection | CQRS Principles | Domain-Driven Design</p>
+</div>
+
+---
+
+## 📖 Overview
+
+**Django Abstract** is a highly advanced framework built on top of Django that strictly enforces **Clean Architecture** and **Domain-Driven Design (DDD)**. It solves the infamous "Fat Model / Fat View" anti-pattern by completely decoupling:
+
+1. **Data Access** (`Selectors` / `Creators`)
+2. **Business Logic** (`Services`)
+3. **Flow Control & Permissions** (`Operators` / `Systems`)
+
+This framework provides a unified, predictable way to scale complex Django applications, manage high-throughput operations via Redis queues, and dynamically inject dependencies.
+
+## 🚀 Key Features
+
+### 🧩 Global Registry & Dependency Injection
+- Dynamically registers all architectural components using decorators (`@creator_selector`, `@register_service`, `@register_operator`).
+- Injects `BaseDependency` instances at runtime to prevent circular imports and allow test mocking.
+- Magic attribute resolution (`__getattr__`) allows developers to resolve dependencies seamlessly (`dependency.select_user`).
+
+### 🏛️ Strict Architectural Separation
+- **`BaseModel`**: Adds soft-delete, active toggles, and rich audit trails natively.
+- **`BaseSelector` / `BaseCreator`**: Isolates raw Django ORM calls from business logic.
+- **`BaseService`**: Pure business logic that operates exclusively on an abstract `ServiceEntryData` state.
+- **`BaseSystem`**: Orchestrates workflows and manages global database transactions (`transaction.atomic()`).
+
+### ⚡ High-Throughput Background Logging
+- Includes a robust `log/` app that tracks `SystemErrorLog`, `SessionMetrics`, and `AdminActionLog`.
+- Uses a **Redis-backed queueing system** within `ModelServices` to buffer high-frequency inserts and bulk-flush (`bulk_create`) them to PostgreSQL, completely preventing database locking during traffic spikes.
+
+### 🔌 Seamless View Binding
+- Replaces traditional Django Views with `EntryBindingMixin`.
+- Automatically extracts `session_key`, `ip_address`, and POST/GET payloads, hydrates a master `Entry` object, and passes it directly to the orchestration `Systems`.
+
+## 📁 Repository Structure
+
+```text
+src/django_abstract/
+├── base/        # Core architectural base classes
+├── generic/     # Generic, reusable creation/selection patterns
+├── log/         # High-performance asynchronous auditing system
+├── registry.py  # Global Dependency Injection container
+└── utilities.py # Context extraction, View Mixins, State Objects
+```
+
+## 📚 Documentation
+Comprehensive documentation for every module can be found in the `docs/` folder:
+- [Base Architecture Overview](docs/django_abstract/base)
+- [Generic Utilities](docs/django_abstract/generic)
+- [High-Performance Logging](docs/django_abstract/log)
+
+## 🧪 Testing
+The repository is fully testable. Due to strict dependency injection, any `Selector` or `Creator` can be swapped out with a mock class during tests. Test stubs for all modules are located in the `tests/` directory.
+
+## 👨‍💻 Author
+Designed and implemented as an enterprise architectural study to showcase advanced systems design, Python metaprogramming, and scalable Django architecture.

django_abstract-0.1.0/README.md

@@ -0,0 +1,61 @@
+<div align="center">
+  <h1>🛡️ Django Abstract</h1>
+  <p><strong>An Enterprise-Grade Architectural Layer for Django</strong></p>
+  <p>Clean Architecture | Dependency Injection | CQRS Principles | Domain-Driven Design</p>
+</div>
+
+---
+
+## 📖 Overview
+
+**Django Abstract** is a highly advanced framework built on top of Django that strictly enforces **Clean Architecture** and **Domain-Driven Design (DDD)**. It solves the infamous "Fat Model / Fat View" anti-pattern by completely decoupling:
+
+1. **Data Access** (`Selectors` / `Creators`)
+2. **Business Logic** (`Services`)
+3. **Flow Control & Permissions** (`Operators` / `Systems`)
+
+This framework provides a unified, predictable way to scale complex Django applications, manage high-throughput operations via Redis queues, and dynamically inject dependencies.
+
+## 🚀 Key Features
+
+### 🧩 Global Registry & Dependency Injection
+- Dynamically registers all architectural components using decorators (`@creator_selector`, `@register_service`, `@register_operator`).
+- Injects `BaseDependency` instances at runtime to prevent circular imports and allow test mocking.
+- Magic attribute resolution (`__getattr__`) allows developers to resolve dependencies seamlessly (`dependency.select_user`).
+
+### 🏛️ Strict Architectural Separation
+- **`BaseModel`**: Adds soft-delete, active toggles, and rich audit trails natively.
+- **`BaseSelector` / `BaseCreator`**: Isolates raw Django ORM calls from business logic.
+- **`BaseService`**: Pure business logic that operates exclusively on an abstract `ServiceEntryData` state.
+- **`BaseSystem`**: Orchestrates workflows and manages global database transactions (`transaction.atomic()`).
+
+### ⚡ High-Throughput Background Logging
+- Includes a robust `log/` app that tracks `SystemErrorLog`, `SessionMetrics`, and `AdminActionLog`.
+- Uses a **Redis-backed queueing system** within `ModelServices` to buffer high-frequency inserts and bulk-flush (`bulk_create`) them to PostgreSQL, completely preventing database locking during traffic spikes.
+
+### 🔌 Seamless View Binding
+- Replaces traditional Django Views with `EntryBindingMixin`.
+- Automatically extracts `session_key`, `ip_address`, and POST/GET payloads, hydrates a master `Entry` object, and passes it directly to the orchestration `Systems`.
+
+## 📁 Repository Structure
+
+```text
+src/django_abstract/
+├── base/        # Core architectural base classes
+├── generic/     # Generic, reusable creation/selection patterns
+├── log/         # High-performance asynchronous auditing system
+├── registry.py  # Global Dependency Injection container
+└── utilities.py # Context extraction, View Mixins, State Objects
+```
+
+## 📚 Documentation
+Comprehensive documentation for every module can be found in the `docs/` folder:
+- [Base Architecture Overview](docs/django_abstract/base)
+- [Generic Utilities](docs/django_abstract/generic)
+- [High-Performance Logging](docs/django_abstract/log)
+
+## 🧪 Testing
+The repository is fully testable. Due to strict dependency injection, any `Selector` or `Creator` can be swapped out with a mock class during tests. Test stubs for all modules are located in the `tests/` directory.
+
+## 👨‍💻 Author
+Designed and implemented as an enterprise architectural study to showcase advanced systems design, Python metaprogramming, and scalable Django architecture.

django_abstract-0.1.0/docs/base.md

@@ -0,0 +1,67 @@
+# Django-Abstract Core Architecture
+
+django-abstract enforces Domain-Driven Design (DDD) by strictly separating concerns. Instead of writing monolithic Django views, you compose your application using our specialized base classes.
+
+1. Data Layer (BaseModel & BaseForm)
+
+BaseModel
+
+An abstract Django model that provides enterprise-grade defaults to every table in your database.
+
+UUID Primary Keys: Uses secure uuid4 instead of predictable auto-incrementing integers.
+
+Audit Trails: Automatically tracks created_at, updated_at, created_by, and updated_by.
+
+Soft Deletes: Built-in soft_delete() and reactivate() methods. It toggles is_active and logs deactivated_at instead of destroying data.
+
+BaseForm
+
+A smart ModelForm that automatically formats itself for modern frontend frameworks (like Bootstrap 5).
+
+Auto-Styling: Injects form-control into standard inputs and form-check-input into checkboxes/radios automatically.
+
+Audit Protection: Automatically strips out sensitive audit fields (created_by, deactivated_at) so users can't overwrite them via POST requests.
+
+2. Dependency Injection (BaseDependency)
+
+Instead of tightly coupling models to services, we use Dependencies.
+
+A BaseDependency acts as a bucket for Selectors (read queries) and Creators (write queries).
+
+Dynamic Resolution: Thanks to a custom __getattr__ implementation, accessing dependency.select_user() automatically routes to the correct localized or global registry.
+
+3. Business Logic (BaseOperatorService & BaseModelService)
+
+This is the brain of your application. Views do not contain logic; Services do.
+
+BaseOperatorService: The heavyweight base class. It handles data validation via the nested BaseServiceValidator, tracks db_record states, and safely routes read_entry, create_entry, and delete_entry operations.
+
+BaseModelService: Inherits from BaseOperatorService but adds model-specific utilities, like get_or_raise(), which standardizes 404/Missing error handling.
+
+4. Security & Routing (BaseOperator)
+
+Operators act as the "Bouncer" and "Router" before a Service is executed.
+
+Uses a ControlEntryData envelope to track state.
+
+The Bouncer (can_run): Validates if the current session or user is allowed to execute the requested target service.
+
+The Router (run): Finds the target service in the SERVICE_REGISTRY, packs the payload, and fires the service hook safely.
+
+5. Orchestration (BaseModelSystem)
+
+When an action requires multiple services to run (e.g., "Checkout" requires the Order Service, Inventory Service, and Email Service), you use a System.
+
+Transactional Safety: The run() method is permanently wrapped in transaction.atomic(). If any service fails, the entire database state rolls back safely.
+
+Operator Invocation: Dynamically loads allowed Operators to handle the complex multi-step flows.
+
+6. Error Handling (CoreException)
+
+Generic 500 errors are a nightmare to debug. CoreException provides:
+
+Standardized formatting with UTC timestamps.
+
+Explicit error_code injection.
+
+A context dictionary to log exactly what payload caused the failure.

django_abstract-0.1.0/docs/django_abstract/admin.md

@@ -0,0 +1,13 @@
+# admin.py
+
+## Overview
+Documentation for `admin.py`.
+
+## Classes / Functions
+- `Admin`
+- (Add more classes or functions as needed)
+
+## Usage Example
+```python
+# Add usage example here
+```

django_abstract-0.1.0/docs/django_abstract/apps.md

@@ -0,0 +1,13 @@
+# apps.py
+
+## Overview
+Documentation for `apps.py`.
+
+## Classes / Functions
+- `Apps`
+- (Add more classes or functions as needed)
+
+## Usage Example
+```python
+# Add usage example here
+```

django_abstract-0.1.0/docs/django_abstract/base/base_abstract_view.md

@@ -0,0 +1,12 @@
+# GMES View Bindings
+
+## Overview
+While the framework operates abstractly, `EntryBindingMixin` (located in `utilities.py` but representing the View layer) automatically binds an incoming Django HTTP Request to a framework `Entry`.
+
+## Workflow
+1. The View Mixin intercepts the request.
+2. It extracts the `session_key`, `ip_address`, `user_agent`, and payload (POST/GET parameters) via `ExtractRequestDataUtilities`.
+3. It creates a master `Entry` object.
+4. It attaches the `Entry` to the `request` object (e.g., `request.GMS_OBJECT.entry`).
+
+This allows `BaseSystem` to receive a fully hydrated context without caring if the request came from an API, an HTMX call, or a standard form submission.

django_abstract-0.1.0/docs/django_abstract/base/base_creator.md

@@ -0,0 +1,25 @@
+# BaseCreator
+
+## Overview
+`BaseCreator` handles the write operations (Create, Update, Delete) for a specific Django model. It abstracts away direct database mutations, ensuring consistent data handling. Inherits from `GenericCreator`.
+
+## Attributes
+- `model_class`: The Django model to mutate.
+- `status`: Execution status flag.
+- `system_infos`: Resolved class information for logging/metadata.
+
+## Methods
+- `access_db`: Property returning the model's default manager (`objects`).
+
+## Usage Example
+```python
+from django_abstract.base.base_creator import BaseCreator
+from .models import Product
+
+class ProductCreator(BaseCreator):
+    def __init__(self):
+        super().__init__(Product)
+        
+    def bulk_create_products(self, data_list):
+        return self.access_db.bulk_create([self.model_class(**data) for data in data_list])
+```

django_abstract-0.1.0/docs/django_abstract/base/base_dependency.md

@@ -0,0 +1,33 @@
+# BaseDependency
+
+## Overview
+`BaseDependency` is the foundation for dependency injection in the framework. It acts as a registry container, allowing components (like selectors and creators) to be resolved dynamically via custom `__getattr__` logic.
+
+## Attributes
+- `_registry`: The global or domain-specific registry (usually `GLOBAL_REGISTRY`).
+- `selectors`: A mapping of registered selectors for this dependency.
+- `creators`: A mapping of registered creators for this dependency.
+- `model_class`: The associated Django model class, automatically attached during registration.
+
+## Dynamic Resolution
+The magic of `BaseDependency` comes from overriding `__getattr__`. 
+- If you call `dependency.select_user`, it checks `selectors` in the registry and instantiates the `UserSelector`.
+- If you call `dependency.create_user`, it checks `creators` and instantiates the `UserCreator`.
+
+## Usage Example
+```python
+from django_abstract.base.base_dependency import BaseDependency
+from django_abstract.registry import creator_selector
+
+class ShopDependency(BaseDependency):
+    app_name = "shop"
+    domain = "e-commerce"
+
+@creator_selector(dependency=ShopDependency())
+class Product(BaseModel):
+    name = models.CharField(max_length=255)
+
+# Later in the code:
+dependency = ShopDependency()
+selector = dependency.select_product # Returns ProductSelector instance
+```

django_abstract-0.1.0/docs/django_abstract/base/base_exception.md

@@ -0,0 +1,34 @@
+# CoreException
+
+## Overview
+`CoreException` provides a standardized exception hierarchy for the entire framework. It allows for contextual error reporting and captures execution state, making debugging significantly easier.
+
+## Attributes
+- `message`: Human-readable error message.
+- `error_code`: Specific application error code.
+- `original_exception`: The underlying exception (if wrapping an existing error).
+- `context`: Additional dictionary payload associated with the error.
+- `timestamp`: UTC timestamp of when the exception occurred.
+
+## Derived Exceptions
+The framework defines several derived exceptions in `exceptions.py`, such as:
+- `ServiceException`
+- `SelectorException`
+- `SystemException`
+- `ModelNotBindedException`
+
+## Usage Example
+```python
+from django_abstract.base.base_exception import CoreException
+
+def do_something_risky():
+    try:
+        1 / 0
+    except ZeroDivisionError as e:
+        raise CoreException(
+            message="Math calculation failed",
+            error_code="MATH_001",
+            original_exception=e,
+            context={"user_id": 123}
+        )
+```

django_abstract-0.1.0/docs/django_abstract/base/base_form.md

@@ -0,0 +1,27 @@
+# BaseForm
+
+## Overview
+`BaseForm` extends Django's `ModelForm` to automatically exclude audit fields (like `created_at`, `updated_at`, etc.) and apply standard CSS classes (e.g., Bootstrap's `form-control`) to widgets.
+
+## Attributes
+- `deafault_exclude_fields`: List of standard audit fields to exclude automatically.
+- `exclude_fields`: Dynamically populated list of fields to exclude.
+
+## Methods
+- `exclude(*fields)`: Dynamically adds fields to the exclusion list and re-processes the form.
+- `_form_process()`: Internal method that applies CSS classes and removes excluded fields from the form.
+
+## Usage Example
+```python
+from django_abstract.base.base_form import BaseForm
+from .models import Product
+
+class ProductForm(BaseForm):
+    class Meta:
+        model = Product
+        fields = "__all__"
+
+# In a view:
+form = ProductForm()
+form.exclude("internal_code", "supplier_price")
+```

django_abstract-0.1.0/docs/django_abstract/base/base_model.md

@@ -0,0 +1,31 @@
+# BaseModel
+
+## Overview
+`BaseModel` provides a foundational Django model abstraction that adds standard audit fields and implements generic soft-deletion mechanics out of the box.
+
+## Fields
+- `id`: UUIDField (Primary Key).
+- `created_at`: DateTimeField (auto-populated on creation).
+- `updated_at`: DateTimeField (auto-updated on save).
+- `is_active`: BooleanField (defaults to True).
+- `is_disabled`: BooleanField (defaults to False).
+- `deactivated_at`: DateTimeField.
+- `deactivated_by`: CharField.
+- `created_by`: CharField.
+- `updated_by`: CharField.
+- `notes`: TextField.
+
+## Methods
+- `deactivate(user_id=None)`: Soft-deletes the record by setting `is_active=False` and recording the timestamp/user.
+- `activate()`: Re-activates a soft-deleted record.
+- `disable()`: Marks the record as completely disabled (distinct from soft-delete).
+
+## Usage Example
+```python
+from django_abstract.base.base_model import BaseModel
+from django.db import models
+
+class Product(BaseModel):
+    name = models.CharField(max_length=255)
+    price = models.DecimalField(max_digits=10, decimal_places=2)
+```

django_abstract-0.1.0/docs/django_abstract/base/base_model_service.md

@@ -0,0 +1,24 @@
+# BaseModelService
+
+## Overview
+`BaseModelService` inherits from `BaseOperatorService` and acts as the Model-Specific Logic Layer. It automatically gains access to the `selector` and `creator` for a registered Django model.
+
+## Attributes
+- `service_slug`: Unique identifier for the service.
+
+## Methods
+- `get_or_raise(**kwargs)`: Standardized fetch operation that raises a `ModelServiceException` if the record is not found, ensuring strict data expectations.
+
+## Usage Example
+```python
+from django_abstract.base.base_model_service import BaseModelService
+from django_abstract.registry import register_service
+
+@register_service()
+class ProductModelService(BaseModelService):
+    model_dependency = ShopDependency()
+    model_slug = "product"
+    
+    def fetch_product(self, product_id):
+        return self.get_or_raise(id=product_id)
+```

django_abstract-0.1.0/docs/django_abstract/base/base_model_system.md

@@ -0,0 +1,20 @@
+# BaseModelSystem
+
+## Overview
+`BaseModelSystem` is identical in structure to `BaseSystem`, but **always wraps execution in a database transaction** (`transaction.atomic()`). If any service or operator fails during `.execute()`, the entire database state rolls back.
+
+## Key Differences
+- The `.run()` method enforces `transaction.atomic()`. Use this system whenever orchestrating data writes across multiple tables (e.g., fulfilling an order and updating inventory).
+
+## Usage Example
+```python
+from django_abstract.base.base_model_system import BaseModelSystem
+
+class CheckoutSystem(BaseModelSystem):
+    allowed_operators = ["cart_operator", "inventory_operator"]
+    
+    def execute(self, cart_id):
+        # If inventory update fails, the cart charge is rolled back automatically
+        self.invoke_operator("cart_operator", "payment_service", "charge", {"cart_id": cart_id})
+        self.invoke_operator("inventory_operator", "inventory_service", "deduct", {"cart_id": cart_id})
+```

django_abstract-0.1.0/docs/django_abstract/base/base_operator.md

@@ -0,0 +1,27 @@
+# BaseOperator
+
+## Overview
+`BaseOperator` defines the flow control and permission layer. Operators determine who can access which services under what conditions. They act as "Routers" inside the `BaseSystem` to delegate actions to specific `BaseServices`.
+
+## Attributes
+- `allowed_services`: A whitelist of service names this operator is allowed to invoke.
+- `domain`: The domain context the operator belongs to.
+- `entry`: A `ControlEntryData` instance tracking execution state, flags, and errors.
+- `entry_operator`: A `ControlDataOperator` to mutate the entry data.
+
+## Methods
+- `dispatch(target_service_name, target_method, payload)`: Validates if the service is allowed, instantiates it with the current payload, and executes the target method.
+
+## Usage Example
+```python
+from django_abstract.base.base_operator import BaseOperator
+from django_abstract.registry import register_operator
+
+@register_operator()
+class GuestCartOperator(BaseOperator):
+    allowed_services = ["cart_model_service", "session_metrics_service"]
+    
+    def dispatch(self, target_service_name, target_method, payload):
+        # Additional permission checks for guests
+        return super().dispatch(target_service_name, target_method, payload)
+```

django_abstract-0.1.0/docs/django_abstract/base/base_operator_service.md

@@ -0,0 +1,19 @@
+# BaseOperatorService
+
+## Overview
+`BaseOperatorService` is the core service base class that bridges `BaseService` logic with Django model dependencies. It manages validation, caching bulk updates, and database transaction tracking.
+
+## Attributes
+- `model_dependency`: The injected model dependency registry.
+- `model_slug`: The slug identifying the target model.
+- `last_updated`: Timestamp of the last bulk update.
+- `operator_class`: Set to `ServiceDataOperator`.
+- `entry_class`: Set to `ServiceEntryData`.
+
+## Key Features
+- **Validation**: Implements an inner `BaseServiceValidator` class to handle `MINIMUM_WRITE_FIELDS` and permission checks before any method runs.
+- **Bulk Updating**: Collects pending updates in memory and only flushes to the database via `bulk_update` periodically (e.g., every 5 seconds) to prevent database locking on high-throughput models.
+- **Auto-loading**: Automatically loads the target database record into memory upon instantiation if `load_record=True`.
+
+## Usage Example
+Usually, developers inherit from `BaseModelService` instead of directly from `BaseOperatorService`, but it can be used for custom logic bridging.

django_abstract-0.1.0/docs/django_abstract/base/base_selector.md

@@ -0,0 +1,28 @@
+# BaseSelector
+
+## Overview
+`BaseSelector` acts as the read-only layer of the data access pattern. It abstracts away complex Django ORM queries into clean, testable methods.
+
+## Attributes
+- `model_class`: The Django model this selector is responsible for.
+
+## Methods
+- `__init__(model_class)`: Initializes the selector.
+- `get(**kwargs)`: Returns a single instance matching the query parameters or None.
+- `filter(**kwargs)`: Returns a queryset of instances matching the query parameters.
+- `all()`: Returns all instances of the model.
+- `exists(**kwargs)`: Checks if any instances match the parameters.
+- `count(**kwargs)`: Returns the count of matching instances.
+
+## Usage Example
+```python
+from django_abstract.base.base_selector import BaseSelector
+from .models import Product
+
+class ProductSelector(BaseSelector):
+    def __init__(self):
+        super().__init__(Product)
+        
+    def get_expensive_products(self):
+        return self.filter(price__gt=1000)
+```

django_abstract-0.1.0/docs/django_abstract/base/base_service.md

@@ -0,0 +1,33 @@
+# BaseService
+
+## Overview
+`BaseService` is the pure business logic layer. It operates entirely on `ServiceEntryData` and does NOT have direct database dependencies (unlike `BaseModelService`). 
+
+## Key Concepts
+- **Validation**: Enforces `MINIMUM_WRITE_FIELDS` or required payload parameters before execution.
+- **State Mutation**: Operations update `self.entry.service_data` instead of returning discrete values, ensuring a uniform data pipeline.
+- **Hook Architecture**: Uses hooks and execution proxies to chain multiple services together cleanly.
+
+## Attributes
+- `operator_class`: Set to `ServiceDataOperator`.
+- `entry_class`: Set to `ServiceEntryData`.
+- `hooks_list`: Allowed hooks.
+
+## Methods
+- `init_state_hook()`: Initializes the entry and operator state.
+- `hook()`: Lifecycle execution method to be called by operators.
+
+## Usage Example
+```python
+from django_abstract.base.base_service import BaseService
+from django_abstract.registry import register_service, action_method_fields
+
+@register_service(service_type="BARE_SERVICE")
+class EmailNotificationService(BaseService):
+    
+    @action_method_fields("email_address", "template_id")
+    def send_welcome_email(self, email_address, template_id):
+        # Call third party API
+        self.entry.service_data.update({"email_sent": True})
+        return self.entry
+```

django_abstract-0.1.0/docs/django_abstract/base/base_system.md

@@ -0,0 +1,26 @@
+# BaseSystem
+
+## Overview
+`BaseSystem` acts as the primary Orchestration Layer for actions that DO NOT require strict database transactions. It defines the workflow entry point and manages the master `Entry` object.
+
+## Attributes
+- `allowed_operators`: Whitelist of operators this system is allowed to invoke.
+- `request`: The incoming HTTP request.
+- `session_key`: The active session identifier.
+- `entry`: The master `Entry` object that holds `ControlEntryData`, `ServiceEntryData`, and `EntryData`.
+
+## Methods
+- `execute(*args, **kwargs)`: Abstract method. Must be implemented to define the main orchestration logic.
+- `run(*args, **kwargs)`: Standard execution wrapper. Calls `execute()` and handles high-level failure logging.
+- `invoke_operator(operator_name, target_service, target_method, payload)`: Dynamically fetches the specified operator, validates system permissions, and dispatches the payload to the service.
+
+## Usage Example
+```python
+from django_abstract.base.base_system import BaseSystem
+
+class AnalyticsSystem(BaseSystem):
+    allowed_operators = ["metrics_operator"]
+    
+    def execute(self, path):
+        self.invoke_operator("metrics_operator", "session_metrics", "record_hit", {"path": path})
+```