# 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