diff --git a/docs/13-pb/docest/specifica_tecnica_management_api/assets/01-app-architecture-part1.puml b/docs/13-pb/docest/specifica_tecnica_management_api/assets/01-app-architecture-part1.puml index d2ea2cae..780af58b 100644 --- a/docs/13-pb/docest/specifica_tecnica_management_api/assets/01-app-architecture-part1.puml +++ b/docs/13-pb/docest/specifica_tecnica_management_api/assets/01-app-architecture-part1.puml @@ -9,29 +9,17 @@ skinparam packageStyle rectangle package "NOTIP Management API" <> { - class "TenantEntity" as TenantEntity { - +id: string - +name: string - +status: TenantStatus - +suspensionIntervalDays: number - +suspensionUntil: Date - +createdAt: Date - +updatedAt: Date - +users: UserEntity[] - +gateways: GatewayEntity[] + package "Common Module" as CommonModule { + class "EnvValidation" as EnvValidation + class "TenantEntity" as TenantEntity + class "MetricsInterceptor" as MetricsInterceptor + class "LastAccessInterceptor" as LastAccessInterceptor + class "AuditInterceptor" as AuditInterceptor } - class "EnvValidation" as EnvValidation { - +validate(config): AppConfig - } - - class "MetricsInterceptor" as MetricsInterceptor - class "LastAccessInterceptor" as LastAccessInterceptor - class "AuditInterceptor" as AuditInterceptor - package "Auth Module" as AuthModule { - class "JwtStrategy" as JwtStrategy class "AuthController" as AuthController + class "JwtStrategy" as JwtStrategy class "ImpersonationService" as ImpersonationService class "JwtAuthGuard" as JwtAuthGuard class "RolesGuard" as RolesGuard @@ -44,9 +32,9 @@ package "NOTIP Management API" <> { class "TenantsService" as TenantsService class "TenantsPersistenceService" as TenantsPersistenceService class "KeycloakAdminService" as KeycloakAdminService - class "AdminGatewaysController" as AdminGatewaysController - class "AdminGatewaysService" as AdminGatewaysService - class "AdminGatewaysPersistenceService" as AdminGatewaysPersistenceService + class "GatewaysController" as AdminGatewaysController + class "GatewaysService" as AdminGatewaysService + class "GatewaysPersistenceService" as AdminGatewaysPersistenceService } package "Metrics Module" as MetricsModule { @@ -54,6 +42,13 @@ package "NOTIP Management API" <> { class "MetricsService" as MetricsService } + package "Api-Client Module" as ApiClientModule { + class "ApiClientController" as ApiClientController + class "ApiClientService" as ApiClientService + class "ApiClientPersistenceService" as ApiClientPersistenceService + class "ApiClientEntity" as ApiClientEntity + } + ' Core relationships MetricsInterceptor --> MetricsService LastAccessInterceptor ..> UserEntity @@ -69,12 +64,17 @@ package "NOTIP Management API" <> { TenantsService --> TenantsPersistenceService TenantsService --> KeycloakAdminService TenantsPersistenceService --> TenantEntity - TenantsPersistenceService --> UserEntity AdminGatewaysController --> AdminGatewaysService AdminGatewaysService --> AdminGatewaysPersistenceService ' Metrics relationships MetricsController --> MetricsService + + ' Api-Client relationships + ApiClientController --> ApiClientService + ApiClientService --> ApiClientPersistenceService + ApiClientService --> KeycloakAdminService + ApiClientPersistenceService --> ApiClientEntity } note top of TenantEntity @@ -90,4 +90,10 @@ note top of AuthModule User impersonation support end note +note top of ApiClientModule + Manages OAuth2 API clients + Sync with Keycloak for client credentials + Client secret management +end note + @enduml diff --git a/docs/13-pb/docest/specifica_tecnica_management_api/assets/01-app-architecture-part1.svg b/docs/13-pb/docest/specifica_tecnica_management_api/assets/01-app-architecture-part1.svg index 59b191c4..f1922e59 100644 --- a/docs/13-pb/docest/specifica_tecnica_management_api/assets/01-app-architecture-part1.svg +++ b/docs/13-pb/docest/specifica_tecnica_management_api/assets/01-app-architecture-part1.svg @@ -1 +1 @@ -NOTIP Management API - Architecture (1/3)NOTIP Management API - Architecture (1/3)NOTIP Management APIAuth ModuleAdmin ModuleMetrics ModuleTenantEntityid: stringname: stringstatus: TenantStatussuspensionIntervalDays: numbersuspensionUntil: DatecreatedAt: DateupdatedAt: Dateusers: UserEntity[]gateways: GatewayEntity[]EnvValidationvalidate(config): AppConfigMetricsInterceptorLastAccessInterceptorAuditInterceptorUserEntityAuditLogServiceJwtStrategyAuthControllerImpersonationServiceJwtAuthGuardRolesGuardAccessPolicyGuardBlockImpersonationGuardTenantsControllerTenantsServiceTenantsPersistenceServiceKeycloakAdminServiceAdminGatewaysControllerAdminGatewaysServiceAdminGatewaysPersistenceServiceMetricsControllerMetricsServiceCore entity shared across modulesManyToOne/OneToMany relationshipswith Users, Gateways, Alerts, etc.Handles JWT authenticationRole-based access controlTenant suspension checksUser impersonation support \ No newline at end of file +NOTIP Management API - Architecture (1/3)NOTIP Management API - Architecture (1/3)NOTIP Management APICommon ModuleAuth ModuleAdmin ModuleMetrics ModuleApi-Client ModuleUserEntityAuditLogServiceEnvValidationTenantEntityMetricsInterceptorLastAccessInterceptorAuditInterceptorAuthControllerJwtStrategyImpersonationServiceJwtAuthGuardRolesGuardAccessPolicyGuardBlockImpersonationGuardTenantsControllerTenantsServiceTenantsPersistenceServiceKeycloakAdminServiceGatewaysControllerGatewaysServiceGatewaysPersistenceServiceMetricsControllerMetricsServiceApiClientControllerApiClientServiceApiClientPersistenceServiceApiClientEntityCore entity shared across modulesManyToOne/OneToMany relationshipswith Users, Gateways, Alerts, etc.Handles JWT authenticationRole-based access controlTenant suspension checksUser impersonation supportManages OAuth2 API clientsSync with Keycloak for client credentialsClient secret management \ No newline at end of file diff --git a/docs/13-pb/docest/specifica_tecnica_management_api/assets/01-app-architecture-part2.puml b/docs/13-pb/docest/specifica_tecnica_management_api/assets/01-app-architecture-part2.puml index 9c45241b..9f91de63 100644 --- a/docs/13-pb/docest/specifica_tecnica_management_api/assets/01-app-architecture-part2.puml +++ b/docs/13-pb/docest/specifica_tecnica_management_api/assets/01-app-architecture-part2.puml @@ -22,6 +22,7 @@ package "NOTIP Management API" <> { class "AlertsController" as AlertsController class "AlertsService" as AlertsService class "AlertsPersistenceService" as AlertsPersistenceService + class "AlertsNatsService" as AlertsNatsService class "AlertConfigNatsResponderService" as AlertConfigNatsResponderService class "AlertsEntity" as AlertsEntity class "AlertsConfigEntity" as AlertsConfigEntity @@ -53,10 +54,14 @@ package "NOTIP Management API" <> { ' Alerts relationships AlertsController --> AlertsService AlertsService --> AlertsPersistenceService + AlertsService --> AlertsNatsService AlertsPersistenceService --> AlertsEntity AlertsPersistenceService --> AlertsConfigEntity AlertsConfigEntity --> TenantEntity + TenantEntity -[hidden]-> GatewayMetadataEntity AlertsConfigEntity --> GatewayEntity + AlertsEntity --> TenantEntity + AlertsEntity --> GatewayEntity ' Command relationships CommandController --> CommandService @@ -88,6 +93,7 @@ note top of AlertsModule Gateway offline detection Default and per-gateway timeouts NATS request-reply for configs + NATS JetStream consumer for alert events end note note top of CommandModule diff --git a/docs/13-pb/docest/specifica_tecnica_management_api/assets/01-app-architecture-part2.svg b/docs/13-pb/docest/specifica_tecnica_management_api/assets/01-app-architecture-part2.svg index d9fcefc2..1ba2396d 100644 --- a/docs/13-pb/docest/specifica_tecnica_management_api/assets/01-app-architecture-part2.svg +++ b/docs/13-pb/docest/specifica_tecnica_management_api/assets/01-app-architecture-part2.svg @@ -1 +1 @@ -NOTIP Management API - Architecture (2/3)NOTIP Management API - Architecture (2/3)NOTIP Management APIGateways ModuleAlerts ModuleCommand ModuleCosts ModuleTenantEntityGatewaysControllerGatewaysServiceGatewaysPersistenceServiceGatewaysNatsServiceGatewayStatusNatsResponderServiceGatewayEntityGatewayMetadataEntityAlertsControllerAlertsServiceAlertsPersistenceServiceAlertConfigNatsResponderServiceAlertsEntityAlertsConfigEntityCommandControllerCommandServiceCommandPersistenceServiceCommandWritingPersistenceServiceCommandsAckConsumerCommandEntityCostsControllerCostsServiceCostsPersistenceServiceGateway CRUD operationsRuntime status updatesNATS integration for telemetryGateway decommissioning eventsAlert configuration managementGateway offline detectionDefault and per-gateway timeoutsNATS request-reply for configsCommand dispatch to gatewaysFirmware updatesConfiguration changesNATS JetStream ack handlingCalculates storage and bandwidth costsIntegrates with Alerts and CommandsUsed for tenant billing info \ No newline at end of file +NOTIP Management API - Architecture (2/3)NOTIP Management API - Architecture (2/3)NOTIP Management APIGateways ModuleAlerts ModuleCommand ModuleCosts ModuleTenantEntityGatewaysControllerGatewaysServiceGatewaysPersistenceServiceGatewaysNatsServiceGatewayStatusNatsResponderServiceGatewayEntityGatewayMetadataEntityAlertsControllerAlertsServiceAlertsPersistenceServiceAlertsNatsServiceAlertConfigNatsResponderServiceAlertsEntityAlertsConfigEntityCommandControllerCommandServiceCommandPersistenceServiceCommandWritingPersistenceServiceCommandsAckConsumerCommandEntityCostsControllerCostsServiceCostsPersistenceServiceGateway CRUD operationsRuntime status updatesNATS integration for telemetryGateway decommissioning eventsAlert configuration managementGateway offline detectionDefault and per-gateway timeoutsNATS request-reply for configsNATS JetStream consumer for alert eventsCommand dispatch to gatewaysFirmware updatesConfiguration changesNATS JetStream ack handlingCalculates storage and bandwidth costsIntegrates with Alerts and CommandsUsed for tenant billing info \ No newline at end of file diff --git a/docs/13-pb/docest/specifica_tecnica_management_api/assets/01-app-architecture-part3.puml b/docs/13-pb/docest/specifica_tecnica_management_api/assets/01-app-architecture-part3.puml index e5b2cd82..93e35509 100644 --- a/docs/13-pb/docest/specifica_tecnica_management_api/assets/01-app-architecture-part3.puml +++ b/docs/13-pb/docest/specifica_tecnica_management_api/assets/01-app-architecture-part3.puml @@ -12,7 +12,8 @@ package "NOTIP Management API" <> { class "KeysController" as KeysController class "ProvisioningController" as ProvisioningController class "KeysService" as KeysService - class "GatewaysKeysPersistenceService" as GatewaysKeysPersistenceService + class "KeysNatsService" as KeysNatsService + class "KeysPersistenceService" as KeysPersistenceService class "ProvisioningNatsResponderService" as ProvisioningNatsResponderService class "KeyEntity" as KeyEntity } @@ -42,9 +43,11 @@ package "NOTIP Management API" <> { ' Keys relationships KeysController --> KeysService ProvisioningController --> KeysService - KeysService --> GatewaysKeysPersistenceService + KeysService --> KeysPersistenceService + KeysService --> KeysNatsService + KeysService --> ProvisioningNatsResponderService KeysService --> GatewaysService - GatewaysKeysPersistenceService --> KeyEntity + KeysPersistenceService --> KeyEntity KeyEntity --> GatewayEntity ' Users relationships @@ -72,6 +75,7 @@ note top of KeysModule Factory key validation (bcrypt) Provisioning with transactions Gateway key lifecycle + NATS integration for key events end note note top of UsersModule @@ -90,6 +94,7 @@ end note note top of AuditLogModule Audit logging for operations Provisioning audit consumer + NATS consumer for provisioning events Time-range queries Tenant-scoped access end note diff --git a/docs/13-pb/docest/specifica_tecnica_management_api/assets/01-app-architecture-part3.svg b/docs/13-pb/docest/specifica_tecnica_management_api/assets/01-app-architecture-part3.svg index b1601dc5..fdbcb84a 100644 --- a/docs/13-pb/docest/specifica_tecnica_management_api/assets/01-app-architecture-part3.svg +++ b/docs/13-pb/docest/specifica_tecnica_management_api/assets/01-app-architecture-part3.svg @@ -1 +1 @@ -NOTIP Management API - Architecture (3/3)NOTIP Management API - Architecture (3/3)NOTIP Management APIKeys ModuleUsers ModuleThresholds ModuleAudit-Log ModuleGatewaysServiceGatewayEntityTenantEntityKeysControllerProvisioningControllerKeysServiceGatewaysKeysPersistenceServiceProvisioningNatsResponderServiceKeyEntityUsersControllerUsersServiceUsersPersistenceServiceUserEntityThresholdsControllerThresholdsServiceThresholdsPersistenceServiceThresholdEntityAuditLogControllerAuditLogServiceAuditLogPersistenceServiceProvisioningAuditConsumerAuditLogEntityHandles AES-256 key managementFactory key validation (bcrypt)Provisioning with transactionsGateway key lifecycleCRUD operations on tenant usersSync with Keycloak IAMRole managementBulk delete supportManages sensor thresholdsDefault and per-sensor overridesUsed for alert generationAudit logging for operationsProvisioning audit consumerTime-range queriesTenant-scoped access \ No newline at end of file +NOTIP Management API - Architecture (3/3)NOTIP Management API - Architecture (3/3)NOTIP Management APIKeys ModuleUsers ModuleThresholds ModuleAudit-Log ModuleGatewaysServiceGatewayEntityTenantEntityKeysControllerProvisioningControllerKeysServiceKeysNatsServiceKeysPersistenceServiceProvisioningNatsResponderServiceKeyEntityUsersControllerUsersServiceUsersPersistenceServiceUserEntityThresholdsControllerThresholdsServiceThresholdsPersistenceServiceThresholdEntityAuditLogControllerAuditLogServiceAuditLogPersistenceServiceProvisioningAuditConsumerAuditLogEntityHandles AES-256 key managementFactory key validation (bcrypt)Provisioning with transactionsGateway key lifecycleNATS integration for key eventsCRUD operations on tenant usersSync with Keycloak IAMRole managementBulk delete supportManages sensor thresholdsDefault and per-sensor overridesUsed for alert generationAudit logging for operationsProvisioning audit consumerNATS consumer for provisioning eventsTime-range queriesTenant-scoped access \ No newline at end of file diff --git a/docs/13-pb/docest/specifica_tecnica_management_api/specifica_tecnica_management_api.meta.yaml b/docs/13-pb/docest/specifica_tecnica_management_api/specifica_tecnica_management_api.meta.yaml index 9f3a9f06..764a4b75 100644 --- a/docs/13-pb/docest/specifica_tecnica_management_api/specifica_tecnica_management_api.meta.yaml +++ b/docs/13-pb/docest/specifica_tecnica_management_api/specifica_tecnica_management_api.meta.yaml @@ -1,5 +1,12 @@ title: Specifica tecnica - Management API changelog: + - version: "1.1.0" + date: "2026-04-17" + authors: + - Alessandro Mazzariol + verifier: Leonardo Preo + description: > + Correzione immagini diagrammi - version: "1.0.0" approver: Leonardo Preo baseline: PB @@ -10,7 +17,7 @@ changelog: - Alessandro Mazzariol verifier: Alessandro Contarini description: > - Fix error + Correzione errori di battitura e refusi - version: "0.2.0" date: "2026-04-10" authors: diff --git a/docs/13-pb/docest/specifica_tecnica_management_api/specifica_tecnica_management_api.typ b/docs/13-pb/docest/specifica_tecnica_management_api/specifica_tecnica_management_api.typ index 3f9aa390..101b4d73 100644 --- a/docs/13-pb/docest/specifica_tecnica_management_api/specifica_tecnica_management_api.typ +++ b/docs/13-pb/docest/specifica_tecnica_management_api/specifica_tecnica_management_api.typ @@ -121,11 +121,12 @@ = Architettura logica - Il servizio adotta una Layered Architecture con organizzazione interna di tipo modulare. All'interno dei vari moduli è - utilizzato prevalentemente il pattern Controller-Service-Persistence, che consente una chiara separazione delle - responsabilità tra esposizione API, logica di business e accesso ai dati. I componenti collaborano tramite Dependency - Injection e, dove opportuno, tramite interfacce e contratti applicativi. La presenza di Business Models, DTO ed - Entities ha portato all'introduzione di Mappers per la conversione dei dati tra i diversi livelli dell'applicazione. + Il microservizio adotta una Layered Architecture con organizzazione interna di tipo modulare. All'interno dei vari + moduli è utilizzato prevalentemente il pattern Controller-Service-Persistence, che consente una chiara separazione + delle responsabilità tra esposizione API, logica di business e accesso ai dati. I componenti collaborano tramite + Dependency Injection e, dove opportuno, tramite interfacce e contratti applicativi. La presenza di Business Models, + DTO ed Entities ha portato all'introduzione di Mappers per la conversione dei dati tra i diversi livelli + dell'applicazione. == Layout dei moduli Essendo il microservizio troppo grande per essere contenuto in un unico diagramma, di seguito è riportata la struttura @@ -3013,5 +3014,5 @@ - gestione alert e threshold; - invio e tracciamento dei comandi; - audit delle operazioni rilevanti; - - corretto caricamento della configurazione e bootstrap del servizio. + - corretto caricamento della configurazione e bootstrap del microservizio. ]