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/08-step-2-storage-layer.md (5325B)

# Step 2: Data Model and Storage Layer

## Purpose

This step converts the design-first database entity model into a working storage layer for the COSMIC AI-Risk Dashboard.

The implementation uses JSON file storage first so the project can remain simple, inspectable, and easy to demonstrate. The structure mirrors the relational entity model in `05-database-schema.sql`, so the application can later move to SQLite or PostgreSQL without changing the domain concepts.

## Source traceability

Source-derived concepts:

- COSMIC-Risk requires a measurable software prototype and REST API.
- The dashboard must support organizational, technical, and human AI risk dimensions.
- Risk indicators must include measurands, units, and interpretation rules.
- AI project risk analysis must support project-management integration.

Implementation extension:

- JSON database file.
- Repository classes.
- CRUD API endpoints.
- Audit-event recording.
- Persisted gate evaluations.
- Seeded relational-style tables.

## Added storage file

```text
/data/database.json
```

This file contains normalized tables:

```text
roles
users
projects
lifecycle_phases
risks
risk_scores
mitigation_actions
indicators
measurement_records
experiments
model_metrics
deployment_gates
gate_criteria
gate_decisions
evidence_artifacts
audit_events
trello_mappings
```

## Added backend modules

```text
src/storage/jsonDatabase.js
src/domain/dataMapper.js
src/domain/validation.js
src/repositories/projectRepository.js
src/repositories/riskRepository.js
src/services/dashboardService.js
```

## Storage responsibilities

| Layer | Responsibility |
|---|---|
| `JsonDatabase` | Read, write, transaction, atomic file replacement |
| `dataMapper` | Convert database tables into dashboard aggregate payloads |
| `validation` | Validate risk and mitigation inputs before storage |
| `ProjectRepository` | Load projects and project aggregates |
| `RiskRepository` | Create, read, update, delete risks and mitigations |
| `DashboardService` | Calculate dashboard, score risk, evaluate gate, persist gate evidence |

## Implemented API endpoints

| Method | Endpoint | Purpose |
|---|---|---|
| GET | `/api/health` | Health check and storage mode |
| GET | `/api/projects` | List projects |
| GET | `/api/projects/{projectId}` | Read one project |
| GET | `/api/dashboard` | Backward-compatible default dashboard |
| GET | `/api/projects/{projectId}/dashboard` | Full dashboard payload |
| GET | `/api/projects/{projectId}/risks` | List scored risks |
| POST | `/api/projects/{projectId}/risks` | Create a new risk |
| GET | `/api/risks/{riskId}` | Read one scored risk |
| PATCH | `/api/risks/{riskId}` | Update a risk |
| DELETE | `/api/risks/{riskId}` | Delete a risk and child records |
| GET | `/api/projects/{projectId}/mitigations` | List project mitigations |
| POST | `/api/risks/{riskId}/mitigations` | Add mitigation to a risk |
| PATCH | `/api/mitigations/{mitigationId}` | Update mitigation progress or status |
| GET | `/api/projects/{projectId}/gate` | Calculate current gate status |
| POST | `/api/projects/{projectId}/gate/evaluate` | Evaluate and persist gate decision |
| GET | `/api/projects/{projectId}/indicators` | List indicator catalog |
| GET | `/api/projects/{projectId}/metrics` | List experiments and model metrics |
| POST | `/api/calculate-risk` | Calculate one risk score without saving |

## Example create-risk request

```bash
curl -X POST http://localhost:8090/api/projects/cosmic-ai-risk-001/risks \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Model rollback plan missing",
    "dimension": "Technical",
    "domain": "Technical risks",
    "lifecyclePhase": "Deployment, support, and monitoring",
    "probability": 3,
    "impact": 5,
    "detectability": 3,
    "owner": "MLOps Lead",
    "mitigations": ["Define rollback criteria", "Test model rollback workflow"]
  }'
```

## Example update-risk request

```bash
curl -X PATCH http://localhost:8090/api/risks/R-001 \
  -H "Content-Type: application/json" \
  -d '{
    "status": "In mitigation",
    "approvalStatus": "Approved"
  }'
```

## Example gate evaluation request

```bash
curl -X POST http://localhost:8090/api/projects/cosmic-ai-risk-001/gate/evaluate
```

This stores records in:

```text
deployment_gates
gate_criteria
gate_decisions
risk_scores
```

## Acceptance criteria

| Check | Result |
|---|---|
| JSON database exists | Complete |
| Repository layer exists | Complete |
| Dashboard aggregate loads from normalized data | Complete |
| Risk CRUD works | Complete |
| Mitigation creation and update work | Complete |
| Gate evaluation persists decision evidence | Complete |
| Audit events are recorded | Complete |
| Existing dashboard still loads | Complete |
| Risk-engine tests pass | Complete |
| Storage-layer tests pass | Complete |

## Test command

```bash
npm test
```

Expected result:

```text
All COSMIC AI-Risk engine tests passed.
All COSMIC AI-Risk storage layer tests passed.
```

## Next development step

Step 3 should implement the full application service layer and UI workflows for risk CRUD:

1. Add risk form in the dashboard.
2. Edit risk from the risk table.
3. Add mitigation action from a risk detail panel.
4. Refresh dashboard score after saving changes.
5. Add frontend tests or manual test script.

cmd: