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/00-design-study.md (3678B)

# COSMIC AI-Risk Dashboard, Design Study Before Development

Version: 0.2
Date: 2026-07-03

## 1. Purpose

This document defines the design layer that must be studied before continuing application development. It covers:

1. UML Class Diagram
2. Use Case Diagram
3. Sequence Diagrams
4. Database Entity Model
5. Database schema draft
6. Traceability from source framework to software implementation

The source framework provides the conceptual foundation. The dashboard, classes, entities, APIs, scoring logic, and multi-project-management integration are software design extensions that operationalize that foundation.

## 2. Source-derived concepts

The source deck supports the following core concepts:

| Source concept | Dashboard design implication |
|---|---|
| AI risks must be quantified through organizational, technical, and human dimensions | Store risk dimension and calculate dimension-level scores |
| Existing frameworks are mostly qualitative and lack ISO 15939-aligned indicators | Create indicator entities with measurand, unit, threshold, and interpretation rule |
| COSMIC-Risk includes a software prototype and REST API | Design API-facing classes, service layer, and persistent database entities |
| The methodology includes API architecture, risk engine implementation, and PM tool integration | Include Trello, Jira, Asana, and Microsoft Planner mapping entities and sync sequences |
| AI Governance Triangle uses organizational, technical, and human dimensions | Use these as first-class dimensions across UI, database, and risk scoring |
| COSMIC-Risk adapts to project profiles | Store project type and apply future weighting by project profile |

## 3. Implementation extensions

The following items are proposed software design decisions, not direct thesis or source-deck claims:

| Extension | Reason |
|---|---|
| Normalized risk score from 0 to 100 | Makes risks comparable in dashboard widgets and gate rules |
| Residual risk calculation after mitigation | Shows whether mitigation actions reduce deployment risk |
| Deployment gate criteria | Converts measurement outputs into a project governance decision |
| Trello, Jira, Asana, and Microsoft Planner mapping | Integrates the framework into project-management workflows |
| Audit events | Provides traceability for instructor review and future governance use |
| JSON first storage, then SQL migration | Allows fast prototype development while preserving a database-ready model |

## 4. Target architecture

The dashboard should use a layered structure:

```text
Browser UI
  calls REST API
API controllers
  validate requests and return JSON
Application services
  risk scoring, mitigation workflow, gate evaluation, PM tool sync
Domain model
  project, risk, indicator, mitigation, experiment, gate, user, audit
Persistence layer
  JSON storage in MVP, SQL database in later version
External integrations
  Trello, Jira, Asana, and external project management tools
```

## 5. Diagram inventory

| File | Purpose |
|---|---|
| `01-uml-class-diagram.puml` | Domain and service class structure |
| `02-use-case-diagram.puml` | Actors and functional scope |
| `03-sequence-diagrams.puml` | Main interaction flows |
| `04-database-entity-model.mmd` | Mermaid ER model |
| `05-database-schema.sql` | SQL schema draft |
| `06-diagram-preview.html` | Browser preview for Mermaid database model |
| `07-design-checklist.md` | Instructor-facing design checklist |

## 6. Development rule from this study

Do not add more dashboard features until each feature maps to:

1. A use case
2. A domain class
3. A database entity or storage object
4. A service method
5. An API endpoint
6. A test case

cmd: