diff --git a/appdoc/doc_security_role_based_access_admin_api.md b/appdoc/doc_security_role_based_access_admin_api.md new file mode 100644 index 0000000..9265961 --- /dev/null +++ b/appdoc/doc_security_role_based_access_admin_api.md @@ -0,0 +1,372 @@ +# RBAC Admin Roles Management & Options API + +## Overview + +This document describes two new features added to support RBAC management: + +1. **Options API**: Dynamic options endpoint for frontend select/multiselect fields +2. **Admin RBAC Roles Module**: Comprehensive role and role assignment management + +--- + +## 1. Options API + +### Purpose + +The Options API provides dynamic options for frontend form fields that use `frontend_options` as a string reference (e.g., `"user.role"`). This allows the frontend to fetch options from the backend, enabling: +- Database-driven options (e.g., user connections) +- Context-aware options (filtered by current user's permissions) +- Centralized option management + +### Frontend Options Format + +The `frontend_options` attribute in Pydantic `Field` definitions supports **two formats**: + +#### 1. Static List (for basic data types) +```python +frontend_options=[ + {"value": "a", "label": {"en": "All Records", "fr": "Tous les enregistrements"}}, + {"value": "m", "label": {"en": "My Records", "fr": "Mes enregistrements"}} +] +``` + +#### 2. String Reference (for dynamic/custom types) +```python +frontend_options="user.role" # Frontend fetches from /api/options/user.role +``` + +### API Endpoints + +#### Get Options +``` +GET /api/options/{optionsName} +``` + +**Path Parameters:** +- `optionsName`: Name of the options set (e.g., "user.role", "user.connection") + +**Response:** +```json +[ + { + "value": "sysadmin", + "label": { + "en": "System Administrator", + "fr": "Administrateur système" + } + }, + { + "value": "admin", + "label": { + "en": "Administrator", + "fr": "Administrateur" + } + } +] +``` + +**Examples:** +- `GET /api/options/user.role` - Get available role options +- `GET /api/options/user.connection` - Get user's connections (context-aware) +- `GET /api/options/auth.authority` - Get authentication authority options +- `GET /api/options/connection.status` - Get connection status options + +#### List Available Options +``` +GET /api/options/ +``` + +**Response:** +```json +[ + "user.role", + "auth.authority", + "connection.status", + "user.connection" +] +``` + +### Available Options + +| Options Name | Description | Context-Aware | +|-------------|------------|---------------| +| `user.role` | Standard role options (sysadmin, admin, user, viewer) | No | +| `auth.authority` | Authentication authority options (local, google, msft) | No | +| `connection.status` | Connection status options (active, inactive, expired, error) | No | +| `user.connection` | User's connections (fetched from database) | Yes (requires currentUser) | + +### Implementation + +**Files:** +- `gateway/modules/features/options/mainOptions.py` - Options logic +- `gateway/modules/routes/routeOptions.py` - Options API endpoints + +**Usage in Pydantic Models:** +```python +roleLabels: List[str] = Field( + default_factory=list, + description="List of role labels", + json_schema_extra={ + "frontend_type": "multiselect", + "frontend_readonly": False, + "frontend_required": True, + "frontend_options": "user.role" # String reference + } +) +``` + +--- + +## 2. Admin RBAC Roles Module + +### Purpose + +The Admin RBAC Roles module provides comprehensive management of roles and role assignments to users. This module allows administrators to: +- View all available roles with metadata +- List users with their role assignments +- Assign/remove roles to/from users +- Filter users by role or mandate +- View role statistics (user counts per role) + +### Access Control + +**Required Permissions:** +- User must have `admin` or `sysadmin` role +- RBAC permission check for `UserInDB` table update operations + +### API Endpoints + +#### List All Roles +``` +GET /api/admin/rbac/roles/ +``` + +**Response:** +```json +[ + { + "roleLabel": "sysadmin", + "description": { + "en": "System Administrator - Full access to all system resources", + "fr": "Administrateur système - Accès complet à toutes les ressources" + }, + "userCount": 2, + "isSystemRole": true + }, + { + "roleLabel": "admin", + "description": { + "en": "Administrator - Manage users and resources within mandate scope", + "fr": "Administrateur - Gérer les utilisateurs et ressources dans le périmètre du mandat" + }, + "userCount": 5, + "isSystemRole": true + } +] +``` + +#### List Users with Roles +``` +GET /api/admin/rbac/roles/users?roleLabel=admin&mandateId=mandate-123 +``` + +**Query Parameters:** +- `roleLabel` (optional): Filter by role label +- `mandateId` (optional): Filter by mandate ID + +**Response:** +```json +[ + { + "id": "user-123", + "username": "john.doe", + "email": "john@example.com", + "fullName": "John Doe", + "mandateId": "mandate-123", + "enabled": true, + "roleLabels": ["admin", "user"], + "roleCount": 2 + } +] +``` + +#### Get User Roles +``` +GET /api/admin/rbac/roles/users/{userId} +``` + +**Response:** +```json +{ + "id": "user-123", + "username": "john.doe", + "email": "john@example.com", + "fullName": "John Doe", + "mandateId": "mandate-123", + "enabled": true, + "roleLabels": ["admin", "user"], + "roleCount": 2 +} +``` + +#### Update User Roles +``` +PUT /api/admin/rbac/roles/users/{userId}/roles +``` + +**Request Body:** +```json +{ + "roleLabels": ["admin", "user"] +} +``` + +**Response:** +Updated user object with new role assignments + +#### Add Role to User +``` +POST /api/admin/rbac/roles/users/{userId}/roles/{roleLabel} +``` + +**Response:** +Updated user object with role added (if not already present) + +#### Remove Role from User +``` +DELETE /api/admin/rbac/roles/users/{userId}/roles/{roleLabel} +``` + +**Response:** +Updated user object with role removed + +**Note:** If all roles are removed, user defaults to `"user"` role + +#### Get Users with Specific Role +``` +GET /api/admin/rbac/roles/roles/{roleLabel}/users?mandateId=mandate-123 +``` + +**Query Parameters:** +- `mandateId` (optional): Filter by mandate ID + +**Response:** +List of users with the specified role + +### Standard Roles + +| Role Label | Description | System Role | +|-----------|-------------|-------------| +| `sysadmin` | System Administrator - Full access to all system resources | Yes | +| `admin` | Administrator - Manage users and resources within mandate scope | Yes | +| `user` | User - Standard user with access to own records | Yes | +| `viewer` | Viewer - Read-only access to group records | Yes | + +**Custom Roles:** The system also supports custom role labels. These are detected when users are assigned non-standard roles and are marked with `isSystemRole: false`. + +### Implementation + +**Files:** +- `gateway/modules/routes/routeAdminRbacRoles.py` - Admin RBAC Roles API endpoints + +**Dependencies:** +- `gateway/modules/interfaces/interfaceDbAppObjects.py` - User management interface +- `gateway/modules/security/auth.py` - Authentication and authorization + +### Usage Examples + +#### Assign Multiple Roles to User +```bash +curl -X PUT "http://localhost:8000/api/admin/rbac/roles/users/user-123/roles" \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d '{"roleLabels": ["admin", "user"]}' +``` + +#### Add Single Role +```bash +curl -X POST "http://localhost:8000/api/admin/rbac/roles/users/user-123/roles/admin" \ + -H "Authorization: Bearer " +``` + +#### Remove Role +```bash +curl -X DELETE "http://localhost:8000/api/admin/rbac/roles/users/user-123/roles/viewer" \ + -H "Authorization: Bearer " +``` + +#### List All Admins +```bash +curl "http://localhost:8000/api/admin/rbac/roles/roles/admin/users" \ + -H "Authorization: Bearer " +``` + +--- + +## Integration + +### Route Registration + +Both modules are registered in `gateway/app.py`: + +```python +from modules.routes.routeOptions import router as optionsRouter +app.include_router(optionsRouter) + +from modules.routes.routeAdminRbacRoles import router as adminRbacRolesRouter +app.include_router(adminRbacRolesRouter) +``` + +### Frontend Integration + +#### Using Dynamic Options + +When a Pydantic model field uses `frontend_options` as a string reference: + +```python +roleLabels: List[str] = Field( + frontend_options="user.role" +) +``` + +The frontend should: +1. Detect the string reference (not a list) +2. Fetch options from `/api/options/user.role` +3. Use the returned options for the select/multiselect field + +#### Using Admin RBAC Roles Module + +The frontend can use the Admin RBAC Roles endpoints to: +- Display role management UI +- Show role assignments in user management +- Provide role assignment controls +- Display role statistics + +--- + +## Security Considerations + +1. **Options API**: + - Requires authentication (currentUser dependency) + - Context-aware options (e.g., `user.connection`) are filtered by current user + - Rate limited: 120 requests/minute + +2. **Admin RBAC Roles Module**: + - Requires `admin` or `sysadmin` role + - All endpoints are rate limited: 30-60 requests/minute + - RBAC permission checks ensure users can only manage roles if they have permission + +--- + +## Future Enhancements + +1. **Options API**: + - Add more option types (e.g., mandate options, workflow options) + - Support for filtered options based on RBAC permissions + - Caching for frequently accessed options + +2. **Admin RBAC Roles Module**: + - Role metadata management (descriptions, permissions summary) + - Bulk role assignment operations + - Role usage analytics + - Role templates/presets diff --git a/strategy/doc_platform_01_platform_overview.jpg b/strategy/doc_platform_01_platform_overview.jpg new file mode 100644 index 0000000..d80c5ba Binary files /dev/null and b/strategy/doc_platform_01_platform_overview.jpg differ diff --git a/strategy/doc_platform_02_customer_story.jpg b/strategy/doc_platform_02_customer_story.jpg new file mode 100644 index 0000000..587a9b1 Binary files /dev/null and b/strategy/doc_platform_02_customer_story.jpg differ diff --git a/strategy/doc_platform_03_workflow_system.jpg b/strategy/doc_platform_03_workflow_system.jpg new file mode 100644 index 0000000..ea696db Binary files /dev/null and b/strategy/doc_platform_03_workflow_system.jpg differ diff --git a/strategy/doc_platform_04_microservice_architecture.jpg b/strategy/doc_platform_04_microservice_architecture.jpg new file mode 100644 index 0000000..788c269 Binary files /dev/null and b/strategy/doc_platform_04_microservice_architecture.jpg differ diff --git a/strategy/doc_platform_05_rbac_system.jpg b/strategy/doc_platform_05_rbac_system.jpg new file mode 100644 index 0000000..22751d0 Binary files /dev/null and b/strategy/doc_platform_05_rbac_system.jpg differ diff --git a/strategy/doc_platform_06_ui_architecture.jpg b/strategy/doc_platform_06_ui_architecture.jpg new file mode 100644 index 0000000..bcadcc4 Binary files /dev/null and b/strategy/doc_platform_06_ui_architecture.jpg differ diff --git a/strategy/doc_platform_07_big_picture_and_future_vision.jpg b/strategy/doc_platform_07_big_picture_and_future_vision.jpg new file mode 100644 index 0000000..06e0ea4 Binary files /dev/null and b/strategy/doc_platform_07_big_picture_and_future_vision.jpg differ diff --git a/strategy/doc_platform_big_picture.css b/strategy/doc_platform_big_picture.css new file mode 100644 index 0000000..7de4e5b --- /dev/null +++ b/strategy/doc_platform_big_picture.css @@ -0,0 +1,867 @@ +/* PowerON Platform Big Picture Documentation Styles */ + +/* Base Styles */ +* { + margin: 0; + padding: 0; + box-sizing: border-box; +} + +body { + font-family: 'DM Sans', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; + line-height: 1.6; + color: #1a1a1a; + background-color: #ffffff; + margin: 0; + padding: 0; +} + +/* Header */ +.header { + background: rgba(255, 255, 255, 0.95); + backdrop-filter: blur(10px); + border-bottom: 1px solid rgba(0, 0, 0, 0.1); + position: fixed; + top: 0; + left: 0; + right: 0; + z-index: 1000; + padding: 1rem 0; + box-shadow: 0 2px 8px rgba(0, 0, 0, 0.05); +} + +.navbar { + max-width: 1400px; + margin: 0 auto; + padding: 0 2rem; + display: flex; + justify-content: space-between; + align-items: center; +} + +.logo { + display: flex; + align-items: center; + gap: 0.75rem; + text-decoration: none; + transition: opacity 0.3s ease; +} + +.logo:hover { + opacity: 0.8; +} + +.logo-img { + height: 32px; + width: auto; + display: inline-block; +} + +.logo-text { + font-size: 1.5rem; + font-weight: 700; + color: #1a1a1a; + transition: color 0.3s ease; +} + +.logo:hover .logo-text { + color: #4B73FF; +} + +.nav-title { + font-size: 0.9rem; + color: #666; + font-weight: 500; +} + +/* Container */ +.container { + max-width: 1400px; + margin: 0 auto; + padding: 0 2rem; + padding-top: 100px; +} + +/* Hero Section */ +.hero { + text-align: center; + padding: 3rem 0; + margin-bottom: 3rem; +} + +.hero h1 { + font-size: 3rem; + font-weight: 700; + margin-bottom: 1rem; + color: #1a1a1a; +} + +.subtitle { + font-size: 1.25rem; + color: #666; + margin-bottom: 1rem; + font-weight: 500; +} + +.intro { + font-size: 1.1rem; + color: #555; + max-width: 800px; + margin: 0 auto; + line-height: 1.8; +} + +.lead { + font-size: 1.15rem; + font-weight: 500; + color: #333; + margin-bottom: 1.5rem; + line-height: 1.8; +} + +/* Tabs */ +.tabs { + display: flex; + gap: 0.5rem; + margin-bottom: 2rem; + border-bottom: 2px solid #e5e5e5; + overflow-x: auto; +} + +.tab-button { + background: none; + border: none; + padding: 1rem 1.5rem; + font-size: 1rem; + font-weight: 500; + color: #666; + cursor: pointer; + border-bottom: 3px solid transparent; + transition: all 0.3s ease; + white-space: nowrap; + font-family: 'DM Sans', sans-serif; +} + +.tab-button:hover { + color: #1a1a1a; + background-color: #f8f9fa; +} + +.tab-button.active { + color: #4B73FF; + border-bottom-color: #4B73FF; +} + +/* Tab Content */ +.tab-content { + display: none; + animation: fadeIn 0.3s ease; +} + +.tab-content.active { + display: block; +} + +@keyframes fadeIn { + from { + opacity: 0; + transform: translateY(10px); + } + to { + opacity: 1; + transform: translateY(0); + } +} + +/* Sections */ +.section { + margin-bottom: 3rem; +} + +.section h2 { + font-size: 2.5rem; + font-weight: 700; + margin-bottom: 2rem; + color: #1a1a1a; + border-bottom: 3px solid #4B73FF; + padding-bottom: 0.5rem; +} + +.section h3 { + font-size: 1.75rem; + font-weight: 600; + margin-bottom: 1rem; + color: #1a1a1a; + margin-top: 2rem; +} + +.section h4 { + font-size: 1.25rem; + font-weight: 600; + margin-bottom: 0.75rem; + color: #333; +} + +.section p { + margin-bottom: 1rem; + line-height: 1.8; + color: #555; +} + +.section ul, .section ol { + margin-left: 1.5rem; + margin-bottom: 1.5rem; + line-height: 1.8; +} + +.section li { + margin-bottom: 0.5rem; + color: #555; +} + +.section code { + background-color: #f4f4f4; + padding: 0.2rem 0.4rem; + border-radius: 4px; + font-family: 'Courier New', monospace; + font-size: 0.9em; + color: #d63384; +} + +.section pre { + background-color: #f8f9fa; + padding: 1.5rem; + border-radius: 8px; + overflow-x: auto; + margin: 1.5rem 0; + border-left: 4px solid #4B73FF; +} + +.section pre code { + background: none; + padding: 0; + color: #333; +} + +/* Highlight Box */ +.highlight-box { + background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); + color: #ffffff; + padding: 2rem; + border-radius: 12px; + margin: 2rem 0; + box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1); +} + +.highlight-box h4 { + color: #ffffff; + margin-bottom: 1rem; + font-size: 1.5rem; +} + +.highlight-box ul { + list-style: none; + margin-left: 0; +} + +.highlight-box li { + margin-bottom: 0.75rem; + padding-left: 1.5rem; + position: relative; + color: #ffffff; +} + +.highlight-box li strong { + color: #ffffff; + font-weight: 600; +} + +.highlight-box li::before { + content: "✓"; + position: absolute; + left: 0; + font-weight: bold; + color: #ffffff; +} + +/* Architecture Diagram */ +.architecture-diagram { + display: flex; + flex-direction: column; + gap: 1rem; + margin: 2rem 0; +} + +.layer { + background: #f8f9fa; + padding: 1.5rem; + border-radius: 8px; + border-left: 4px solid #4B73FF; + transition: transform 0.3s ease, box-shadow 0.3s ease; +} + +.layer:hover { + transform: translateX(5px); + box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1); +} + +.layer h4 { + color: #4B73FF; + margin-bottom: 0.5rem; +} + +/* Workflow Structure */ +.workflow-structure { + display: grid; + grid-template-columns: repeat(auto-fit, minmax(250px, 1fr)); + gap: 1.5rem; + margin: 2rem 0; +} + +.workflow-item { + background: #f8f9fa; + padding: 1.5rem; + border-radius: 8px; + border-top: 4px solid #4B73FF; +} + +.workflow-item h4 { + color: #4B73FF; + margin-bottom: 0.5rem; +} + +/* Mode Grid */ +.mode-grid { + display: grid; + grid-template-columns: repeat(auto-fit, minmax(280px, 1fr)); + gap: 1.5rem; + margin: 2rem 0; +} + +.mode-card { + background: white; + border: 2px solid #e5e5e5; + padding: 1.5rem; + border-radius: 8px; + transition: all 0.3s ease; +} + +.mode-card:hover { + border-color: #4B73FF; + box-shadow: 0 4px 12px rgba(75, 115, 255, 0.1); +} + +.mode-card h4 { + color: #4B73FF; + margin-bottom: 0.75rem; +} + +/* Services Tree */ +.services-tree { + margin: 2rem 0; +} + +.service-category { + background: #f8f9fa; + padding: 1.5rem; + border-radius: 8px; + margin-bottom: 1.5rem; + border-left: 4px solid #4B73FF; +} + +.service-category h4 { + color: #4B73FF; + margin-bottom: 1rem; + font-size: 1.3rem; +} + +.service-category ul { + list-style: none; + margin-left: 0; +} + +.service-category > ul > li { + margin-bottom: 1rem; + font-weight: 500; + color: #333; +} + +.service-category ul ul { + margin-left: 1.5rem; + margin-top: 0.5rem; +} + +.service-category ul ul li { + font-weight: normal; + color: #666; + font-size: 0.95em; +} + +/* Access Levels */ +.access-levels { + display: grid; + grid-template-columns: repeat(auto-fit, minmax(200px, 1fr)); + gap: 1rem; + margin: 2rem 0; +} + +.access-level { + background: white; + border: 2px solid #e5e5e5; + padding: 1.5rem; + border-radius: 8px; + text-align: center; + transition: all 0.3s ease; +} + +.access-level:hover { + border-color: #4B73FF; + transform: translateY(-2px); + box-shadow: 0 4px 12px rgba(75, 115, 255, 0.1); +} + +.access-level h4 { + color: #4B73FF; + margin-bottom: 0.5rem; + font-size: 1.1rem; +} + +.access-level p { + font-size: 0.9em; + color: #666; + margin: 0; +} + +/* Context Grid */ +.context-grid { + display: grid; + grid-template-columns: repeat(auto-fit, minmax(250px, 1fr)); + gap: 1.5rem; + margin: 2rem 0; +} + +.context-card { + background: white; + border: 2px solid #e5e5e5; + padding: 1.5rem; + border-radius: 8px; + transition: all 0.3s ease; +} + +.context-card:hover { + border-color: #4B73FF; + box-shadow: 0 4px 12px rgba(75, 115, 255, 0.1); +} + +.context-card h4 { + color: #4B73FF; + margin-bottom: 0.75rem; + font-size: 1.3rem; +} + +.context-card code { + background-color: #f4f4f4; + padding: 0.2rem 0.4rem; + border-radius: 4px; + font-family: 'Courier New', monospace; + font-size: 0.9em; + color: #d63384; +} + +/* Building Blocks */ +.building-blocks { + display: grid; + grid-template-columns: repeat(auto-fit, minmax(250px, 1fr)); + gap: 1.5rem; + margin: 2rem 0; +} + +.block { + background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); + color: white; + padding: 1.5rem; + border-radius: 8px; + transition: transform 0.3s ease, box-shadow 0.3s ease; +} + +.block:hover { + transform: translateY(-5px); + box-shadow: 0 8px 20px rgba(0, 0, 0, 0.15); +} + +.block h4 { + color: white; + margin-bottom: 0.75rem; +} + +.block p { + color: rgba(255, 255, 255, 0.9); + margin: 0; +} + +/* Footer */ +.footer { + background: #1a1a1a; + color: white; + padding: 2rem 0; + text-align: center; + margin-top: 4rem; +} + +.footer p { + margin: 0.5rem 0; + color: rgba(255, 255, 255, 0.7); +} + +/* Responsive Design */ +@media (max-width: 768px) { + .hero h1 { + font-size: 2rem; + } + + .subtitle { + font-size: 1.1rem; + } + + .section h2 { + font-size: 2rem; + } + + .tabs { + flex-wrap: nowrap; + overflow-x: auto; + -webkit-overflow-scrolling: touch; + } + + .tab-button { + padding: 0.75rem 1rem; + font-size: 0.9rem; + } + + .container { + padding: 0 1rem; + padding-top: 90px; + } + + .architecture-diagram, + .workflow-structure, + .mode-grid, + .access-levels, + .context-grid, + .building-blocks, + .feature-grid, + .transformation-comparison, + .vision-grid { + grid-template-columns: 1fr; + } + + .step-card { + flex-direction: column; + gap: 1rem; + } + + .diagram-box { + min-width: 100%; + } +} + +/* Feature Grid */ +.feature-grid { + display: grid; + grid-template-columns: repeat(auto-fit, minmax(300px, 1fr)); + gap: 1.5rem; + margin: 2rem 0; +} + +.feature-card { + background: white; + border: 2px solid #e5e5e5; + padding: 1.5rem; + border-radius: 8px; + transition: all 0.3s ease; +} + +.feature-card:hover { + border-color: #4B73FF; + box-shadow: 0 4px 12px rgba(75, 115, 255, 0.1); +} + +.feature-card h4 { + color: #4B73FF; + margin-bottom: 0.75rem; +} + +/* System Diagram */ +.system-diagram { + margin: 2rem 0; + padding: 2rem; + background: #f8f9fa; + border-radius: 12px; +} + +.diagram-row { + display: flex; + justify-content: center; + margin-bottom: 1rem; +} + +.diagram-box { + background: white; + border: 3px solid #4B73FF; + border-radius: 8px; + padding: 1.5rem; + min-width: 400px; + max-width: 800px; + width: 100%; +} + +.diagram-box.customer { + border-color: #28a745; + background: linear-gradient(135deg, #f0fff4 0%, #ffffff 100%); +} + +.diagram-box.platform { + border-color: #4B73FF; + background: linear-gradient(135deg, #f0f4ff 0%, #ffffff 100%); +} + +.diagram-box h4 { + color: #4B73FF; + margin-bottom: 1rem; + text-align: center; + font-size: 1.3rem; +} + +.diagram-box.customer h4 { + color: #28a745; +} + +.diagram-items { + display: flex; + flex-direction: column; + gap: 0.75rem; +} + +.diagram-item { + background: #f8f9fa; + padding: 0.75rem 1rem; + border-radius: 6px; + border-left: 3px solid #4B73FF; + font-size: 0.95em; + color: #333; +} + +.diagram-box.customer .diagram-item { + border-left-color: #28a745; +} + +.diagram-arrow { + text-align: center; + padding: 1rem; + font-weight: 600; + color: #666; + font-size: 1.1rem; +} + +/* Customer Story Steps */ +.step-card { + display: flex; + gap: 2rem; + background: white; + border: 2px solid #e5e5e5; + border-radius: 12px; + padding: 2rem; + margin: 2rem 0; + transition: all 0.3s ease; +} + +.step-card:hover { + border-color: #4B73FF; + box-shadow: 0 4px 12px rgba(75, 115, 255, 0.1); +} + +.step-number { + flex-shrink: 0; + width: 60px; + height: 60px; + background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); + color: white; + border-radius: 50%; + display: flex; + align-items: center; + justify-content: center; + font-size: 2rem; + font-weight: 700; +} + +.step-content { + flex: 1; +} + +.step-content h4 { + color: #4B73FF; + margin-bottom: 0.75rem; + font-size: 1.5rem; +} + +.step-content ul { + margin-top: 1rem; +} + +.lead { + font-size: 1.2rem; + font-weight: 500; + color: #333; + margin-bottom: 2rem; + line-height: 1.8; +} + +.highlight-text { + background: #fff3cd; + padding: 1rem; + border-left: 4px solid #ffc107; + border-radius: 4px; + margin-top: 1rem; + font-weight: 500; + color: #856404; +} + +/* Transformation Comparison */ +.transformation-comparison { + display: grid; + grid-template-columns: repeat(auto-fit, minmax(300px, 1fr)); + gap: 1.5rem; + margin: 2rem 0; +} + +.comparison-box { + padding: 1.5rem; + border-radius: 8px; + border: 2px solid; +} + +.comparison-box.old { + background: #fff5f5; + border-color: #fc8181; +} + +.comparison-box.new { + background: #f0fff4; + border-color: #28a745; +} + +.comparison-box h5 { + margin-bottom: 1rem; + font-size: 1.2rem; +} + +.comparison-box.old h5 { + color: #c53030; +} + +.comparison-box.new h5 { + color: #22543d; +} + +.comparison-box ul { + margin-left: 1.5rem; +} + +.comparison-box li { + margin-bottom: 0.5rem; +} + +/* Vision Cards */ +.vision-card { + background: white; + border: 2px solid #e5e5e5; + border-left: 4px solid #4B73FF; + padding: 2rem; + border-radius: 8px; + margin: 2rem 0; + transition: all 0.3s ease; +} + +.vision-card:hover { + border-color: #4B73FF; + box-shadow: 0 4px 12px rgba(75, 115, 255, 0.1); +} + +.vision-card h4 { + color: #4B73FF; + margin-bottom: 1rem; + font-size: 1.4rem; +} + +.vision-grid { + display: grid; + grid-template-columns: repeat(auto-fit, minmax(250px, 1fr)); + gap: 1.5rem; + margin: 2rem 0; +} + +.vision-item { + background: #f8f9fa; + padding: 1.5rem; + border-radius: 8px; + border-top: 4px solid #4B73FF; +} + +.vision-item h4 { + color: #4B73FF; + margin-bottom: 1rem; +} + +.vision-item ul { + margin-left: 1.5rem; +} + +/* Diagram Images */ +.diagram-image-container { + margin: 2rem 0; + text-align: center; + background: #f8f9fa; + padding: 2rem; + border-radius: 8px; + border: 1px solid #e0e0e0; +} + +.diagram-image { + max-width: 100%; + height: auto; + border-radius: 4px; + box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1); + transition: transform 0.3s ease, box-shadow 0.3s ease; +} + +.diagram-image:hover { + transform: scale(1.02); + box-shadow: 0 6px 20px rgba(0, 0, 0, 0.15); +} + +@media (max-width: 768px) { + .diagram-image-container { + padding: 1rem; + } + + .diagram-image { + width: 100%; + } +} + +/* Print Styles */ +@media print { + .header, + .footer, + .tabs { + display: none; + } + + .container { + padding-top: 0; + } + + .tab-content { + display: block !important; + } +} diff --git a/strategy/doc_platform_big_picture.html b/strategy/doc_platform_big_picture.html new file mode 100644 index 0000000..684e5c5 --- /dev/null +++ b/strategy/doc_platform_big_picture.html @@ -0,0 +1,799 @@ + + + + + + + PowerOn Platform - Big Picture | PowerON + + + + + + + + + + + + +
+
+ + +
+
+ +
+
+

PowerOn Platform - Big Picture

+

Enterprise AI Workflow Platform with Integrated Data Privacy Neutralizer

+

This document provides an overview of the PowerOn platform architecture, building blocks, and capabilities for external software developers who want to contribute to or integrate with the platform.

+
+ + +
+ + + + + + + + +
+ + +
+

Platform Overview

+ +
+

Core Concept

+

PowerOn is a Multi-Agent AI Platform for Enterprise Workflows with an integrated data privacy neutralizer. The platform enables companies to accelerate their AI transformation without data privacy risks.

+ +
+

Key Value Propositions

+
    +
  • Data Privacy First: Integrated privacy neutralizer enables safe use of ChatGPT/Copilot without privacy risks
    • +
  • Unlimited Processing: No token limits - process documents of any size through intelligent chunking
    • +
  • Universal Integration: Seamless integration of all enterprise data sources
    • +
  • Workflow Automation: Configure workflows per customer journey with standard automation elements and AI components
    • +
  • Future-Proof Architecture: Automatically improves with better AI models and larger token limits
    • +
  • Plug & Play Architecture: Renderers and dynamic AI selection per intention (analyze, generate, web, plan, etc.)
    • +
+
+
+ +
+

Architecture Layers

+
+
+

UI Layer (Playground)

+

React-based playground UI as entry point. Additional UIs (chatbots, customer UIs) can be easily integrated via REST API in React, JavaScript, or other languages.

+
+
+

API Layer

+

RESTful API providing full access to platform capabilities. Open API design allows external UIs and integrations.

+
+
+

Workflow Engine

+

Core orchestration engine managing tasks, actions, and state. Supports multiple execution modes (Learning, Actionplan, Automation).

+
+
+

Microservices Layer

+

Modular service architecture with specialized services for AI, data processing, security, and integrations.

+
+
+

Data Layer

+

Multi-tenant database with RBAC-based access control. Mandate isolation ensures secure data separation.

+
+
+
+ +
+

Customer Journey → Workflow

+

For each customer journey, a workflow can be configured in the workflow editor where:

+
    +
  • Customers integrate their data sources
    • +
  • Standard automation elements are available
    • +
  • AI components can be used
    • +
  • Workflows can be executed manually or automated (hourly/daily/weekly)
    • +
+
+ +
+

Plug & Play Architecture

+
+
+

Dynamic Renderers

+

Plug & play architecture for document renderers. Support for multiple formats (PDF, DOCX, XLSX, PPTX, HTML, Markdown, JSON, CSV, etc.) with easy extension capabilities.

+
+
+

Dynamic AI Selection

+

Intelligent AI model selection per intention type. The system automatically selects the best AI model based on the task: analysis, generation, web research, planning, etc.

+
+
+
+ +
+

System Architecture Diagram

+
+ PowerON Platform Architecture Diagram +
+
+
+ +
+

Customer Story

+ +
+

The Journey from Application-Centric to Data-Centric Work

+

PowerOn enables customers to transition from application-centric to data-centric work. This is a key differentiator that transforms how businesses operate.

+
+ +
+

Step 1: Customer Journey Identification

+
+
1
+
+

Identify Business Processes

+

Work with customers to identify their key customer journeys and business processes that can benefit from automation and AI.

+
    +
  • Document analysis workflows
    • +
  • Email processing and routing
    • +
  • Data extraction and transformation
    • +
  • Report generation
    • +
  • Customer communication workflows
    • +
+
+
+
+ +
+

Step 2: MVP Integration with Focus on Data Privacy & Compliance

+
+
2
+
+

Simple MVP Integration

+

Start with a simple MVP that integrates customer data sources with strong focus on data privacy and compliance:

+
    +
  • Data Privacy Neutralizer: Automatic anonymization of sensitive data before AI processing
    • +
  • Compliance First: DSGVO/GDPR compliant processing from day one
    • +
  • Secure Connections: Encrypted connections to customer data sources (SharePoint, Google Drive, Outlook, etc.)
    • +
  • Mandate Isolation: Complete data separation between tenants
    • +
  • Audit Logging: Full traceability of all data access and processing
    • +
+

This step builds trust and demonstrates the platform's commitment to data security.

+
+
+
+ +
+

Step 3: Pre-Processing Engine Deployment

+
+
3
+
+

Standard API Pre-Processing

+

Deploy a pre-processing engine at the customer's location using a standard API:

+
    +
  • On-Premise/Edge Processing: Data processing happens at the customer's location
    • +
  • Standard API: Consistent interface for all customers
    • +
  • Data Minimization: Only necessary data is sent to the platform
    • +
  • Local Neutralization: Privacy neutralization can happen before data leaves customer premises
    • +
  • Reduced Latency: Faster processing for large documents
    • +
+

This step further enhances data privacy and gives customers full control over their data processing.

+
+
+
+ +
+

Step 4: Gradual Component Integration - The Transformation

+
+
4
+
+

From Application-Centric to Data-Centric

+

Gradually integrate additional components until the customer works data-centrically instead of application-centrically:

+ +
+
+
❌ Application-Centric (Old Way)
+
    +
  • Work within individual applications (Word, Excel, SharePoint, Outlook)
    • +
  • Manual data transfer between applications
    • +
  • Data silos in different systems
    • +
  • Workflows are application-bound
    • +
  • Difficult to automate across applications
    • +
+
+
+
✅ Data-Centric (PowerOn Way)
+
    +
  • Work with data directly, regardless of source application
    • +
  • Automatic data integration across all sources
    • +
  • Unified data view across all systems
    • +
  • Workflows span multiple applications seamlessly
    • +
  • Easy automation across entire data ecosystem
    • +
+
+
+ +

This transformation is a KEY DIFFERENTIATOR! Customers no longer think in terms of applications, but in terms of their data and business processes.

+
+
+
+ +
+

Customer Journey Diagram

+
+ Customer Story - Journey from Application-Centric to Data-Centric +
+
+
+ +
+

Workflow System

+ +
+

Core Concept: Tasks with Actions

+

The core building block is workflow elements: tasks with actions. Each workflow consists of tasks, and each task contains one or more actions that execute specific operations.

+ +
+
+

Workflow

+

Definition: Top-level container representing a complete customer journey or business process.

+

Purpose: Orchestrates multiple tasks to achieve a business goal.

+
+
+

Task

+

Definition: A logical step in the workflow.

+

Purpose: Groups related actions that work together to complete a sub-goal.

+
+
+

Action

+

Definition: Executable unit that performs a specific operation.

+

Purpose: Actions belong to methods (microservices) and are the atomic units of work.

+
+
+
+ +
+

Execution Modes

+

PowerOn supports three execution modes, each optimized for different use cases:

+
+
+

Learning Mode

+

Best for: Exploratory tasks with up to 5 steps

+

Approach: Iterative Plan-Act-Observe-Refine loop

+

Use Case: When the solution path is not fully known in advance

+
+
+

Actionplan Mode

+

Best for: Structured, sequential processes

+

Approach: Batch planning with sequential execution

+

Use Case: When the workflow steps are well-defined

+
+
+

Automation Mode

+

Best for: Repetitive, predefined workflows

+

Approach: Automated execution (scheduled or event-triggered)

+

Use Case: Production workflows that run automatically

+
+
+
+ +
+

Available Workflow Methods

+

Workflow methods provide actions that can be executed within workflows. Each method exposes multiple actions accessible via self.services.<method>.<action>:

+
    +
  • ai.* - AI operations (process, analyze, generate)
    • +
  • sharepoint.* - SharePoint integration (search, read, upload)
    • +
  • outlook.* - Outlook integration (read emails, send emails)
    • +
  • context.* - Context management (get context, set context)
    • +
+
+ +
+

Workflow System Diagram

+
+ Workflow System - Structure, Execution Modes, and Available Methods +
+
+
+ +
+

Microservices Architecture

+ +
+

Service Access Pattern

+

All microservices are accessible via self.services.<serviceName>. Services follow a consistent access pattern and are organized into logical categories.

+
+ +
+

Services Structure Tree

+

Complete overview of all available microservices:

+ +
+
+

Core Services

+
    +
  • self.services.chat - Chat and conversation management +
      +
    • Progress logging
      • +
    • Document management
      • +
    • Connection handling
      • +
    +
    • +
  • self.services.workflow - Workflow state and management
    • +
  • self.services.utils - Utility functions (timestamps, formatting, etc.)
    • +
+
+ +
+

AI & Processing Services

+
    +
  • self.services.ai - AI model management and operations +
      +
    • Model selection
      • +
    • Prompt processing
      • +
    • Response handling
      • +
    +
    • +
  • self.services.generation - Document generation +
      +
    • Multiple formats (PDF, DOCX, XLSX, PPTX, HTML, Markdown, etc.)
      • +
    • Template-based rendering
      • +
    • JSON schema support
      • +
    +
    • +
  • self.services.extraction - Document extraction and processing +
      +
    • Multiple extractors (PDF, DOCX, XLSX, PPTX, CSV, HTML, XML, JSON, Images, etc.)
      • +
    • Intelligent chunking
      • +
    • Merging strategies
      • +
    +
    • +
  • self.services.neutralization - Data privacy neutralization +
      +
    • PII detection and anonymization
      • +
    • Pattern-based neutralization
      • +
    • Binary and text processing
      • +
    +
    • +
+
+ +
+

Integration Services

+
    +
  • self.services.sharepoint - SharePoint integration +
      +
    • Site discovery
      • +
    • File operations (read, upload, search)
      • +
    • Path resolution
      • +
    +
    • +
  • self.services.web - Web operations +
      +
    • HTTP requests
      • +
    • Web scraping
      • +
    • API integration
      • +
    +
    • +
  • self.services.ticket - Ticket system integration +
      +
    • Jira integration
      • +
    • ClickUp integration
      • +
    • Generic ticket operations
      • +
    +
    • +
+
+ +
+

Security & Infrastructure

+
    +
  • self.services.security - Security operations +
      +
    • Authentication
      • +
    • Authorization
      • +
    • Token management
      • +
    +
    • +
+
+
+
+ +
+

Code Examples

+

Examples of how to use services in workflow actions or methods:

+ 
# In workflow actions or methods
+result = await self.services.<service>.<method>(parameters)
+
+# Example: Using AI service
+response = await self.services.ai.process(prompt="Analyze this document", documents=[...])
+
+# Example: Using SharePoint service
+files = await self.services.sharepoint.searchFiles(pathQuery="sites/my-site/documents")
+
+# Example: Using generation service
+document = self.services.generation.createDocument(format="pdf", content={...})
+
+ +
+

Microservices Architecture Diagram

+
+ Microservices Architecture - Core Services, AI & Processing, Integration Services, and Security +
+
+
+ +
+

RBAC System

+ +
+

Overview

+

The Role-Based Access Control (RBAC) system provides complete UI configuration per tenant and user. It enables fine-grained control over data access, UI visibility, and resource availability.

+ +
+
+

Data Access

+

Table and field-level permissions for database operations. Control who can read, create, update, or delete specific data.

+
+
+

UI Access

+

Component and feature visibility management. Configure exactly which UI elements each user or role can see.

+
+
+

Resource Access

+

System resource availability control. Manage access to AI models, actions, and other platform resources.

+
+
+
+ +
+

Access Levels: Opening Logic

+

For DATA context, the system uses opening rights with four access levels. These levels determine what data a user can access:

+
+
+

none (n)

+

No access - item is completely hidden/disabled

+
+
+

my (m)

+

My records - only records created by the current user

+
+
+

group (g)

+

Group records - records within the same mandate (group context)

+
+
+

all (a)

+

All records - full access to all records in the mandate

+
+
+
+ +
+

View Logic: Open + Close

+

The view attribute controls visibility and enablement. This is the fundamental on/off switch for all RBAC contexts:

+
    +
  • view: true - Item is visible/enabled
    • +
  • view: false - Item is hidden/disabled (regardless of other permissions)
    • +
+

Key Rule: Only objects with view: true are shown. This applies to:

+
    +
  • DATA Context: Controls whether tables/fields are accessible
    • +
  • UI Context: Controls whether UI elements are visible
    • +
  • RESOURCE Context: Controls whether resources are available
    • +
+
+ +
+

Rule Specificity & Hierarchy

+

The RBAC system uses a cascading hierarchy where more specific rules override generic ones:

+
    +
  1. Generic Rules (item = null) - Apply to all items in context
    2. +
  2. Specific Rules (item = "table.field" or item = "ui.component.feature") - Override generic rules
    3. +
+

Resolution Logic: Within a single role, the most specific rule wins. Across multiple roles, opening (union) logic applies - if ANY role enables something, it is enabled.

+
+ +
+

Opening Rights Principle

+

For DATA context, read permission (R) is a prerequisite for create/update/delete operations (CUD). This ensures data integrity and proper access control:

+
    +
  • If Read = "n": No CUD operations allowed
    • +
  • If Read = "m": CUD operations limited to "m" or "n"
    • +
  • If Read = "g": CUD operations limited to "g", "m", or "n"
    • +
  • If Read = "a": CUD operations can be "a", "g", "m", or "n"
    • +
+

Key Rule: You can ONLY create/update/delete if you have read right.

+
+ +
+

Context Types

+

RBAC rules apply to three different context types, each serving a specific purpose:

+
+
+

DATA

+

Database tables and fields. Controls read/create/update/delete permissions.

+

Example: item: "UserInDB.email"

+
+
+

UI

+

UI elements and features. Controls component visibility.

+

Example: item: "playground.voice.settings"

+
+
+

RESOURCE

+

System resources (AI models, actions, etc.). Controls resource availability.

+

Example: item: "ai.model.anthropic"

+
+
+
+ +
+

RBAC System Diagram

+
+ RBAC System - Contexts, Access Levels, View Logic, and Rule Hierarchy +
+
+
+ +
+

UI Architecture

+ +
+

Playground UI

+

The Playground serves as the main entry point and demonstration UI. It's built with React and provides a comprehensive interface for workflow interaction:

+
    +
  • Chat interface for workflow interaction
    • +
  • Workflow editor for configuration
    • +
  • Document management
    • +
  • Connection management
    • +
  • Voice input/output capabilities
    • +
+
+ +
+

RBAC-Driven UI Configuration

+

The UI is completely configurable via RBAC rules. This allows customers to configure exactly the UI they need for their use case:

+
    +
  • Per tenant configuration
    • +
  • Per user configuration
    • +
  • Component-level visibility control
    • +
  • Feature-level access control
    • +
+

This allows customers to configure exactly the UI they need for their use case.

+
+ +
+

External UI Integration

+

Additional UIs can be easily integrated via the REST API. All UI components communicate with the platform through the standardized REST API, ensuring consistent behavior and security:

+
    +
  • Chatbots: Build custom chatbots using the workflow API
    • +
  • Customer UIs: Create customer-specific interfaces in React, JavaScript, or other languages
    • +
  • Mobile Apps: Integrate via REST API from mobile applications
    • +
  • Third-Party Tools: Connect existing tools via webhooks and API
    • +
+

All UI components communicate with the platform through the standardized REST API, ensuring consistent behavior and security.

+
+ +
+

Available UI Components

+

The platform provides reusable UI components that can be configured via RBAC:

+
    +
  • Chat interface
    • +
  • Document viewer/editor
    • +
  • Workflow editor
    • +
  • Connection manager
    • +
  • Settings panels
    • +
  • Dashboard widgets
    • +
+
+ +
+

UI Architecture Diagram

+
+ UI Architecture - RBAC-Driven Configuration, UI Components, UI Layer, and REST API +
+
+
+ +
+

Big Picture & Future Vision

+ +
+

Vendor-Independent Platform

+
+

AI Model Independence

+

PowerOn is designed as a vendor-independent platform regarding AI models:

+
    +
  • Support for multiple AI providers (OpenAI, Anthropic, Google, Azure, etc.)
    • +
  • Dynamic model selection based on task requirements
    • +
  • Easy addition of new AI providers
    • +
  • No vendor lock-in - customers can switch providers seamlessly
    • +
+
+ +
+

Connector Independence

+

Universal connector architecture supporting all major platforms:

