FM / docs

/home/techb158/balavpn.abdallabala.com/docs/

/home/techb158/balavpn.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	2571	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

Edit: /home/techb158/balavpn.abdallabala.com/docs/19-final-report-draft.md (6814B)

# COSMIC AI-Risk Dashboard: Final Report Draft

## 1. Project title

COSMIC AI-Risk Dashboard: A Software Prototype for Measuring, Tracking, and Governing AI Project Risks

## 2. Project context

AI projects are difficult to manage with traditional project management tools because they involve uncertainty in data quality, model behavior, performance stability, deployment readiness, ethical review, legal review, and organizational adoption.

The COSMIC AI-Risk Dashboard transforms the COSMIC AI-Risk conceptual direction into a working software prototype. The prototype supports risk registration, risk scoring, mitigation tracking, deployment gate decisions, reporting, role-based access control, and integration with multiple project management applications.

## 3. Source-derived foundation

The source framework provides the conceptual basis for the dashboard. It identifies the need for a measurable AI project risk framework and emphasizes:

1. Organizational, technical, and human risk dimensions.
2. ISO-style measurement logic.
3. Explicit indicators and interpretation rules.
4. A software prototype and REST API.
5. Integration with project management tools.
6. Validation and transfer to practical usage.

## 4. Software implementation extension

The software architecture is an operational extension of the source framework. The thesis and COSMIC presentation provide the conceptual direction. The dashboard adds implementation-specific details such as:

1. JSON storage layer for prototype persistence.
2. Domain repositories for projects, risks, mitigations, gates, indicators, users, roles, and integrations.
3. Risk scoring service.
4. Deployment gate service.
5. Reporting service.
6. OAuth and live connector service.
7. Role-based access control service.
8. Production configuration and backup service.

## 5. Research and engineering problem

The main problem is that AI project risks are often tracked qualitatively, inconsistently, and separately from project execution tools. The dashboard addresses this by turning risk information into measurable indicators, workflow controls, and exportable evidence.

## 6. Project objectives

| Objective | Implementation evidence |
|---|---|
| Quantify AI project risk | Risk scoring engine and normalized risk values |
| Track risk dimensions | Organizational, technical, and human risk categories |
| Manage mitigations | Mitigation workflow with evidence and residual risk impact |
| Support deployment decisions | Deployment gate evaluation and reviewer decision workflow |
| Integrate with PM tools | Trello, Jira, Asana, and Microsoft Planner adapter layer |
| Provide audit evidence | Reports, audit trail, gate history, and exports |
| Support governance roles | Role-based access control and permission matrix |
| Prepare deployment | Docker, Nginx, systemd, security headers, and readiness checks |

## 7. Application architecture

The prototype uses a dependency-light Node.js backend and a browser-based frontend. The system is divided into:

1. Public dashboard UI.
2. HTTP API layer.
3. Domain services.
4. Repository layer.
5. JSON storage engine.
6. Security and access control layer.
7. Integration adapter layer.
8. Operations layer.

## 8. Main modules

### 8.1 Risk management

Users can create, edit, delete, and classify AI risks. Each risk belongs to a lifecycle phase and governance dimension. Risks have probability, impact, detectability, status, owner, and approval state.

### 8.2 Risk scoring

The scoring model calculates raw and normalized risk values. It also supports residual risk after mitigation progress and effectiveness are considered.

### 8.3 Mitigation workflow

Mitigation actions are linked to risks. They include owner, status, progress, effectiveness, due date, and evidence references.

### 8.4 Deployment gate

The gate evaluates deployment readiness based on risk score, critical risks, mitigation completion, data readiness, model metrics, legal review, ethical review, and approval state.

### 8.5 Reporting and export

The system produces executive reports, risk register exports, mitigation exports, gate reports, indicator reports, integration reports, and audit reports.

### 8.6 Project management integrations

The system supports an integration adapter layer for Trello, Jira, Asana, and Microsoft Planner. The current implementation includes simulated synchronization and live client boundaries for OAuth-enabled production integration.

### 8.7 Role-based access control

The system includes roles such as System Admin, Project Manager, Risk Owner, AI Engineer, Governance Reviewer, Legal/Ethics Reviewer, Integration Admin, and Read-only Viewer.

### 8.8 Production hardening

The app includes security headers, content security policy, environment checks, readiness checks, backup support, Docker deployment, Nginx reverse proxy guidance, and systemd guidance.

## 9. Design artifacts

| Design artifact | File |
|---|---|
| Design study | `docs/00-design-study.md` |
| UML class diagram | `docs/01-uml-class-diagram.puml` |
| Use case diagram | `docs/02-use-case-diagram.puml` |
| Sequence diagrams | `docs/03-sequence-diagrams.puml` |
| Database entity model | `docs/04-database-entity-model.mmd` |
| SQL schema draft | `docs/05-database-schema.sql` |

## 10. Testing summary

The prototype includes automated tests for:

1. Risk engine.
2. Storage layer.
3. API workflow.
4. Mitigation workflow.
5. Gate workflow.
6. PM integration workflow.
7. OAuth and live connector boundaries.
8. Reporting workflow.
9. Access control.
10. Production hardening.

## 11. Evaluation result

The prototype demonstrates a complete academic software engineering path:

1. Conceptual framework interpretation.
2. UML and database design.
3. Backend service implementation.
4. Frontend dashboard implementation.
5. API development.
6. Integration design.
7. Security and access control.
8. Reporting and deployment documentation.

## 12. Limitations

The current prototype uses JSON storage instead of a production database. OAuth live integrations require real credentials and provider app registration. The scoring model is an implementation proposal and should be calibrated through empirical validation.

## 13. Future work

1. Replace JSON storage with PostgreSQL or SQLite.
2. Add full user authentication.
3. Complete live production connectors.
4. Add PDF server-side report generation.
5. Add real-time notifications.
6. Validate the scoring model with industrial case data.
7. Prepare final defense presentation.

## 14. Conclusion

The COSMIC AI-Risk Dashboard converts the source framework into a working software prototype. It demonstrates how AI project risk can be measured, governed, mitigated, reviewed, integrated into project management tools, and exported as evaluation evidence.

cmd: