# System Architecture Documentation

## Core Components

### 1. ClusterToMethod (Router)
API router that groups related endpoints into logical clusters.

**Key Components:**
- `TAGS`: List of router categorization tags
- `PREFIX`: Base URL prefix for all contained endpoints
- `PAGEINFO`: Page metadata and UI information
- `ENDPOINTS`: Collection of MethodEvent instances
- `SUBCATEGORY`: Nested ClusterToMethod instances for hierarchical routing

### 2. MethodToEvent (Endpoint Handler)
Handles individual API endpoints and their event mappings.

**Key Components:**
- `EVENTS`: Collection of Event instances
- `HEADER_LANGUAGE_MODELS`: Header localization
- `ERROR_LANGUAGE_MODELS`: Error message localization
- Endpoint metadata (URL, method, summary, description)
- Endpoint callable with request validation

### 3. Event (Business Logic)
Represents individual business operations with validation.

**Core Features:**
- Unique `KEY_` identifier
- Request/Response validation using PydanticModel
- Callable business logic function
- Language model integration

## Data Flow & Storage

### Redis Key Structure
```
CLUSTER_FUNCTION_CODES:{ClusterToMethod}
└── {PageInfo, [FunctionCodes]}

METHOD_FUNCTION_CODES:{ClusterToMethod}:MethodEvent:Endpoint
└── [FunctionCodes]

LANGUAGE_MODELS:*
└── Localization data

PAGE_MAPPER:{Type}:{BuildingID}:{UserID}
└── PageInfo

MENU_MAPPER:{Type}:{BuildingID}:{UserID}
└── PageInfo
```

### Application Initialization Flow
1. **Pages Iteration**
   - Saves router/endpoint mappings
   - Caches menu structure

2. **Events Iteration**
   - Stores endpoint information
   - Caches validation schemas

3. **Web Statics**
   - Caches localization data
   - Builds UI components

### Request Flow
```
Request → Router(ClusterToMethod) → Endpoint(MethodEvent) → Event Handler
                                 ↓
                            Validation
                                 ↓
                         Business Logic
```

## Core Services

### 1. ValidationService
- Model validation handling
- Schema caching
- Language-specific validation
- Redis-first validation lookup

### 2. EventService
- Event routing management
- Function code mapping
- User-specific event access
- Login state management

### 3. AuthService
- User authentication
- Event access control
- User preferences (timezone, language)
- Token management

## Design Patterns

### 1. Multi-layer Validation
- Language model validation
- Function code validation
- User access validation
- Request/Response schema validation

### 2. Hierarchical Routing
- ClusterToMethod → MethodEvent → Event
- Nested routing via SUBCATEGORY
- URL prefix inheritance

### 3. Internationalization
- Comprehensive language support
- Cached translations
- Header and error localization
- Per-user language preferences

## Cache Layer

### Redis Categories
```
RedisCategoryKeys:
├── LANGUAGE_MODELS
├── VALIDATION_USER
├── CLUSTER_FUNCTION_CODES
├── METHOD_FUNCTION_CODES
├── MENU_FIRST_LAYER
├── PAGE_MAPPER
├── MENU_MAPPER
├── AUTH (Authorization)
├── OCC (Occupant)
└── EMP (Employee)
```

### Cache Invalidation
- On login: User-specific caches
- On language change: Localization caches
- On permission change: Access control caches