/home/techb158/trellopowerup.abdallabala.com/docs
Edit: /home/techb158/trellopowerup.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.