/home/techb158/cosmic.abdallabala.com
Edit: /home/techb158/cosmic.abdallabala.com/README.md (16676B)
# COSMIC AI-Risk Dashboard
A complete working dashboard prototype for COSMIC AI-Risk Management. The project follows a design-first approach with UML, use cases, sequence diagrams, a database entity model, normalized JSON storage, Risk CRUD, mitigation workflow management, evidence linkage, deployment gate workflow controls, reviewer decisions, audit traceability, and a native Node.js API.
## What is included
- Web dashboard with a COSMIC-style green and white layout.
- AI Governance Triangle view: organizational, technical, and human risk.
- AI lifecycle readiness map.
- Risk register with 35 sample AI risks.
- Browser workflow for creating, editing, deleting, and filtering risks.
- Dedicated mitigation management page.
- Mitigation create, edit, mark done, delete, and evidence-link workflow.
- Residual-risk recalculation after mitigation updates.
- Risk scoring engine.
- Deployment gate evaluation with reviewer decision workflow.
- Gate history, criterion notes, evidence references, and audit trail view.
- ISO-style indicator catalog with measurands, units, and interpretation rules.
- Experiment and model metrics table.
- Multi-project-management integration for Trello, Jira, Asana, and Microsoft Planner.
- Reporting and export module with executive HTML report, CSV exports, JSON evidence package, gate report, indicator report, integration report, and audit report.
- Native Node.js API with no external package dependency.
- Normalized JSON database aligned with the database entity model.
- Repository layer for projects, risks, mitigations, indicators, experiments, gates, evidence, and audit events.
- OpenAPI file.
- API and workflow tests.
## Run locally
```bash
npm start
```
or:
```bash
node server.js
```
Open:
```text
http://localhost:8090
```
Health check:
```bash
curl http://localhost:8090/api/health
```
Full dashboard payload:
```bash
curl http://localhost:8090/api/dashboard
```
Project-specific dashboard payload:
```bash
curl http://localhost:8090/api/projects/cosmic-ai-risk-001/dashboard
```
Run tests:
```bash
npm test
```
## Main API endpoints
| Method | Endpoint | Purpose |
|---|---|---|
| GET | /api/health | Service health check |
| GET | /api/projects | List projects |
| GET | /api/projects/{projectId} | Read one project |
| GET | /api/dashboard | Backward-compatible full dashboard payload |
| GET | /api/projects/{projectId}/dashboard | Full dashboard data and calculated results |
| GET | /api/projects/{projectId}/risks | Scored risk register |
| POST | /api/projects/{projectId}/risks | Create a risk |
| GET | /api/risks/{riskId} | Read one scored risk |
| PATCH | /api/risks/{riskId} | Update one risk |
| DELETE | /api/risks/{riskId} | Delete one risk |
| GET | /api/projects/{projectId}/mitigations | List project mitigations |
| POST | /api/risks/{riskId}/mitigations | Create mitigation action |
| GET | /api/mitigations/{mitigationId} | Read one mitigation action |
| PATCH | /api/mitigations/{mitigationId} | Update mitigation action |
| DELETE | /api/mitigations/{mitigationId} | Delete mitigation action |
| POST | /api/mitigations/{mitigationId}/evidence | Add mitigation evidence |
| GET | /api/projects/{projectId}/gate | Deployment gate evaluation |
| POST | /api/projects/{projectId}/gate/evaluate | Evaluate and persist gate decision |
| GET | /api/projects/{projectId}/gate/history | List persisted gate evaluations |
| GET | /api/projects/{projectId}/audit | List project audit events |
| GET | /api/gates/{gateId} | Read persisted gate with criteria and decisions |
| POST | /api/gates/{gateId}/decisions | Record reviewer gate decision |
| PATCH | /api/gate-criteria/{criterionId} | Update criterion notes and evidence reference |
| GET | /api/projects/{projectId}/indicators | Indicator catalog |
| GET | /api/projects/{projectId}/metrics | Experiment and model metrics |
| POST | /api/calculate-risk | Calculate one risk score |
| GET | /api/integration-providers | Supported project-management providers |
| GET | /api/projects/{projectId}/integrations | List PM integrations |
| POST | /api/projects/{projectId}/integrations | Create PM integration configuration |
| GET | /api/integrations/{integrationId} | Read one PM integration |
| PATCH | /api/integrations/{integrationId} | Update PM integration configuration |
| POST | /api/integrations/{integrationId}/sync | Sync COSMIC risks to external work items |
| POST | /api/integrations/{integrationId}/mappings/risks/{riskId} | Create one risk-to-work-item mapping |
| GET | /api/projects/{projectId}/integration-mappings | List external work-item mappings |
| GET | /api/projects/{projectId}/sync-runs | List PM sync history |
| GET | /api/projects/{projectId}/reports/executive | Executive report JSON |
| GET | /api/projects/{projectId}/reports/executive.html | Printable executive HTML report |
| GET | /api/projects/{projectId}/reports/full | Full evidence package JSON |
| GET | /api/projects/{projectId}/reports/full.json | Downloadable full evidence package |
| GET | /api/projects/{projectId}/reports/risk-register | Risk register report JSON |
| GET | /api/projects/{projectId}/reports/risk-register.csv | Risk register CSV export |
| GET | /api/projects/{projectId}/reports/mitigations | Mitigation report JSON |
| GET | /api/projects/{projectId}/reports/mitigations.csv | Mitigation CSV export |
| GET | /api/projects/{projectId}/reports/gate | Deployment gate report |
| GET | /api/projects/{projectId}/reports/indicators | Indicator report |
| GET | /api/projects/{projectId}/reports/integrations | PM integration report |
| GET | /api/projects/{projectId}/reports/audit | Audit trail report |
## Step 5 workflow controls
The deployment gate now separates calculated status from governance review. The calculated gate can be Ready, Warning, or Blocked. The reviewer decision can be Approved, Rejected, Accepted, or Needs changes.
Gate records now include:
- Persisted gate history.
- Criteria snapshots with actual values, expected rules, and blocking status.
- Reviewer notes per criterion.
- Optional evidence URL or internal document reference per criterion.
- Reviewer decision history.
- Audit events for gate evaluation, criterion updates, and reviewer decisions.
## Scoring model
The source material defines the need for quantitative AI risk indicators. The specific scoring formula is a proposed implementation extension.
```text
Raw risk score = probability x impact x detectability
Normalized score = raw risk score / 125 x 100
Residual score = normalized score x (1 - mitigation progress x mitigation effectiveness)
```
Detectability is scored from 1 to 5, where 5 means the risk is difficult to detect.
## Source traceability
Source-derived:
- Organizational, technical, and human dimensions.
- COSMIC-Risk as a measurable AI risk framework.
- ISO 15939 and VIM-style indicator logic.
- Software prototype and REST API objective.
- Integration with project management tools.
Implementation extension:
- Dashboard screens.
- Gate criteria.
- Risk scoring formula.
- Mitigation workflow screens and evidence-link controls.
- Sample project dataset.
- Multi-PM integration mapping.
## Design-first development
Before adding more features, review the instructor-facing design package in `docs/`:
- `00-design-study.md`
- `01-uml-class-diagram.puml`
- `02-use-case-diagram.puml`
- `03-sequence-diagrams.puml`
- `04-database-entity-model.mmd`
- `05-database-schema.sql`
- `06-diagram-preview.html`
- `07-design-checklist.md`
- `08-step-2-storage-layer.md`
- `09-step-3-risk-crud-ui.md`
- `10-step-4-mitigation-workflow.md`
- `11-step-5-deployment-gate-workflow.md`
- `12-step-6-multi-pm-integration.md`
- `13-step-6-1-microsoft-planner-integration.md`
- `14-step-7-reporting-export.md`
These files define the domain model, use cases, main sequences, and database structure that should guide the application implementation.
## Step 2: Storage layer implemented
The application uses `data/database.json` as a normalized JSON database. This mirrors the database entity model before moving to SQLite or PostgreSQL.
Added backend files:
- `src/storage/jsonDatabase.js`
- `src/domain/dataMapper.js`
- `src/domain/validation.js`
- `src/repositories/projectRepository.js`
- `src/repositories/riskRepository.js`
- `src/services/dashboardService.js`
- `tests/storage-layer.test.js`
Detailed notes are in `docs/08-step-2-storage-layer.md`.
## Step 3: Risk CRUD UI implemented
The Risk register page includes browser-based workflow controls:
- Add risk
- Edit risk
- Delete risk
- Add mitigation action from a risk
- Refresh dashboard
- Evaluate and persist deployment gate
Each write action calls the REST API, persists to `data/database.json`, reloads the dashboard, and recalculates scores. The form includes a score preview using probability, impact, and detectability.
Detailed notes are in `docs/09-step-3-risk-crud-ui.md`.
## Step 4: Mitigation workflow implemented
The Mitigations page includes:
- Mitigation summary cards.
- Mitigation search and status filter.
- Create mitigation from the mitigation page or risk register.
- Edit mitigation progress, effectiveness, owner, due date, and status.
- Mark mitigation as done.
- Delete mitigation actions.
- Link evidence title, type, and URL/reference.
- Recalculate residual risk after every mitigation change.
Added files and changes:
- `tests/mitigation-workflow.test.js`
- `docs/10-step-4-mitigation-workflow.md`
- Updated `public/index.html`
- Updated `public/app.js`
- Updated `public/styles.css`
- Updated `src/domain/dataMapper.js`
- Updated `src/repositories/riskRepository.js`
- Updated `server.js`
- Updated `openapi.yaml`
Run all tests with:
```bash
npm test
```
## Step 6: Multi-PM integration implemented
The project-management integration layer now supports four applications through one adapter model:
- Trello: board, list, card, checklist item, custom field or badge.
- Jira: project, issue, workflow status, sub-task or linked issue, custom field.
- Asana: project, task, section or custom status field, subtask, custom field.
- Microsoft Planner: Microsoft 365 plan, task, bucket or progress state, checklist item, task details/reference.
The implementation uses seed connector configurations in `data/database.json`. The current sync is a local adapter simulation that creates external work-item mappings without calling live third-party APIs. This keeps the academic prototype testable without API credentials.
Added files and changes:
- `src/services/integrationService.js`
- `tests/integration-workflow.test.js`
- `docs/12-step-6-multi-pm-integration.md`
- Updated `public/index.html`
- Updated `public/app.js`
- Updated `server.js`
- Updated `openapi.yaml`
- Updated UML, use case, sequence, ER, and SQL design files
## Step 6.1: Microsoft Planner integration added
Microsoft Planner is now included as a fourth project-management provider in the shared adapter layer.
Planner mapping:
- COSMIC project maps to a Microsoft Planner plan.
- COSMIC risk maps to a Planner task.
- Risk status maps to a bucket or progress state.
- Mitigation action maps to a task checklist item.
- Evidence maps to a task reference or checklist evidence.
- Authentication mode is modeled as Microsoft Graph OAuth.
The current implementation remains a local adapter simulation. It does not call live Microsoft Graph endpoints yet.
## Step 7: Reporting and export implemented
The Reports page and API endpoints package dashboard evidence into instructor-ready exports.
Included reports:
- Executive HTML report for browser printing or saving as PDF.
- Full JSON evidence package.
- Risk register CSV.
- Mitigation CSV.
- Deployment gate report.
- Indicator report.
- Project-management integration report.
- Audit trail report.
Added files and changes:
- `src/services/reportingService.js`
- `tests/reporting-workflow.test.js`
- `docs/14-step-7-reporting-export.md`
- Updated `public/index.html`
- Updated `public/app.js`
- Updated `public/styles.css`
- Updated `server.js`
- Updated `openapi.yaml`
- Updated UML, use case, sequence, ER, and SQL design files
Example report commands:
```bash
curl http://localhost:8090/api/projects/cosmic-ai-risk-001/reports/executive
curl http://localhost:8090/api/projects/cosmic-ai-risk-001/reports/risk-register.csv
curl http://localhost:8090/api/projects/cosmic-ai-risk-001/reports/executive.html
```
## Step 7.1, OAuth and live PM connectors
The dashboard now includes OAuth credential handling and live third-party API client boundaries for:
- Trello
- Jira Cloud
- Asana
- Microsoft Planner through Microsoft Graph
Credentials must be provided through environment variables. Do not hardcode secrets in source files.
Use `.env.example` as the setup template.
Core safety variables:
```bash
export COSMIC_TOKEN_ENCRYPTION_KEY="replace-with-long-random-secret"
export COSMIC_LIVE_PM_ENABLED="false"
```
Live calls are disabled unless this is explicitly set:
```bash
export COSMIC_LIVE_PM_ENABLED="true"
```
New OAuth and live connector endpoints:
```text
GET /api/oauth/providers
GET /api/oauth/{provider}/status
GET /api/oauth/{provider}/authorize
GET /api/oauth/{provider}/callback
POST /api/oauth/Trello/store-token
GET /api/integrations/{integrationId}/live/status
POST /api/integrations/{integrationId}/live/test
POST /api/integrations/{integrationId}/live/sync
```
Run the new connector tests:
```bash
npm run test:oauth
```
The OAuth callback stores tokens only when `COSMIC_TOKEN_ENCRYPTION_KEY` is configured. Tokens are encrypted locally and only redacted values are exposed in API responses.
## Step 8: User roles and access control
The dashboard now includes role-based access control for governance-sensitive workflows.
New supported roles:
- System Admin
- Project Manager
- Risk Owner
- AI Engineer / Data Scientist
- Governance Reviewer
- Legal / Ethics Reviewer
- Integration Admin
- Read-only Viewer
The API reads the current actor from:
```http
X-Cosmic-User-Id: USER-GOV
```
New access endpoints:
```text
GET /api/access/me
GET /api/access/permissions
POST /api/access/seed-defaults
GET /api/users
POST /api/users
GET /api/users/{userId}
PATCH /api/users/{userId}
GET /api/roles
POST /api/roles
GET /api/roles/{roleId}
PATCH /api/roles/{roleId}
```
Run the access-control test:
```bash
npm run test:access
```
The UI includes an **Access control** tab where the active actor can be switched to test permissions.
## Step 9: Production deployment and security hardening
The dashboard now includes an operations layer for server deployment.
New operational endpoints:
```text
GET /api/ready
GET /api/operations/security
GET /api/operations/backups
POST /api/operations/backups
```
New scripts:
```bash
npm run check:config
npm run backup
npm run test:ops
npm run start:prod
```
Deployment files:
```text
Dockerfile
docker-compose.yml
deploy/nginx.conf
deploy/cosmic-ai-risk-dashboard.service
```
Production environment example:
```bash
NODE_ENV=production
PORT=8090
COSMIC_PUBLIC_BASE_URL=https://your-domain.example
COSMIC_TRUST_PROXY=true
COSMIC_FORCE_HTTPS=true
COSMIC_HSTS_ENABLED=true
COSMIC_SECURITY_HEADERS_ENABLED=true
COSMIC_ALLOWED_ORIGINS=https://your-domain.example
COSMIC_FRAME_ANCESTORS='self'
COSMIC_TOKEN_ENCRYPTION_KEY=replace-with-a-long-random-production-secret
COSMIC_BACKUP_DIR=./backups
COSMIC_BACKUP_RETENTION=10
```
For a reverse-proxy deployment, terminate TLS at Nginx and forward requests to the Node.js process on port `8090`. Use `deploy/nginx.conf` as the starting configuration.
The backup workflow copies the JSON database and writes a SHA-256 manifest. Backups may contain encrypted OAuth token payloads, so the backup directory must be protected as sensitive operational data.
## Step 10: Final Academic Documentation and Instructor Submission Package
The project now includes a final submission layer for instructor evaluation.
Added files:
- `SUBMISSION-README.md`
- `docs/18-step-10-final-academic-submission.md`
- `docs/19-final-report-draft.md`
- `docs/20-instructor-submission-checklist.md`
- `docs/21-demo-script.md`
- `docs/22-traceability-matrix.md`
- `docs/23-testing-evidence.md`
- `docs/24-evaluation-rubric-mapping.md`
- `docs/25-final-deployment-runbook.md`
- `docs/26-known-limitations-and-future-work.md`
Use these files to submit, present, and defend the project. The recommended evaluation order is:
1. Review the final report draft.
2. Review the UML, use case, sequence, and database diagrams.
3. Review the traceability matrix.
4. Run the automated tests.
5. Follow the demo script.
6. Review the production deployment runbook.