created design pattern

create_patterns/README.md

@@ -0,0 +1,102 @@
+# Endpoint Structure Pattern
+
+This document describes the Endpoint Structure pattern used in the EVYOS backend services.
+
+## Overview
+
+The Endpoint Structure is a modular, event-driven architecture pattern that provides clear separation of concerns for API services. It consists of three main components:
+
+1. **Events Component**
+2. **Endpoints Component**
+3. **Validations Component**
+
+This architecture enables scalable, maintainable API services with a consistent structure.
+
+## Directory Structure
+
+```
+ApiServices/
+└── [ServiceName]/
+    ├── Events/
+    │   └── [entity]/
+    │       ├── cluster.py
+    │       └── supers_events.py
+    ├── Endpoints/
+    │   └── [entity]/
+    │       └── route.py
+    └── Validations/
+        └── [entity]/
+            └── [entity]/
+                └── validations.py
+```
+
+## Components
+
+### 1. Events Component
+
+Located at `ApiServices/[ServiceName]/Events/[entity]/`
+
+#### cluster.py
+- Organizes events into clusters for routing
+- Contains:
+  - `RouterCluster`: Top-level container for event clusters
+  - `EventCluster`: Groups related events (List, Create, Update)
+  - Each cluster has a unique name and UUID
+
+#### supers_events.py
+- Defines event handlers with business logic
+- Contains:
+  - `Event` objects with unique name, key, validators, and description
+  - Callable methods implementing business logic
+  - Events are registered to their respective clusters
+
+### 2. Endpoints Component
+
+Located at `ApiServices/[ServiceName]/Endpoints/[entity]/`
+
+#### route.py
+- Defines FastAPI routes that map to event handlers
+- Contains:
+  - APIRouter with prefix and tags
+  - Route functions that:
+    - Extract token information
+    - Retrieve event codes
+    - Match to appropriate event cluster
+    - Call corresponding event handler
+
+### 3. Validations Component
+
+Located at `ApiServices/[ServiceName]/Validations/[entity]/[entity]/`
+
+#### validations.py
+- Defines Pydantic models for request/response validation
+- Contains:
+  - Request models with field definitions
+  - Response models for structured responses
+
+## Data Flow
+
+1. Request → FastAPI endpoint
+2. Data validation with Pydantic
+3. Token extraction and event code retrieval
+4. Event matching and handler execution
+5. Business logic execution
+6. Formatted response return
+
+## Implementation Guide
+
+To implement a new endpoint using this structure:
+
+1. Create the directory structure for your entity
+2. Define validation models in `validations.py`
+3. Create events and their callable methods in `supers_events.py`
+4. Organize events into clusters in `cluster.py`
+5. Define API routes in `route.py`
+
+## Benefits
+
+- Clear separation of concerns
+- Consistent structure across services
+- Scalable and maintainable architecture
+- Flexible event-driven design
+- Standardized response format