@bluealba/platform-cli 1.0.1 → 1.1.0

package/docs/architecture/api-explorer.mdx

@@ -0,0 +1,478 @@
+---
+title: API Explorer
+description: Interactive API documentation system for exploring and testing the Blue Alba Platform REST APIs
+---
+
+import { Card, CardGrid, Aside, Tabs, TabItem } from '@astrojs/starlight/components';
+
+The Blue Alba Platform provides comprehensive API documentation through an interactive **API Explorer** that enables developers to discover, understand, and test all available REST endpoints across the platform and business applications.
+
+## Overview
+
+The Platform API consists of two main categories:
+
+<CardGrid>
+  <Card title="Business Application APIs" icon="seti:javascript">
+    Custom APIs provided by business applications, prefixed by the gateway through the Application Catalog. These APIs are product-specific and depend on the applications and modules deployed.
+  </Card>
+
+  <Card title="Platform APIs" icon="seti:config">
+    Out-of-the-box APIs provided by the Platform itself and its core microservices. These APIs handle authentication, authorization, catalog management, user management, and more.
+  </Card>
+</CardGrid>
+
+---
+
+## API Documentation via Swagger
+
+Every Platform service implements interactive API documentation using **Swagger/OpenAPI**. This provides:
+
+- **Interactive Testing**: Execute API calls directly from the documentation
+- **Request/Response Examples**: See real-world examples of API payloads
+- **Schema Definitions**: Understand data structures and validation rules
+- **Authentication Support**: Test authenticated endpoints with your session
+
+---
+
+## Accessing the API Explorer
+
+### Built-in API Docs Explorer
+
+The most straightforward way to inspect and test APIs is through the **built-in API Docs Explorer**, available since Platform version `v1.5.0`.
+
+**Access Requirements**:
+- Navigate to the Admin Application
+- Requires the `api-docs::*` operation permission
+
+**Features**:
+- Unified interface for all platform services
+- Single sign-on - uses your current authentication session
+- Tenant-aware - respects your current tenant context
+- Service switching - easily navigate between different service APIs
+
+<Aside type="tip" title="Admin Access">
+  The API Explorer is available in the Platform Admin UI under the API Documentation section. Users must have the appropriate permissions to access this feature.
+</Aside>
+
+---
+
+## Individual Service Documentation
+
+You can also access each service's Swagger documentation directly at specific URLs:
+
+<Tabs>
+  <TabItem label="Gateway">
+    **Gateway Service API**
+    ```
+    /api-documentation
+    ```
+
+    Provides documentation for orchestrator and gateway endpoints.
+  </TabItem>
+
+  <TabItem label="Catalog">
+    **Application Catalog API**
+    ```
+    /catalog/docs
+    ```
+
+    Documents endpoints for managing applications, modules, and catalog entries.
+  </TabItem>
+
+  <TabItem label="Authorization">
+    **Authorization API**
+    ```
+    /authz/docs
+    ```
+
+    Documents endpoints for managing roles, operations, permissions, and authorization rules.
+  </TabItem>
+
+  <TabItem label="User Service">
+    **User Service API**
+    ```
+    /user/api-docs
+    ```
+
+    Documents endpoints for user management, authentication, and user states.
+  </TabItem>
+</Tabs>
+
+<Aside type="note">
+  The base URL depends on your platform instance. For example, in development it might be `http://localhost/_/docs`, while in production it would use your configured domain.
+</Aside>
+
+---
+
+## Using the API Explorer
+
+### Interactive Testing
+
+The Swagger interface allows you to:
+
+1. **Expand Endpoint Groups**: Click on endpoint categories to see available operations
+2. **View Details**: See request parameters, headers, and body schemas
+3. **Try It Out**: Click "Try it out" to enable interactive testing
+4. **Execute Requests**: Fill in parameters and click "Execute"
+5. **View Responses**: See actual API responses with status codes and data
+
+**Example Workflow**:
+
+```
+1. Navigate to Authorization API docs (/authz/docs)
+2. Find "GET /operations" endpoint
+3. Click "Try it out"
+4. Execute the request
+5. View the list of all operations in the system
+```
+
+### Authentication Context
+
+The API Explorer automatically uses your current session:
+
+- **JWT Token**: Extracted from your HTTP-only cookie
+- **Tenant Context**: Inherited from your current tenant selection
+- **User Context**: Operations are executed as the logged-in user
+- **Permissions**: You can only execute operations you're authorized for
+
+---
+
+## Platform Core APIs
+
+### Gateway & Orchestrator API
+
+**Base Path**: `/api-documentation`
+
+Key endpoints include:
+- Health checks
+- Configuration management
+- Platform metadata
+- Request proxying information
+
+### Catalog API
+
+**Base Path**: `/catalog/docs`
+
+Manages the dynamic service registry:
+
+<CardGrid>
+  <Card title="Applications" icon="seti:folder">
+    - List all applications
+    - Get application details
+    - Create/update applications
+    - Manage application access
+  </Card>
+
+  <Card title="Modules" icon="puzzle">
+    - Register services and UIs
+    - Update module configurations
+    - Query module endpoints
+    - Manage module dependencies
+  </Card>
+
+  <Card title="Operations" icon="approve-check">
+    - List all operations
+    - Create new operations
+    - Bind operations to applications
+    - Query operation permissions
+  </Card>
+</CardGrid>
+
+### Authorization API
+
+**Base Path**: `/authz/docs`
+
+Implements the RBAC system:
+
+**Key Endpoints**:
+- `GET /roles` - List all roles
+- `POST /roles` - Create a new role
+- `GET /operations` - List all operations
+- `POST /operations` - Create a new operation
+- `GET /users/{username}/resources` - Get user's authorized resources
+- `POST /authorization-rules` - Create authorization rules
+
+### User Service API
+
+**Base Path**: `/user/api-docs`
+
+Manages users and user-related data:
+
+**Key Endpoints**:
+- `GET /users` - List users (with filtering)
+- `POST /users` - Create a new user
+- `GET /users/{id}` - Get user details
+- `PUT /users/{id}` - Update user
+- `GET /user-states` - Manage user state storage
+- `POST /api-keys` - Generate API keys
+
+---
+
+## API Request Flow
+
+Understanding how API requests flow through the platform:
+
+```
+┌──────────────────────────────────────────────────────┐
+│ 1. Client makes API request                          │
+│    (Browser, Postman, cURL, etc.)                    │
+└────────────────────┬─────────────────────────────────┘
+                     │
+                     ▼
+┌──────────────────────────────────────────────────────┐
+│ 2. Gateway receives request                          │
+│    - Validates JWT token                             │
+│    - Resolves tenant context                         │
+│    - Identifies target service from catalog          │
+└────────────────────┬─────────────────────────────────┘
+                     │
+                     ▼
+┌──────────────────────────────────────────────────────┐
+│ 3. Authorization check                               │
+│    - Verifies user has required operations           │
+│    - Evaluates authorization rules                   │
+│    - Checks tenant-specific restrictions             │
+└────────────────────┬─────────────────────────────────┘
+                     │
+                     ▼
+┌──────────────────────────────────────────────────────┐
+│ 4. Request proxied to target service                 │
+│    - Gateway adds platform context headers           │
+│    - Service processes business logic                │
+│    - Service respects tenant isolation               │
+└────────────────────┬─────────────────────────────────┘
+                     │
+                     ▼
+┌──────────────────────────────────────────────────────┐
+│ 5. Response returned to client                       │
+│    - Gateway forwards service response               │
+│    - Client receives data                            │
+└──────────────────────────────────────────────────────┘
+```
+
+---
+
+## API Authentication
+
+### For Browser-Based Requests
+
+When using the API Explorer or making requests from UI applications:
+
+```typescript
+// Authentication happens automatically via HTTP-only cookie
+fetch('/catalog/api/applications', {
+  method: 'GET',
+  credentials: 'include' // Include cookies
+})
+  .then(response => response.json())
+  .then(data => console.log(data));
+```
+
+### For API Keys
+
+For programmatic access or service-to-service calls:
+
+```bash
+# Using Bearer token
+curl -X GET "https://platform.com/catalog/api/applications" \
+  -H "Authorization: Bearer YOUR_API_KEY"
+```
+
+**Generate API Keys**:
+1. Navigate to User Service API docs
+2. Use `POST /api-keys` endpoint
+3. Provide description and expiration
+4. Store the generated key securely
+
+<Aside type="caution" title="API Key Security">
+  - Never commit API keys to version control
+  - Use environment variables for key storage
+  - Rotate keys regularly
+  - Set appropriate expiration dates
+  - Revoke compromised keys immediately
+</Aside>
+
+---
+
+## Business Application APIs
+
+Custom applications can expose their own APIs through the platform:
+
+### Registering Application APIs
+
+When a service registers with the catalog, its endpoints automatically become available:
+
+```json
+{
+  "name": "@mycompany/orders-service",
+  "type": "service",
+  "baseUrl": "/api/orders",
+  "service": {
+    "host": "orders-service",
+    "port": 4002
+  }
+}
+```
+
+**Resulting API Paths**:
+```
+GET  /api/orders           → List all orders
+POST /api/orders           → Create new order
+GET  /api/orders/:id       → Get order details
+PUT  /api/orders/:id       → Update order
+DELETE /api/orders/:id     → Delete order
+```
+
+### Documenting Application APIs
+
+Services can provide Swagger documentation:
+
+<Tabs>
+  <TabItem label="NestJS">
+    ```typescript
+    // main.ts
+    import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
+
+    const config = new DocumentBuilder()
+      .setTitle('Orders Service API')
+      .setDescription('API for managing customer orders')
+      .setVersion('1.0')
+      .addBearerAuth()
+      .build();
+
+    const document = SwaggerModule.createDocument(app, config);
+    SwaggerModule.setup('api-docs', app, document);
+    ```
+  </TabItem>
+
+  <TabItem label="Express">
+    ```typescript
+    // app.ts
+    import swaggerJsdoc from 'swagger-jsdoc';
+    import swaggerUi from 'swagger-ui-express';
+
+    const swaggerOptions = {
+      definition: {
+        openapi: '3.0.0',
+        info: {
+          title: 'Orders Service API',
+          version: '1.0.0',
+        },
+      },
+      apis: ['./routes/*.ts'],
+    };
+
+    const swaggerSpec = swaggerJsdoc(swaggerOptions);
+    app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));
+    ```
+  </TabItem>
+</Tabs>
+
+---
+
+## API Response Formats
+
+Platform APIs follow consistent response patterns:
+
+### Success Response
+
+```json
+{
+  "statusCode": 200,
+  "data": {
+    "id": "123",
+    "name": "Example Resource"
+  }
+}
+```
+
+### List Response
+
+```json
+{
+  "statusCode": 200,
+  "data": [
+    { "id": "1", "name": "Item 1" },
+    { "id": "2", "name": "Item 2" }
+  ],
+  "total": 2,
+  "page": 1,
+  "pageSize": 10
+}
+```
+
+### Error Response
+
+```json
+{
+  "statusCode": 400,
+  "message": "Validation failed",
+  "error": "Bad Request",
+  "timestamp": "2025-01-09T10:30:00Z",
+  "path": "/api/orders"
+}
+```
+
+---
+
+## Best Practices
+
+<CardGrid>
+  <Card title="Use the API Explorer" icon="rocket">
+    Start with the built-in API Explorer for discovery and testing before writing code
+  </Card>
+
+  <Card title="Respect Rate Limits" icon="warning">
+    Be mindful of API rate limits and implement appropriate retry logic
+  </Card>
+
+  <Card title="Handle Errors Gracefully" icon="error">
+    Always implement proper error handling for API calls
+  </Card>
+
+  <Card title="Validate Input" icon="approve-check">
+    Use schema definitions to validate request data before submission
+  </Card>
+
+  <Card title="Secure API Keys" icon="seti:lock">
+    Never expose API keys in client-side code or public repositories
+  </Card>
+
+  <Card title="Version APIs" icon="seti:config">
+    Plan for API versioning to support backward compatibility
+  </Card>
+</CardGrid>
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+**401 Unauthorized**:
+- Verify you're logged in
+- Check if your JWT token is valid
+- Ensure API key is correct (if using key auth)
+
+**403 Forbidden**:
+- Verify you have the required operations
+- Check tenant-specific restrictions
+- Confirm application access permissions
+
+**404 Not Found**:
+- Verify the endpoint URL is correct
+- Check if the service is registered in the catalog
+- Confirm the module is deployed and running
+
+**500 Internal Server Error**:
+- Check service logs for details
+- Verify database connectivity
+- Ensure all dependencies are available
+
+---
+
+## Next Steps
+
+- **[Gateway Architecture](/_/docs/architecture/gateway-architecture/)** - Understand how the gateway routes API requests
+- **[Authorization System](/_/docs/architecture/authorization-system/)** - Learn about API access control
+- **[Authentication System](/_/docs/architecture/authentication-system/)** - Understand API authentication mechanisms

package/docs/architecture/architecture-diagrams.mdx

@@ -0,0 +1,12 @@
+---
+title: Architecture Diagrams
+description: Architecture diagrams have been merged into the System Architecture Overview page.
+sidebar:
+  hidden: true
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+<Aside type="note">
+  The architecture diagrams have been merged into the **[System Architecture Overview](/_/docs/architecture/overview/)** page. All interactive diagrams covering platform topology, request flows, service communication, micro-frontend loading, authentication, catalog lifecycle, and multi-tenancy are available there.
+</Aside>