/home/techb158/cosmic-risk.abdallabala.com/docs
Edit: /home/techb158/cosmic-risk.abdallabala.com/docs/03-sequence-diagrams.puml (9732B)
@startuml
skinparam shadowing false
skinparam sequenceMessageAlign center
title Sequence 1, Register and Score AI Risk
actor "Risk Owner" as RO
participant "Dashboard UI" as UI
participant "Risk API Controller" as API
participant "RiskService" as RS
participant "RiskScoringService" as SCORE
participant "AuditService" as AUDIT
database "Risk Store" as DB
RO -> UI: Enter risk details
UI -> API: POST /api/projects/{id}/risks
API -> RS: createRisk(request)
RS -> DB: insert Risk
RS -> SCORE: calculateRiskScore(risk)
SCORE --> RS: RiskScore
RS -> DB: insert RiskScore
RS -> AUDIT: record RiskCreated
AUDIT -> DB: insert AuditEvent
RS --> API: Risk with score
API --> UI: 201 Created
UI --> RO: Show risk and normalized score
@enduml
@startuml
skinparam shadowing false
skinparam sequenceMessageAlign center
title Sequence 2, Add Mitigation and Recalculate Residual Risk
actor "Risk Owner" as RO
participant "Dashboard UI" as UI
participant "Mitigation API Controller" as API
participant "MitigationService" as MS
participant "RiskScoringService" as SCORE
participant "GateEvaluationService" as GATE
participant "AuditService" as AUDIT
database "Risk Store" as DB
RO -> UI: Add mitigation action
UI -> API: POST /api/risks/{riskId}/mitigations
API -> MS: addMitigation(riskId, request)
MS -> DB: insert MitigationAction
MS -> DB: load Risk and mitigations
MS -> SCORE: calculateResidualRisk(risk, mitigations)
SCORE --> MS: residualScore
MS -> DB: insert RiskScore
MS -> GATE: refreshGateImpact(projectId)
GATE -> DB: update gate preview
MS -> AUDIT: record MitigationAdded
AUDIT -> DB: insert AuditEvent
MS --> API: mitigation and residual score
API --> UI: 201 Created
UI --> RO: Show updated residual risk
@enduml
@startuml
skinparam shadowing false
skinparam sequenceMessageAlign center
title Sequence 3, Evaluate Deployment Gate and Record Review
actor "Governance Reviewer" as GR
participant "Dashboard UI" as UI
participant "Gate API Controller" as API
participant "GateEvaluationService" as GATE
participant "GateWorkflowService" as WORKFLOW
participant "RiskScoringService" as SCORE
participant "IndicatorService" as IND
database "Project Store" as DB
GR -> UI: Run deployment gate evaluation
UI -> API: POST /api/projects/{id}/gate/evaluate
API -> GATE: evaluateProjectGate(projectId)
GATE -> DB: load project thresholds
GATE -> SCORE: calculateProjectRisk(projectId)
SCORE -> DB: load risks, scores, mitigations
SCORE --> GATE: overall risk and dimension scores
GATE -> IND: load reviewed indicators
IND -> DB: load data readiness, legal, ethics, metrics
IND --> GATE: indicator statuses
GATE -> GATE: build criteria and calculated status
GATE -> DB: insert DeploymentGate and GateCriteria snapshot
GATE --> API: calculated gate and persisted gate id
API --> UI: status, blockers, criteria, gate id
UI --> GR: Show Ready, Warning, or Blocked
GR -> UI: Add criterion notes and evidence links
UI -> API: PATCH /api/gate-criteria/{criterionId}
API -> WORKFLOW: updateCriterionReview(criterionId, payload)
WORKFLOW -> DB: update GateCriterion reviewer fields
WORKFLOW -> DB: insert AuditEvent
API --> UI: updated criterion
GR -> UI: Record reviewer decision
UI -> API: POST /api/gates/{gateId}/decisions
API -> WORKFLOW: recordDecision(gateId, decision)
WORKFLOW -> DB: insert GateDecision
WORKFLOW -> DB: update DeploymentGate reviewStatus
WORKFLOW -> DB: insert AuditEvent
API --> UI: updated gate with latest decision
UI --> GR: Show review status and audit trail
@enduml
@startuml
skinparam shadowing false
skinparam sequenceMessageAlign center
title Sequence 4, Multi-PM Work-Item Sync
actor "PM Tool User" as PMU
participant "Trello / Jira / Asana / Microsoft Planner" as PMTOOL
participant "Dashboard UI" as UI
participant "Integration API" as API
participant "ProjectManagementIntegrationService" as SYNC
participant "Provider Adapter" as ADAPTER
database "Project Store" as DB
PMU -> UI: Select provider and click Sync risks
UI -> API: POST /api/integrations/{integrationId}/sync
API -> SYNC: syncIntegration(integrationId)
SYNC -> DB: load integration and project risks
loop For each COSMIC risk
SYNC -> ADAPTER: mapRiskToWorkItem(risk, provider)
ADAPTER --> SYNC: external work-item payload
SYNC -> DB: create or update ExternalWorkItemMapping
end
SYNC -> DB: insert ProjectManagementSyncRun
SYNC -> DB: insert AuditEvent
SYNC --> API: sync result with counts
API --> UI: created, updated, failed counts
UI --> PMU: Show mappings and sync history
note right of ADAPTER
The academic prototype uses local adapter simulation.
Live Trello, Jira, Asana, and Microsoft Planner clients can replace
this adapter in production.
end note
@enduml
@startuml
skinparam shadowing false
skinparam sequenceMessageAlign center
title Sequence 5, Record Experiment Metrics and Update Risk Evidence
actor "AI Engineer" as DS
participant "Dashboard UI" as UI
participant "Experiment API Controller" as API
participant "ExperimentService" as ES
participant "IndicatorService" as IND
participant "RiskScoringService" as SCORE
database "Project Store" as DB
DS -> UI: Submit experiment and metrics
UI -> API: POST /api/projects/{id}/experiments
API -> ES: createExperiment(request)
ES -> DB: insert Experiment
ES -> DB: insert ModelMetric records
ES -> IND: evaluate model performance indicators
IND -> DB: insert MeasurementRecord
IND --> ES: indicator status
ES -> SCORE: refreshProjectRisk(projectId)
SCORE -> DB: update project and risk scores
ES --> API: experiment, metric status, risk impact
API --> UI: Show metrics and warnings
UI --> DS: Show performance, bias, stability, reproducibility
@enduml
@startuml
skinparam shadowing false
skinparam sequenceMessageAlign center
title Sequence 6, Generate Reporting Evidence Package
actor "Project Manager" as PM
participant "Dashboard UI" as UI
participant "Report API" as API
participant "ReportingService" as REPORT
participant "DashboardService" as DASH
participant "GateWorkflowService" as GATE
participant "IntegrationService" as INTEGRATION
database "Project Store" as DB
PM -> UI: Open Reports page
UI -> API: GET /api/projects/{id}/reports/executive.html
API -> REPORT: renderExecutiveHtml(projectId)
REPORT -> DASH: getDashboard(projectId)
DASH -> DB: load project, risks, mitigations, indicators, experiments
DASH --> REPORT: calculated dashboard evidence
REPORT -> GATE: listGateHistory(projectId)
GATE -> DB: load gates, criteria, decisions
GATE --> REPORT: gate history
REPORT -> INTEGRATION: list integrations, mappings, sync runs
INTEGRATION -> DB: load PM integration evidence
INTEGRATION --> REPORT: integration evidence
REPORT --> API: printable report
API --> UI: HTML report
UI --> PM: Print or save as PDF
PM -> UI: Download CSV or JSON report
UI -> API: GET /api/projects/{id}/reports/risk-register.csv
API -> REPORT: getRiskRegisterCsv(projectId)
REPORT --> API: CSV payload
API --> UI: report file
@enduml
@startuml
skinparam shadowing false
skinparam sequenceMessageAlign center
title Sequence 7, OAuth and Live PM Sync
actor ProjectManager as PM
participant "Dashboard UI" as UI
participant "OAuthService" as OAuth
participant "IntegrationService" as IS
participant "Live PM Client" as Client
participant "External PM API" as API
participant "JsonDatabase" as DB
PM -> UI: Click OAuth URL
UI -> OAuth: buildAuthorizePayload(provider, integrationId)
OAuth -> DB: store OAuthState
OAuth --> UI: authorization URL + state
PM -> API: Consent in provider screen
API -> OAuth: callback(code, state)
OAuth -> API: token exchange
OAuth -> DB: store encrypted OAuthToken
PM -> UI: Click Live sync
UI -> IS: syncIntegrationLive(integrationId)
IS -> OAuth: getAccessToken(provider, integrationId)
IS -> Client: create client with token
loop For each risk
IS -> Client: createOrUpdateRiskWorkItem(risk, mitigations)
Client -> API: create or update external item
API --> Client: external id, key, URL
IS -> DB: upsert ExternalWorkItemMapping
end
IS -> DB: create SyncRun and AuditEvent
IS --> UI: live sync result
@enduml
@startuml
skinparam shadowing false
title Step 8, Enforce role-based permission on protected API action
actor User
participant "Dashboard UI" as UI
participant "API Router" as API
participant "AccessControlService" as RBAC
database "JSON Database" as DB
participant "Domain Service" as Domain
User -> UI: Perform protected action
UI -> API: Request with X-Cosmic-User-Id
API -> RBAC: requirePermission(actorUserId, permission)
RBAC -> DB: Read user and role permissions
alt Permission granted
RBAC --> API: Actor context
API -> Domain: Execute requested workflow
Domain -> DB: Persist change and audit event
API --> UI: 200/201 response
else Permission denied
RBAC --> API: AuthorizationError
API --> UI: 403 with required permission
end
@enduml
@startuml
skinparam shadowing false
skinparam sequenceMessageAlign center
title Step 9, Production readiness and backup workflow
actor "Deployment Operator" as DO
participant "Reverse Proxy" as Proxy
participant "API Router" as API
participant "OperationsService" as OPS
participant "RuntimeConfig" as CFG
database "JSON Database" as DB
collections "Backup Directory" as BKP
DO -> Proxy: GET /api/ready
Proxy -> API: Forward request with X-Forwarded-Proto
API -> OPS: getReadiness()
OPS -> CFG: validateRuntimeConfig()
OPS -> DB: read database tables
OPS -> BKP: verify write access
OPS --> API: readiness checks
API --> Proxy: 200 or 503 JSON
Proxy --> DO: readiness result
DO -> Proxy: POST /api/operations/backups
Proxy -> API: Forward with X-Cosmic-User-Id
API -> OPS: createBackup(actorUserId)
OPS -> DB: copy database file
OPS -> BKP: write backup and manifest
OPS --> API: BackupManifest
API --> DO: 201 backup manifest
@enduml