+
    +
  • Microsoft: SharePoint, Outlook, Teams, OneDrive, Azure
    • +
  • Google: Drive, Gmail, Workspace, Cloud
    • +
  • Amazon: AWS services, S3, etc.
    • +
  • Other: Jira, Slack, Salesforce, and many more
    • +
+

Customers are not locked into a single vendor ecosystem.

+
+
+ +
+

Graphical Workflow Modeling

+
+

Visual Customer Journey Design

+

Future capability to graphically model workflows for customer journeys:

+
    +
  • Drag-and-drop workflow editor
    • +
  • Visual representation of customer journeys
    • +
  • Easy workflow modification without coding
    • +
  • Template library for common workflows
    • +
  • Workflow versioning and testing
    • +
+

This makes workflow creation accessible to business users, not just developers.

+
+
+ +
+

MCP Integration in Customer Copilot

+
+

Microsoft Copilot Plugin Architecture

+

Integration of PowerOn actions as MCP (Model Context Protocol) plugins in the customer's Copilot:

+
    +
  • Native Copilot Integration: PowerOn workflows accessible directly from Microsoft Copilot
    • +
  • Action Library: All PowerOn actions available as Copilot plugins
    • +
  • Seamless Experience: Customers use PowerOn capabilities without leaving Copilot
    • +
  • Enterprise Workflows: Complex workflows triggered from simple Copilot conversations
    • +
  • Data Privacy: All PowerOn privacy features work seamlessly in Copilot context
    • +
+

This enables customers to leverage PowerOn's powerful workflow capabilities directly from their familiar Copilot interface.

+
+
+ +
+

Platform Evolution

+
+
+

Today

+
    +
  • REST API-based workflows
    • +
  • Playground UI
    • +
  • Multiple AI providers
    • +
  • Standard connectors
    • +
+
+
+

Near Future

+
    +
  • Graphical workflow editor
    • +
  • MCP Copilot integration
    • +
  • Enhanced pre-processing
    • +
  • Advanced AI selection
    • +
+
+
+

Future

+
    +
  • AI-powered workflow generation
    • +
  • Multi-platform Copilot support
    • +
  • Edge computing expansion
    • +
  • Federated learning
    • +
+
+
+
+ +
+

Big Picture & Future Vision Diagram

+
+ Big Picture & Future Vision - Platform Evolution from Today to Future +
+
+
+ +
+

Integration Guide

+ +
+

REST API

+

The platform exposes a comprehensive REST API for all operations. This API serves as the primary integration point for external developers:

+
    +
  • Workflow API: Create, execute, and manage workflows
    • +
  • Document API: Upload, download, and process documents
    • +
  • Connection API: Manage external connections (SharePoint, Outlook, etc.)
    • +
  • RBAC API: Manage roles and permissions
    • +
  • Options API: Dynamic options for UI components
    • +
+
+ +
+

Building Blocks for Developers

+

Developers can extend the platform by creating custom components in these areas:

+
+
+

Workflow Methods

+

Create custom workflow methods by extending MethodBase and registering actions.

+
+
+

Services

+

Extend the services layer by creating new service modules following the existing pattern.

+
+
+

Connectors

+

Build connectors for external systems (databases, APIs, services) using the connector interface.

+
+
+

UI Components

+

Create React components that integrate with the REST API and respect RBAC rules.

+
+
+
+ +
+

Development Workflow

+

Follow these steps to get started with platform development:

+
    +
  1. Understand the Architecture: Review this document and codebase structure
    2. +
  2. Set Up Development Environment: Clone repository and configure local environment
    3. +
  3. Choose Integration Point: Decide whether to extend workflows, services, or UI
    4. +
  4. Follow Patterns: Use existing code as reference for consistent implementation
    5. +
  5. Test with RBAC: Ensure your changes respect RBAC rules
    6. +
  6. Document: Update documentation for your changes
    7. +
+
+ +
+

Key Integration Points

+

Main directories where developers can add new functionality:

+
    +
  • gateway/modules/workflows/methods/ - Add new workflow methods
    • +
  • gateway/modules/services/ - Add new microservices
    • +
  • gateway/modules/connectors/ - Add new connectors
    • +
  • gateway/modules/routes/ - Add new API endpoints
    • +
  • gateway/modules/features/ - Add new features
    • +
+
+
+
+ +
+
+

© 2025 PowerON. All rights reserved.

+

Platform Architecture Documentation v1.0

