http-request-manager 18.7.21 → 18.7.24

package/ARCHITECTURE.md

@@ -1,483 +0,0 @@
-# HTTP Request Manager - Architecture Overview
-
-## System Architecture
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                         Angular Application                      │
-├─────────────────────────────────────────────────────────────────┤
-│                                                                   │
-│  ┌────────────────┐  ┌────────────────┐  ┌──────────────────┐  │
-│  │   Components   │  │   Components   │  │    Components    │  │
-│  │   (Signals)    │  │  (Observables) │  │  (State Store)   │  │
-│  └───────┬────────┘  └───────┬────────┘  └────────┬─────────┘  │
-│          │                   │                     │             │
-│          ▼                   ▼                     ▼             │
-│  ┌──────────────┐    ┌──────────────┐    ┌──────────────────┐  │
-│  │HTTPManager   │    │HTTPManager   │    │HTTPManager       │  │
-│  │SignalsService│    │Service       │    │StateService      │  │
-│  └──────┬───────┘    └──────┬───────┘    └────────┬─────────┘  │
-│         │                   │                      │             │
-│         └───────────────────┴──────────────────────┘             │
-│                             │                                    │
-│                             ▼                                    │
-│                    ┌─────────────────┐                          │
-│                    │  HttpClient     │                          │
-│                    │  (Angular)      │                          │
-│                    └────────┬────────┘                          │
-│                             │                                    │
-├─────────────────────────────┼────────────────────────────────────┤
-│                             │                                    │
-│  ┌──────────────────────────┼──────────────────────┐            │
-│  │        Local Storage Layer                      │            │
-│  ├──────────────────────────┼──────────────────────┤            │
-│  │                          │                      │            │
-│  │  ┌────────────────┐      │      ┌─────────────┐│            │
-│  │  │LocalStorage    │      │      │IndexedDB    ││            │
-│  │  │Manager Service │      │      │(Dexie.js)   ││            │
-│  │  └────────────────┘      │      └─────────────┘│            │
-│  │                          │                      │            │
-│  └──────────────────────────┼──────────────────────┘            │
-│                             │                                    │
-│  ┌──────────────────────────┼──────────────────────┐            │
-│  │        WebSocket Layer                          │            │
-│  ├──────────────────────────┼──────────────────────┤            │
-│  │                          │                      │            │
-│  │  ┌─────────────────────────────────────┐       │            │
-│  │  │   WebsocketService                  │       │            │
-│  │  │   - Connection Management           │       │            │
-│  │  │   - Channel Subscriptions           │       │            │
-│  │  │   - Message Routing                 │       │            │
-│  │  │   - Authentication (JWT)            │       │            │
-│  │  └─────────────────────────────────────┘       │            │
-│  │                                                 │            │
-│  └─────────────────────────────────────────────────┘            │
-│                             │                                    │
-└─────────────────────────────┼────────────────────────────────────┘
-                              │
-                              ▼
-                ┌──────────────────────────────┐
-                │     Backend Server            │
-                ├──────────────────────────────┤
-                │                               │
-                │  ┌────────────────────────┐  │
-                │  │  HTTP REST API         │  │
-                │  │  (Express/Node.js)     │  │
-                │  └────────────────────────┘  │
-                │                               │
-                │  ┌────────────────────────┐  │
-                │  │  WebSocket Server      │  │
-                │  │  (ws library)          │  │
-                │  └────────────────────────┘  │
-                │                               │
-                │  ┌────────────────────────┐  │
-                │  │  SQLite Database       │  │
-                │  │  (Notifications)       │  │
-                │  └────────────────────────┘  │
-                │                               │
-                └───────────────────────────────┘
-```
-
-## Service Hierarchy
-
-```
-HTTPManagerService (Base)
-├── Features:
-│   ├── HTTP CRUD Operations
-│   ├── Loading States (isPending$, error$, data$)
-│   ├── Retry Logic
-│   ├── Polling with Countdown
-│   ├── Adapters & Mappers
-│   └── Stream Handling
-│
-├── HTTPManagerSignalsService
-│   └── Same as HTTPManagerService but with Angular Signals
-│
-└── HTTPManagerStateService (extends ComponentStore)
-    ├── Inherits all HTTPManagerService features
-    ├── ComponentStore Integration
-    ├── CRUD with Auto State Updates
-    ├── WebSocket Integration
-    │   ├── SYS- channels (State sync)
-    │   ├── PUB- channels (Messaging)
-    │   └── MES- channels (Notifications)
-    ├── IndexedDB Caching
-    ├── Pagination Support
-    └── Real-time Updates
-```
-
-## Data Flow
-
-### HTTP Request Flow
-
-```
-Component
-    │
-    ├─> Call Service Method (e.g., fetchRecords())
-    │
-    ▼
-HTTPManagerStateService
-    │
-    ├─> Build ApiRequest
-    │   ├─> Apply Mapper (if provided)
-    │   └─> Add Headers
-    │
-    ▼
-HTTPManagerService
-    │
-    ├─> Check Polling
-    ├─> Execute HTTP Request (HttpClient)
-    │
-    ▼
-Interceptors
-    │
-    ├─> RequestHeadersInterceptor (add headers)
-    ├─> WithCredentialsInterceptor (add credentials)
-    └─> RequestErrorInterceptor (handle errors)
-    │
-    ▼
-Backend Server
-    │
-    ├─> Process Request
-    └─> Return Response
-    │
-    ▼
-HTTPManagerService
-    │
-    ├─> Apply Adapter (transform data)
-    ├─> Update isPending$ = false
-    ├─> Update data$ with new data
-    │
-    ▼
-HTTPManagerStateService
-    │
-    ├─> Update ComponentStore state
-    └─> Save to IndexedDB (if configured)
-    │
-    ▼
-Component
-    │
-    └─> Display updated data via data$ observable
-```
-
-### WebSocket Message Flow
-
-```
-Component
-    │
-    └─> Send Message (e.g., sendNotification())
-        │
-        ▼
-HTTPManagerStateService
-    │
-    └─> Add Channel Prefix (MES-, PUB-, or SYS-)
-        │
-        ▼
-WebsocketService
-    │
-    ├─> Format Message
-    │   ├─> type: 'notification'
-    │   ├─> channel: 'MES-alerts'
-    │   ├─> content: { message: '...' }
-    │   └─> sessionId: { id, name, email }
-    │
-    └─> Send via WebSocket
-        │
-        ▼
-Backend WebSocket Server
-    │
-    ├─> Validate Channel & User
-    ├─> Store in Database (for MES- channels)
-    └─> Broadcast to Subscribers
-        │
-        ▼
-All Connected Clients (Subscribers)
-    │
-    ├─> WebsocketService receives message
-    │
-    ▼
-HTTPManagerStateService
-    │
-    ├─> Update ComponentStore
-    └─> Emit via notificationMessages$
-        │
-        ▼
-Component
-    │
-    └─> Display notification in UI
-```
-
-## Channel Architecture
-
-### Channel Types and Data Flow
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                        Client Application                        │
-├─────────────────────────────────────────────────────────────────┤
-│                                                                   │
-│  Component calls:                                                │
-│  ┌──────────────────────────────────────────────────────────┐   │
-│  │ stateService.subscribeToChannel('general')           (PUB)│   │
-│  │ stateService.subscribeToNotificationChannel('alerts') (MES)│  │
-│  │ stateService.fetchRecords()                          (SYS)│   │
-│  └──────────────────────────────────────────────────────────┘   │
-│                            │                                     │
-│                            ▼                                     │
-│  ┌──────────────────────────────────────────────────────────┐   │
-│  │         HTTPManagerStateService                          │   │
-│  │  - Adds appropriate prefix (PUB-, MES-, SYS-)           │   │
-│  │  - Routes to WebsocketService                           │   │
-│  └──────────────────────────────────────────────────────────┘   │
-│                            │                                     │
-│                            ▼                                     │
-│  ┌──────────────────────────────────────────────────────────┐   │
-│  │              WebsocketService                            │   │
-│  │  - Manages connection lifecycle                          │   │
-│  │  - Sends subscription messages                           │   │
-│  │  - Receives and routes messages                          │   │
-│  └──────────────────────────────────────────────────────────┘   │
-│                            │                                     │
-└────────────────────────────┼─────────────────────────────────────┘
-                             │
-                             ▼
-┌─────────────────────────────────────────────────────────────────┐
-│                      WebSocket Server                            │
-├─────────────────────────────────────────────────────────────────┤
-│                                                                   │
-│  ┌──────────────┐   ┌──────────────┐   ┌──────────────┐        │
-│  │ PUB- Channel │   │ MES- Channel │   │ SYS- Channel │        │
-│  │              │   │              │   │              │        │
-│  │ In-Memory    │   │ DB Persisted │   │ State Sync   │        │
-│  │ Broadcasting │   │ Notifications│   │ Private      │        │
-│  └──────┬───────┘   └──────┬───────┘   └──────┬───────┘        │
-│         │                  │                  │                 │
-│         ▼                  ▼                  ▼                 │
-│  ┌────────────────────────────────────────────────┐            │
-│  │     Channel Subscribers (Set<WebSocket>)       │            │
-│  └────────────────────────────────────────────────┘            │
-│         │                  │                  │                 │
-│         └──────────────────┴──────────────────┘                 │
-│                            │                                     │
-│                            ▼                                     │
-│  ┌─────────────────────────────────────────────────┐            │
-│  │        Broadcast to All Subscribers             │            │
-│  └─────────────────────────────────────────────────┘            │
-│                                                                   │
-│  For MES- channels:                                              │
-│  ┌─────────────────────────────────────────────────┐            │
-│  │  1. Store in SQLite Database                    │            │
-│  │  2. Broadcast to current subscribers            │            │
-│  │  3. Retrieve historical data on new subscription│            │
-│  └─────────────────────────────────────────────────┘            │
-│                                                                   │
-└───────────────────────────────────────────────────────────────────┘
-```
-
-## State Management Flow
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                    ComponentStore                            │
-│                (HTTPManagerStateService extends this)        │
-├─────────────────────────────────────────────────────────────┤
-│                                                               │
-│  State Interface:                                            │
-│  {                                                            │
-│    records: T[],           // Array of entities             │
-│    record: T | null,       // Single selected entity        │
-│    page: number,           // Current page                  │
-│    totalPages: number,     // Total pages                   │
-│    isPending: boolean,     // Loading state                 │
-│    error: any              // Error state                   │
-│  }                                                            │
-│                                                               │
-│  Selectors (Observables):                                    │
-│  ├─> data$ (all records)                                     │
-│  ├─> record$ (single record)                                 │
-│  ├─> selectRecord$(id) (specific record)                     │
-│  ├─> page$                                                    │
-│  └─> totalPages$                                              │
-│                                                               │
-│  Updaters (State Mutations):                                 │
-│  ├─> updateRecordsState(records[])                           │
-│  ├─> addRecordState(record)                                  │
-│  ├─> updateRecordState(record)                               │
-│  ├─> deleteRecordState(id)                                   │
-│  └─> setError(error)                                          │
-│                                                               │
-│  Effects (Side Effects):                                      │
-│  ├─> fetchRecords() → HTTP GET                               │
-│  ├─> createRecord() → HTTP POST → addRecordState()           │
-│  ├─> updateRecord() → HTTP PUT → updateRecordState()         │
-│  ├─> deleteRecord() → HTTP DELETE → deleteRecordState()      │
-│  └─> WebSocket messages → auto state updates                 │
-│                                                               │
-└───────────────────────────────────────────────────────────────┘
-```
-
-## Caching Strategy
-
-```
-┌────────────────────────────────────────────────────────────┐
-│              Fetch Records Request                          │
-└──────────────────────┬─────────────────────────────────────┘
-                       │
-                       ▼
-         ┌─────────────────────────┐
-         │ DatabaseStorage Config? │
-         └────────┬────────────────┘
-                  │
-          ┌───────┴────────┐
-          │                │
-         YES              NO
-          │                │
-          ▼                ▼
-┌──────────────────┐  ┌──────────────┐
-│Check IndexedDB   │  │Fetch from    │
-│for cached data   │  │Server (HTTP) │
-└────┬─────────────┘  └──────┬───────┘
-     │                       │
-     ▼                       │
-┌──────────────┐             │
-│Cache Valid?  │             │
-└──┬───────────┘             │
-   │                         │
-┌──┴──┐                      │
-│ YES │ NO                   │
-│     │                      │
-▼     ▼                      │
-│  ┌──────────────┐          │
-│  │Fetch from    │          │
-│  │Server        │          │
-│  └──────┬───────┘          │
-│         │                  │
-│         ▼                  │
-│  ┌──────────────┐          │
-│  │Save to       │          │
-│  │IndexedDB     │          │
-│  └──────┬───────┘          │
-│         │                  │
-└─────────┴──────────────────┘
-          │
-          ▼
-┌──────────────────────────┐
-│Update ComponentStore     │
-│and emit via data$        │
-└──────────────────────────┘
-```
-
-## Integration Points
-
-### Backend Requirements
-
-For full functionality, the backend server must:
-
-1. **HTTP REST API**
-   - CRUD endpoints for entities
-   - JSON request/response format
-   - Support for standard HTTP methods (GET, POST, PUT, DELETE)
-
-2. **WebSocket Server**
-   - Accept WebSocket connections with optional JWT authentication
-   - Handle message types: `subscribe`, `unsubscribe`, `message`, `notification`, etc.
-   - Broadcast messages to channel subscribers
-   - Maintain channel subscriptions per connection
-
-3. **Database (for MES- channels)**
-   - Store notifications with: id, channel, user_name, created (epoch), message (JSON)
-   - Support queries by channel and date range
-   - Provide endpoints for:
-     - GET today's notification channels
-     - GET previous day's notification channels
-     - GET notifications by channel with date filters
-
-### Example Backend Structure
-
-See `gtlc-websockets` server implementation for reference:
-- `ws-server.js` - Main server with HTTP and WebSocket setup
-- `middleware/websocket-service.js` - WebSocket message handlers
-- `middleware/notification-db.js` - SQLite database operations
-
----
-
-## Security Considerations
-
-1. **JWT Authentication**: WebSocket connections can require JWT tokens
-2. **Encrypted Storage**: LocalStorage can use AES encryption with APP_ID
-3. **Channel Access Control**: Backend validates user permissions for channels
-4. **HTTPS/WSS**: Production deployments should use secure protocols
-5. **Data Validation**: All inputs are validated on server side
-
----
-
-## Performance Optimizations
-
-1. **IndexedDB Caching**: Reduces server load and improves offline capability
-2. **Polling with Countdown**: Visual feedback prevents duplicate requests
-3. **Connection Pooling**: WebSocket reuses single connection for all channels
-4. **Debounced Updates**: State updates batched when possible
-5. **Lazy Loading**: Services loaded only when needed
-
----
-
-## Migration Guide
-
-### From HTTPClient to HTTPManagerService
-
-```typescript
-// Before (HttpClient)
-http.get('api/users').subscribe(users => {
-  this.users = users;
-  this.loading = false;
-});
-
-// After (HTTPManagerService)
-httpManager.getRequest(
-  ApiRequest.adapt({ path: ['users'] })
-).subscribe();
-
-data$ = this.httpManager.data$;
-isLoading$ = this.httpManager.isPending$;
-```
-
-### From Manual State to HTTPManagerStateService
-
-```typescript
-// Before (Manual State)
-users: User[] = [];
-loading = false;
-
-loadUsers() {
-  this.loading = true;
-  this.http.get('api/users').subscribe(users => {
-    this.users = users;
-    this.loading = false;
-  });
-}
-
-addUser(user: User) {
-  this.http.post('api/users', user).subscribe(newUser => {
-    this.users = [...this.users, newUser];
-  });
-}
-
-// After (HTTPManagerStateService)
-@Injectable()
-export class UsersStore extends HTTPManagerStateService<User> {
-  constructor() {
-    super(ApiRequest.adapt({ path: ['users'] }), DataType.ARRAY);
-  }
-  
-  loadUsers() { this.fetchRecords(); }
-  addUser(user: User) { this.createRecord(user); }
-}
-
-// Component
-data$ = this.usersStore.data$;
-isLoading$ = this.usersStore.isPending$;
-```
-
----
-
-This architecture provides a scalable, maintainable foundation for Angular applications with comprehensive data management capabilities.