135 lines
3.3 KiB
Markdown
135 lines
3.3 KiB
Markdown
# 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 |