+
+
+ + + + diff --git a/strategy/doc_platform_diagrams.md b/strategy/doc_platform_diagrams.md new file mode 100644 index 0000000..24ebc22 --- /dev/null +++ b/strategy/doc_platform_diagrams.md @@ -0,0 +1,484 @@ +# PowerON Platform Architecture Diagrams + +This document contains all Mermaid diagrams visualizing the PowerON platform architecture, components, and workflows. These diagrams can be rendered in any Mermaid-compatible viewer or exported as images for documentation purposes. + +--- + +## 1. Platform Overview + +This diagram shows the overall architecture of the PowerON platform, including the UI layer, API, workflow engine, microservices, and the customer tenant with pre-processing engine. + +```mermaid +graph TB + subgraph "PowerON Platform Architecture" + UI[UI Layer
Playground, Chatbots, Customer UIs] + API[REST API
Open API Design] + WF[Workflow Engine
Tasks & Actions Orchestration] + MS[Microservices Layer
AI, Processing, Integration] + DB[(Multi-Tenant Database
RBAC Access Control)] + end + + subgraph "Customer Tenant" + PRE[Pre-Processing Engine
On-Premise/Edge] + DATA[Customer Data Sources
SharePoint, Outlook, etc.] + end + + subgraph "Plug & Play Components" + RENDER[Dynamic Renderers
PDF, DOCX, XLSX, etc.] + AI_SEL[Dynamic AI Selection
Analysis, Generate, Web, Plan] + end + + UI --> API + API --> WF + WF --> MS + MS --> DB + MS --> RENDER + MS --> AI_SEL + PRE -->|Secure API| API + DATA --> PRE + + style UI fill:#4B73FF,color:#fff + style API fill:#4B73FF,color:#fff + style WF fill:#FF6B6B,color:#fff + style MS fill:#51CF66,color:#fff + style DB fill:#FFD93D,color:#000 + style PRE fill:#A78BFA,color:#fff + style DATA fill:#A78BFA,color:#fff + style RENDER fill:#51CF66,color:#fff + style AI_SEL fill:#51CF66,color:#fff +``` + +--- + +## 2. Customer Story + +This diagram illustrates the customer journey from application-centric to data-centric work, showing the four key steps: identification, MVP integration, pre-processing deployment, and transformation. + +```mermaid +graph LR + subgraph "Step 1: Identification" + ID[Identify Customer Journey
Business Process Analysis] + end + + subgraph "Step 2: MVP Integration" + MVP[MVP Integration
Data Privacy & Compliance Focus] + NEUT[Privacy Neutralizer
DSGVO/GDPR Compliant] + SEC[Secure Connections
Encrypted Data Sources] + end + + subgraph "Step 3: Pre-Processing" + PRE[Pre-Processing Engine
Standard API Deployment] + EDGE[On-Premise/Edge
Local Processing] + end + + subgraph "Step 4: Transformation" + OLD[Application-Centric
❌ Work within Apps
❌ Manual Transfer
❌ Data Silos] + NEW[Data-Centric
✅ Work with Data
✅ Auto Integration
✅ Unified View] + end + + ID --> MVP + MVP --> NEUT + MVP --> SEC + MVP --> PRE + PRE --> EDGE + EDGE --> OLD + OLD -->|Transformation| NEW + + style ID fill:#4B73FF,color:#fff + style MVP fill:#51CF66,color:#fff + style NEUT fill:#FF6B6B,color:#fff + style SEC fill:#FF6B6B,color:#fff + style PRE fill:#A78BFA,color:#fff + style EDGE fill:#A78BFA,color:#fff + style OLD fill:#FFD93D,color:#000 + style NEW fill:#51CF66,color:#fff +``` + +--- + +## 3. Workflow System + +This diagram shows the workflow structure (Workflow → Tasks → Actions), execution modes (Learning, Actionplan, Automation), and available methods. + +```mermaid +graph TB + subgraph "Workflow Structure" + WF[Workflow
Customer Journey] + T1[Task 1] + T2[Task 2] + T3[Task 3] + + A1[Action 1.1] + A2[Action 1.2] + A3[Action 2.1] + A4[Action 3.1] + + WF --> T1 + WF --> T2 + WF --> T3 + + T1 --> A1 + T1 --> A2 + T2 --> A3 + T3 --> A4 + end + + subgraph "Execution Modes" + LM[Learning Mode
Plan-Act-Observe-Refine
Up to 5 steps] + AM[Actionplan Mode
Batch Planning
Sequential Execution] + AUTO[Automation Mode
Scheduled/Event-Triggered
Production Workflows] + end + + subgraph "Available Methods" + AI_M[ai.*
process, analyze, generate] + SP_M[sharepoint.*
search, read, upload] + OUT_M[outlook.*
read, send emails] + CTX_M[context.*
get, set context] + end + + A1 --> AI_M + A2 --> SP_M + A3 --> OUT_M + A4 --> CTX_M + + WF -.->|Mode Selection| LM + WF -.->|Mode Selection| AM + WF -.->|Mode Selection| AUTO + + style WF fill:#4B73FF,color:#fff + style T1 fill:#51CF66,color:#fff + style T2 fill:#51CF66,color:#fff + style T3 fill:#51CF66,color:#fff + style A1 fill:#FFD93D,color:#000 + style A2 fill:#FFD93D,color:#000 + style A3 fill:#FFD93D,color:#000 + style A4 fill:#FFD93D,color:#000 + style LM fill:#A78BFA,color:#fff + style AM fill:#A78BFA,color:#fff + style AUTO fill:#A78BFA,color:#fff +``` + +--- + +## 4. Microservices Architecture + +This diagram shows the complete microservices structure, organized into Core Services, AI & Processing, Integration Services, and Security, with their relationships and dependencies. + +```mermaid +graph TB + subgraph "Core Services" + CHAT[self.services.chat
Chat & Conversation] + WF_SVC[self.services.workflow
Workflow State] + UTILS[self.services.utils
Utilities] + end + + subgraph "AI & Processing" + AI[self.services.ai
AI Model Management] + GEN[self.services.generation
Document Generation
PDF, DOCX, XLSX, etc.] + EXT[self.services.extraction
Document Extraction
Multiple Extractors] + NEUT_SVC[self.services.neutralization
Privacy Neutralization
PII Detection] + end + + subgraph "Integration Services" + SP[self.services.sharepoint
SharePoint Integration] + WEB[self.services.web
Web Operations] + TICKET[self.services.ticket
Jira, ClickUp, etc.] + end + + subgraph "Security" + SEC_SVC[self.services.security
Auth, Authorization
Token Management] + end + + CHAT --> AI + CHAT --> GEN + CHAT --> EXT + WF_SVC --> AI + GEN --> EXT + EXT --> NEUT_SVC + SP --> SEC_SVC + WEB --> SEC_SVC + TICKET --> SEC_SVC + + style CHAT fill:#4B73FF,color:#fff + style WF_SVC fill:#4B73FF,color:#fff + style UTILS fill:#4B73FF,color:#fff + style AI fill:#51CF66,color:#fff + style GEN fill:#51CF66,color:#fff + style EXT fill:#51CF66,color:#fff + style NEUT_SVC fill:#FF6B6B,color:#fff + style SP fill:#A78BFA,color:#fff + style WEB fill:#A78BFA,color:#fff + style TICKET fill:#A78BFA,color:#fff + style SEC_SVC fill:#FFD93D,color:#000 +``` + +--- + +## 5. RBAC System + +This diagram visualizes the Role-Based Access Control system, showing context types (DATA, UI, RESOURCE), access levels (none, my, group, all), view logic, and rule hierarchy. + +```mermaid +graph TB + subgraph "RBAC Contexts" + DATA[DATA Context
Tables & Fields] + UI_CTX[UI Context
Components & Features] + RES[RESOURCE Context
AI Models, Actions] + end + + subgraph "Access Levels - Opening Logic" + N[none - n
No Access] + M[my - m
My Records] + G[group - g
Group Records] + A[all - a
All Records] + end + + subgraph "View Logic" + V_TRUE[view: true
Visible/Enabled] + V_FALSE[view: false
Hidden/Disabled] + end + + subgraph "Rule Hierarchy" + GEN_RULE[Generic Rules
item = null] + SPEC_RULE[Specific Rules
item = 'table.field'] + end + + DATA --> N + DATA --> M + DATA --> G + DATA --> A + + DATA --> V_TRUE + UI_CTX --> V_TRUE + RES --> V_TRUE + + DATA --> V_FALSE + UI_CTX --> V_FALSE + RES --> V_FALSE + + GEN_RULE --> SPEC_RULE + + style DATA fill:#4B73FF,color:#fff + style UI_CTX fill:#51CF66,color:#fff + style RES fill:#A78BFA,color:#fff + style N fill:#FF6B6B,color:#fff + style M fill:#FFD93D,color:#000 + style G fill:#51CF66,color:#fff + style A fill:#4B73FF,color:#fff + style V_TRUE fill:#51CF66,color:#fff + style V_FALSE fill:#FF6B6B,color:#fff + style GEN_RULE fill:#FFD93D,color:#000 + style SPEC_RULE fill:#4B73FF,color:#fff +``` + +--- + +## 6. UI Architecture + +This diagram shows the UI layer structure, RBAC-driven configuration, REST API integration, and available UI components. + +```mermaid +graph TB + subgraph "UI Layer" + PLAY[Playground UI
React-based Main Entry] + CHAT_UI[Chatbots
Custom Chat Interfaces] + CUST_UI[Customer UIs
Tenant-Specific UIs] + end + + subgraph "RBAC-Driven Configuration" + TENANT[Per Tenant
Configuration] + USER[Per User
Configuration] + COMP[Component-Level
Visibility] + FEAT[Feature-Level
Access Control] + end + + subgraph "REST API" + API[REST API
Standardized Interface] + end + + subgraph "UI Components" + CHAT_COMP[Chat Interface] + DOC_COMP[Document Viewer/Editor] + WF_COMP[Workflow Editor] + CONN_COMP[Connection Manager] + SETT_COMP[Settings Panels] + DASH_COMP[Dashboard Widgets] + end + + PLAY --> API + CHAT_UI --> API + CUST_UI --> API + + TENANT --> COMP + USER --> COMP + COMP --> FEAT + + FEAT --> CHAT_COMP + FEAT --> DOC_COMP + FEAT --> WF_COMP + FEAT --> CONN_COMP + FEAT --> SETT_COMP + FEAT --> DASH_COMP + + PLAY --> CHAT_COMP + PLAY --> DOC_COMP + PLAY --> WF_COMP + + style PLAY fill:#4B73FF,color:#fff + style CHAT_UI fill:#51CF66,color:#fff + style CUST_UI fill:#51CF66,color:#fff + style API fill:#FF6B6B,color:#fff + style TENANT fill:#A78BFA,color:#fff + style USER fill:#A78BFA,color:#fff + style COMP fill:#FFD93D,color:#000 + style FEAT fill:#FFD93D,color:#000 +``` + +--- + +## 7. Big Picture & Future Vision + +This diagram shows the platform evolution from today to the future, including vendor independence, graphical workflow modeling, MCP integration, and future capabilities. + +```mermaid +graph TB + subgraph "Vendor Independence" + AI_PROV[AI Providers
OpenAI, Anthropic, Google, Azure] + CONN_PROV[Connectors
Microsoft, Google, Amazon, Others] + end + + subgraph "Today" + REST[REST API Workflows] + PLAY_TODAY[Playground UI] + MULT_AI[Multiple AI Providers] + STD_CONN[Standard Connectors] + end + + subgraph "Near Future" + GRAPH[Graphical Workflow Editor
Drag & Drop] + MCP[MCP Copilot Integration
Microsoft Copilot] + PRE_ENH[Enhanced Pre-Processing] + AI_SEL_ENH[Advanced AI Selection] + end + + subgraph "Future Vision" + AI_WF[AI-Powered Workflow Generation] + MULT_COP[Multi-Platform Copilot Support] + EDGE_EXP[Edge Computing Expansion] + FED_LEARN[Federated Learning] + end + + REST --> GRAPH + PLAY_TODAY --> GRAPH + MULT_AI --> AI_PROV + STD_CONN --> CONN_PROV + + GRAPH --> AI_WF + MCP --> MULT_COP + PRE_ENH --> EDGE_EXP + AI_SEL_ENH --> FED_LEARN + + style AI_PROV fill:#4B73FF,color:#fff + style CONN_PROV fill:#51CF66,color:#fff + style REST fill:#FFD93D,color:#000 + style PLAY_TODAY fill:#FFD93D,color:#000 + style GRAPH fill:#A78BFA,color:#fff + style MCP fill:#A78BFA,color:#fff + style AI_WF fill:#51CF66,color:#fff + style MULT_COP fill:#51CF66,color:#fff + style EDGE_EXP fill:#4B73FF,color:#fff + style FED_LEARN fill:#4B73FF,color:#fff +``` + +--- + +## 8. Integration Guide + +This diagram shows the REST API endpoints, building blocks for developers, integration points in the codebase, and the development workflow. + +```mermaid +graph TB + subgraph "REST API Endpoints" + WF_API[Workflow API
Create, Execute, Manage] + DOC_API[Document API
Upload, Download, Process] + CONN_API[Connection API
SharePoint, Outlook, etc.] + RBAC_API[RBAC API
Roles & Permissions] + OPT_API[Options API
Dynamic UI Options] + end + + subgraph "Building Blocks" + WF_METH[Workflow Methods
Extend MethodBase] + SERVICES[Services
New Service Modules] + CONNECTORS[Connectors
External Systems] + UI_COMP[UI Components
React Components] + end + + subgraph "Integration Points" + WF_DIR[gateway/modules/workflows/methods/] + SVC_DIR[gateway/modules/services/] + CONN_DIR[gateway/modules/connectors/] + ROUTE_DIR[gateway/modules/routes/] + FEAT_DIR[gateway/modules/features/] + end + + subgraph "Development Workflow" + ARCH[Understand Architecture] + SETUP[Set Up Environment] + CHOOSE[Choose Integration Point] + PATTERN[Follow Patterns] + TEST[Test with RBAC] + DOC[Document Changes] + end + + WF_API --> WF_METH + DOC_API --> SERVICES + CONN_API --> CONNECTORS + RBAC_API --> UI_COMP + OPT_API --> UI_COMP + + WF_METH --> WF_DIR + SERVICES --> SVC_DIR + CONNECTORS --> CONN_DIR + UI_COMP --> ROUTE_DIR + UI_COMP --> FEAT_DIR + + ARCH --> SETUP + SETUP --> CHOOSE + CHOOSE --> PATTERN + PATTERN --> TEST + TEST --> DOC + + style WF_API fill:#4B73FF,color:#fff + style DOC_API fill:#4B73FF,color:#fff + style CONN_API fill:#4B73FF,color:#fff + style RBAC_API fill:#4B73FF,color:#fff + style OPT_API fill:#4B73FF,color:#fff + style WF_METH fill:#51CF66,color:#fff + style SERVICES fill:#51CF66,color:#fff + style CONNECTORS fill:#51CF66,color:#fff + style UI_COMP fill:#51CF66,color:#fff + style ARCH fill:#FFD93D,color:#000 + style SETUP fill:#FFD93D,color:#000 + style CHOOSE fill:#FFD93D,color:#000 + style PATTERN fill:#FFD93D,color:#000 + style TEST fill:#FFD93D,color:#000 + style DOC fill:#FFD93D,color:#000 +``` + +--- + +## Usage Notes + +- These diagrams can be rendered in any Mermaid-compatible viewer (e.g., mermaid.live, GitHub, GitLab, VS Code with Mermaid extension) +- To export as images, use a Mermaid renderer or online tool like mermaid.live +- Each diagram corresponds to a tab in the main documentation (`doc_platform_big_picture.html`) +- The color scheme is consistent across all diagrams: + - Blue (#4B73FF): Core/Platform components + - Green (#51CF66): Processing/AI components + - Red (#FF6B6B): Security/Critical components + - Yellow (#FFD93D): Development/Workflow steps + - Purple (#A78BFA): Integration/Customer components + +--- + +*Last updated: 2025* diff --git a/strategy/logo2.png b/strategy/logo2.png new file mode 100644 index 0000000..e7127a4 Binary files /dev/null and b/strategy/logo2.png differ diff --git a/ui_playground/doc_frontend_options_usage.md b/ui_playground/doc_frontend_options_usage.md new file mode 100644 index 0000000..6048911 --- /dev/null +++ b/ui_playground/doc_frontend_options_usage.md @@ -0,0 +1,229 @@ +# Frontend Options Usage Guide + +## Overview + +The `frontend_options` attribute in Pydantic `Field` definitions supports **two formats** for providing options to frontend select/multiselect fields: + +1. **Static List**: Predefined list of options +2. **String Reference**: Dynamic options fetched from the Options API + +## Type System + +The type system is defined in `gateway/modules/shared/frontendOptionsTypes.py`: + +```python +from modules.shared.frontendOptionsTypes import FrontendOptions, OptionItem + +# FrontendOptions is Union[List[OptionItem], str] +# OptionItem is Dict[str, Any] with "value" and "label" keys +``` + +## Format 1: Static List + +Use static lists for fixed, predefined options that don't change based on user context. + +### Example + +```python +from pydantic import Field +from typing import List + +language: str = Field( + default="en", + description="Preferred language", + json_schema_extra={ + "frontend_type": "select", + "frontend_readonly": False, + "frontend_required": True, + "frontend_options": [ + {"value": "en", "label": {"en": "English", "fr": "Anglais"}}, + {"value": "fr", "label": {"en": "Français", "fr": "Français"}}, + {"value": "de", "label": {"en": "Deutsch", "fr": "Allemand"}}, + ] + } +) +``` + +### When to Use Static Lists + +- Options are fixed constants (e.g., enum values) +- Options don't require database queries +- Options are the same for all users +- Options are simple and don't change frequently + +## Format 2: String Reference + +Use string references for dynamic options that come from the database or are context-aware. + +### Example + +```python +from pydantic import Field +from typing import List + +roleLabels: List[str] = Field( + default_factory=list, + description="List of role labels", + json_schema_extra={ + "frontend_type": "multiselect", + "frontend_readonly": False, + "frontend_required": True, + "frontend_options": "user.role" # String reference + } +) +``` + +### When to Use String References + +- Options come from the database (e.g., user connections) +- Options are context-aware (filtered by current user's permissions) +- Options need centralized management +- Options may change frequently +- Options depend on user context or permissions + +### Frontend Integration + +When the frontend encounters a string reference: + +1. **Detect**: Check if `frontend_options` is a string (not a list) +2. **Fetch**: Call `GET /api/options/{optionsName}` (e.g., `/api/options/user.role`) +3. **Use**: Use the returned options for the select/multiselect field + +**Example Frontend Code**: +```typescript +// Pseudocode +if (typeof field.frontend_options === 'string') { + // Dynamic options - fetch from API + const options = await fetch(`/api/options/${field.frontend_options}`); + return options; +} else { + // Static options - use directly + return field.frontend_options; +} +``` + +## Available Option Names + +| Option Name | Description | Context-Aware | +|-------------|-------------|---------------| +| `user.role` | Standard role options (sysadmin, admin, user, viewer) | No | +| `auth.authority` | Authentication authority options (local, google, msft) | No | +| `connection.status` | Connection status options (active, inactive, expired, error) | No | +| `user.connection` | User's connections (fetched from database) | Yes (requires currentUser) | + +## Utility Functions + +The `frontendOptionsTypes` module provides utility functions: + +```python +from modules.shared.frontendOptionsTypes import ( + isStringReference, + isStaticList, + validateFrontendOptions, + getOptionsName, + getStaticOptions +) + +# Check format +if isStringReference(frontend_options): + optionsName = getOptionsName(frontend_options) + # Fetch from API: /api/options/{optionsName} +elif isStaticList(frontend_options): + options = getStaticOptions(frontend_options) + # Use directly + +# Validate format +if not validateFrontendOptions(frontend_options): + raise ValueError("Invalid frontend_options format") +``` + +## Validation + +The `validateFrontendOptions()` function ensures: + +1. **String References**: Non-empty string +2. **Static Lists**: + - List of dictionaries + - Each dictionary has `"value"` and `"label"` keys + - `"label"` is a dictionary (multilingual labels) + +## Examples in Codebase + +### Static List Example +```python +# datamodelUam.py - Language field +language: str = Field( + default="en", + json_schema_extra={ + "frontend_options": [ + {"value": "en", "label": {"en": "English", "fr": "Anglais"}}, + {"value": "fr", "label": {"en": "Français", "fr": "Français"}}, + ] + } +) +``` + +### String Reference Example +```python +# datamodelUam.py - Role labels field +roleLabels: List[str] = Field( + default_factory=list, + json_schema_extra={ + "frontend_options": "user.role" # Dynamic - fetched from API + } +) +``` + +### Mixed Example +```python +# datamodelRbac.py - AccessRule model +roleLabel: str = Field( + json_schema_extra={ + "frontend_options": "user.role" # String reference + } +) + +context: AccessRuleContext = Field( + json_schema_extra={ + "frontend_options": [ # Static list + {"value": "DATA", "label": {"en": "Data", "fr": "Données"}}, + {"value": "UI", "label": {"en": "UI", "fr": "Interface"}}, + {"value": "RESOURCE", "label": {"en": "Resource", "fr": "Ressource"}} + ] + } +) +``` + +## Best Practices + +1. **Use Static Lists** for: + - Enum values + - Fixed constants + - Simple options that don't change + +2. **Use String References** for: + - Database-driven options + - Context-aware options + - Options that need centralized management + +3. **Always validate** frontend_options format when processing + +4. **Document** which format is used and why in field descriptions + +5. **Frontend**: Always check the type before using options + +## Migration Guide + +If you have existing static lists that should become dynamic: + +1. **Create Options Provider**: Add option logic to `gateway/modules/features/options/mainOptions.py` +2. **Register Option Name**: Add to `getAvailableOptionsNames()` function +3. **Update Field**: Change `frontend_options` from list to string reference +4. **Update Frontend**: Ensure frontend handles string references correctly + +## See Also + +- `gateway/modules/shared/frontendOptionsTypes.py` - Type definitions and utilities +- `gateway/modules/features/options/mainOptions.py` - Options API implementation +- `gateway/modules/routes/routeOptions.py` - Options API endpoints +- `wiki/appdoc/doc_security_role_based_access.md` - RBAC documentation with frontend_options examples