prod-wag-backend-automate-services/create_patterns

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