FM / docs

/home/techb158/cosmic-risk.abdallabala.com/docs/

/home/techb158/cosmic-risk.abdallabala.com/docs

Name	Size	Mode	Actions
00-design-study.md	3678	0644	edit dl rm
01-uml-class-diagram.puml	11869	0644	edit dl rm
02-use-case-diagram.puml	3763	0644	edit dl rm
03-sequence-diagrams.puml	9732	0644	edit dl rm
04-database-entity-model.mmd	7051	0644	edit dl rm
05-database-schema.sql	13372	0644	edit dl rm
06-diagram-preview.html	5021	0644	edit dl rm
07-design-checklist.md	3256	0644	edit dl rm
08-step-2-storage-layer.md	5325	0644	edit dl rm
09-step-3-risk-crud-ui.md	3380	0644	edit dl rm
10-step-4-mitigation-workflow.md	3996	0644	edit dl rm
11-step-5-deployment-gate-workflow.md	2292	0644	edit dl rm
12-step-6-multi-pm-integration.md	3770	0644	edit dl rm
13-step-6-1-microsoft-planner-integration.md	2335	0644	edit dl rm
14-step-7-reporting-export.md	4158	0644	edit dl rm
15-step-7-1-oauth-live-connectors.md	4545	0644	edit dl rm
16-step-8-user-roles-access-control.md	3297	0644	edit dl rm
17-step-9-production-deployment-security.md	4228	0644	edit dl rm
18-step-10-final-academic-submission.md	3199	0644	edit dl rm
19-final-report-draft.md	6814	0644	edit dl rm
20-instructor-submission-checklist.md	3639	0644	edit dl rm
21-demo-script.md	3948	0644	edit dl rm
22-traceability-matrix.md	4847	0644	edit dl rm
23-testing-evidence.md	2961	0644	edit dl rm
24-evaluation-rubric-mapping.md	2910	0644	edit dl rm
25-final-deployment-runbook.md	3214	0644	edit dl rm
26-known-limitations-and-future-work.md	2632	0644	edit dl rm
27-final-qa-checklist.md	2893	0644	edit dl rm
28-demo-rehearsal-script.md	3618	0644	edit dl rm
29-submission-freeze-report.md	2769	0644	edit dl rm
30-final-known-issues.md	1876	0644	edit dl rm
31-saas-rebuild-implementation.md	2573	0644	edit dl rm
application-documentation.md	27515	0644	edit dl rm
conversation-log.md	18503	0644	edit dl rm
dashboard-spec.md	3691	0644	edit dl rm
database-guide.md	37826	0644	edit dl rm
development-summary.md	7070	0644	edit dl rm
github-architecture.svg	6288	0644	edit dl rm
integration-pull-push-plan.md	7384	0644	edit dl rm

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

cmd: