> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/AllianceBioversityCIAT/alliance-risk-analysis-tool/llms.txt
> Use this file to discover all available pages before exploring further.

# Risk Scoring System

> Comprehensive 7-category risk assessment with subcategory scoring, traffic-light indicators, and AI-generated recommendations

## Overview

The CGIAR Risk Intelligence Tool evaluates partner organizations across **7 major risk categories**, each containing **5 subcategories**. This multi-dimensional approach provides a comprehensive risk profile using industry-standard assessment methodologies.

## Risk Categories

Every assessment generates scores across these categories:

<CardGroup cols={2}>
  <Card title="Financial Risk" icon="dollar-sign">
    Revenue stability, profitability, debt levels, cash flow, and financial sustainability
  </Card>

  <Card title="Operational Risk" icon="cogs">
    Supply chain reliability, operational capacity, quality control, logistics, and resource management
  </Card>

  <Card title="Market Risk" icon="chart-line">
    Market volatility, competition, demand fluctuations, pricing pressures, and market access
  </Card>

  <Card title="Behavioral Risk" icon="users">
    Management integrity, organizational culture, stakeholder relationships, and ethical conduct
  </Card>

  <Card title="Climate-Environmental Risk" icon="leaf">
    Climate change exposure, environmental impact, resource depletion, and sustainability practices
  </Card>

  <Card title="Governance & Legal Risk" icon="gavel">
    Legal compliance, regulatory requirements, governance structure, and policy adherence
  </Card>

  <Card title="Technology & Data Risk" icon="server">
    Technology infrastructure, data security, digital capabilities, and cybersecurity posture
  </Card>
</CardGroup>

## Risk Levels (Traffic-Light System)

Risk scores are mapped to four standardized levels:

<AccordionGroup>
  <Accordion title="🟢 LOW (0-24)" icon="circle" iconType="solid" color="green">
    **Minimal risk detected.** Standard monitoring procedures are sufficient.

    * Strong performance indicators
    * Robust controls in place
    * Low probability of adverse events
    * Recommended action: Continue routine oversight
  </Accordion>

  <Accordion title="🟡 MODERATE (25-49)" icon="circle" iconType="solid" color="yellow">
    **Acceptable risk with monitoring.** Enhanced oversight recommended.

    * Some areas of concern identified
    * Adequate controls with room for improvement
    * Moderate probability of issues
    * Recommended action: Implement specific mitigation measures
  </Accordion>

  <Accordion title="🟠 HIGH (50-74)" icon="circle" iconType="solid" color="orange">
    **Significant risk requiring active management.** Mitigation plan required.

    * Multiple risk factors present
    * Controls need strengthening
    * Elevated probability of adverse outcomes
    * Recommended action: Develop comprehensive risk reduction strategy
  </Accordion>

  <Accordion title="🔴 CRITICAL (75-100)" icon="circle" iconType="solid" color="red">
    **Unacceptable risk level.** Immediate intervention required.

    * Severe risk exposure
    * Inadequate or missing controls
    * High probability of significant negative impact
    * Recommended action: Consider partnership suspension or major remediation
  </Accordion>
</AccordionGroup>

## Scoring Methodology

### Category Score Calculation

Each category score is computed from its 5 subcategories:

<Steps>
  <Step title="Subcategory Analysis">
    AI agents analyze extracted data and generate scores (0-100) for each subcategory based on:

    * Documentary evidence from uploaded files
    * Interview responses or manual data entries
    * Industry benchmarks and standards
    * Historical performance data
  </Step>

  <Step title="Weighted Aggregation">
    Subcategory scores are aggregated using configurable weights. Default: equal weighting (20% each).

    ```typescript theme={null}
    categoryScore = Σ(subcategoryScore × weight) / Σ(weights)
    ```
  </Step>

  <Step title="Level Assignment">
    The numerical score is mapped to a risk level:

    * 0-24 → LOW
    * 25-49 → MODERATE
    * 50-74 → HIGH
    * 75-100 → CRITICAL
  </Step>
</Steps>

### Overall Risk Score

The overall assessment score is calculated as:

```typescript theme={null}
overallScore = (Σ all category scores) / 7
overallLevel = mapScoreToLevel(overallScore)
```

<Info>
  All scores are stored as floating-point numbers and rounded to the nearest integer for display.
</Info>

## Risk Score Data Model

Risk scores are stored per category with detailed subcategory breakdowns:

<CodeGroup>
  ```typescript RiskScore Schema theme={null}
  {
    id: string;
    assessmentId: string;
    category: RiskCategory;  // One of the 7 categories
    score: number;           // Aggregate category score (0-100)
    level: RiskLevel;        // LOW | MODERATE | HIGH | CRITICAL
    subcategories: SubcategoryScore[];  // Array of 5 subcategories
    evidence?: string;       // Supporting evidence summary
    narrative?: string;      // AI-generated risk narrative
  }
  ```

  ```typescript SubcategoryScore theme={null}
  {
    name: string;          // e.g., "Revenue Stability"
    indicator: string;     // Specific indicator measured
    score: number;         // Subcategory score (0-100)
    level: RiskLevel;      // Traffic-light level
    evidence: string;      // Evidence supporting this score
    mitigation: string;    // Suggested mitigation strategies
  }
  ```
</CodeGroup>

## Fetching Risk Scores

Risk scores are included in the report response:

<CodeGroup>
  ```typescript GET /api/assessments/:id/report theme={null}
  ```

  ```typescript Response theme={null}
  {
    "assessment": { /* Assessment details */ },
    "overallScore": 42,
    "overallLevel": "MODERATE",
    "executiveSummary": "Risk assessment for Green Valley Agritech...",
    "categories": [
      {
        "id": "score-123",
        "category": "FINANCIAL",
        "score": 38,
        "level": "MODERATE",
        "subcategories": [
          {
            "name": "Revenue Stability",
            "indicator": "Year-over-year revenue variance",
            "score": 42,
            "level": "MODERATE",
            "evidence": "Revenue declined 8% in FY2025 but stabilized in Q4",
            "mitigation": "Diversify customer base and develop new revenue streams"
          },
          {
            "name": "Profitability",
            "indicator": "Operating margin trend",
            "score": 35,
            "level": "MODERATE",
            "evidence": "Operating margin of 12% below industry average of 18%",
            "mitigation": "Optimize cost structure and improve operational efficiency"
          },
          // ... 3 more subcategories
        ],
        "evidence": "Financial statements show moderate volatility...",
        "narrative": "The Financial risk level is MODERATE based on analysis of revenue trends, profitability metrics, debt levels, cash flow patterns, and financial sustainability indicators.",
        "recommendations": [
          {
            "id": "rec-123",
            "text": "Develop a 3-year financial sustainability plan focusing on revenue diversification and cost optimization",
            "priority": "HIGH",
            "isEdited": false,
            "editedText": null
          },
          {
            "id": "rec-124",
            "text": "Implement quarterly financial health monitoring with early warning indicators",
            "priority": "MEDIUM",
            "isEdited": false,
            "editedText": null
          }
        ]
      },
      // ... 6 more categories
    ],
    "radarData": [
      { "category": "FINANCIAL", "score": 38 },
      { "category": "OPERATIONAL", "score": 45 },
      { "category": "MARKET", "score": 52 },
      { "category": "BEHAVIORAL", "score": 28 },
      { "category": "CLIMATE_ENVIRONMENTAL", "score": 61 },
      { "category": "GOVERNANCE_LEGAL", "score": 33 },
      { "category": "TECHNOLOGY_DATA", "score": 48 }
    ]
  }
  ```
</CodeGroup>

## Recommendations

Each risk category includes AI-generated recommendations prioritized by urgency:

<Tabs>
  <Tab title="HIGH Priority">
    Critical actions requiring immediate attention. These address severe risk exposures or control gaps.

    **Example:**

    > "Establish a formal risk management committee and implement quarterly board-level risk reviews to address governance deficiencies."
  </Tab>

  <Tab title="MEDIUM Priority">
    Important improvements that should be addressed within 3-6 months.

    **Example:**

    > "Develop standardized operating procedures for supply chain management to reduce operational variability."
  </Tab>

  <Tab title="LOW Priority">
    Enhancements that can be implemented as resources permit, typically within 6-12 months.

    **Example:**

    > "Consider implementing advanced analytics for demand forecasting to optimize inventory levels."
  </Tab>
</Tabs>

### Editing Recommendations

Analysts can manually refine AI-generated recommendations:

```typescript theme={null}
// Recommendations support in-place editing
{
  "id": "rec-123",
  "text": "Original AI-generated recommendation",
  "priority": "HIGH",
  "isEdited": true,
  "editedText": "Analyst-refined version with specific context and actionable steps"
}
```

<Note>
  The original AI-generated text is preserved when `isEdited` is true, allowing auditability of modifications.
</Note>

## Radar Chart Visualization

The `radarData` array provides data optimized for radar chart visualization:

```typescript theme={null}
import { Radar } from 'recharts';

<RadarChart data={report.radarData}>
  <PolarGrid />
  <PolarAngleAxis dataKey="category" />
  <PolarRadiusAxis domain={[0, 100]} />
  <Radar
    name="Risk Score"
    dataKey="score"
    stroke="#8884d8"
    fill="#8884d8"
    fillOpacity={0.6}
  />
</RadarChart>
```

## Risk Score Generation Pipeline

Scores are generated through the AI analysis pipeline:

<Steps>
  <Step title="Document Parsing">
    AWS Textract extracts text and tables from uploaded PDFs

    **See:** [AI Analysis - Parser Agent](/features/ai-analysis#parser-agent)
  </Step>

  <Step title="Gap Detection">
    AI identifies missing or incomplete data fields across all categories

    **See:** [AI Analysis - Gap Detector Agent](/features/ai-analysis#gap-detector-agent)
  </Step>

  <Step title="Risk Analysis">
    Multi-agent system scores each subcategory and generates narratives

    **See:** [AI Analysis - Risk Analysis Agent](/features/ai-analysis#risk-analysis-agent)

    **Job Type:** `RISK_ANALYSIS`
  </Step>

  <Step title="Score Aggregation">
    System calculates category scores, overall score, and assigns risk levels

    **Database Update:** Assessment record updated with `overallRiskScore` and `overallRiskLevel`
  </Step>
</Steps>

## Database Schema

<CodeGroup>
  ```prisma RiskScore Model theme={null}
  model RiskScore {
    id            String       @id @default(uuid())
    assessmentId  String
    category      RiskCategory
    score         Float
    level         RiskLevel
    subcategories Json         // SubcategoryScore[]
    evidence      String?      @db.Text
    narrative     String?      @db.Text

    assessment      Assessment       @relation(fields: [assessmentId], references: [id], onDelete: Cascade)
    recommendations Recommendation[]

    @@unique([assessmentId, category])
    @@map("risk_scores")
  }
  ```

  ```prisma Recommendation Model theme={null}
  model Recommendation {
    id          String                 @id @default(uuid())
    riskScoreId String
    text        String                 @db.Text
    priority    RecommendationPriority
    isEdited    Boolean                @default(false)
    editedText  String?                @db.Text
    order       Int                    @default(0)

    riskScore RiskScore @relation(fields: [riskScoreId], references: [id], onDelete: Cascade)

    @@index([riskScoreId])
    @@map("recommendations")
  }
  ```
</CodeGroup>

## Code Example: Risk Level Badge Component

```typescript components/risk-level-badge.tsx theme={null}
import { cn } from '@/lib/utils';
import type { RiskLevel } from '@alliance-risk/shared';

const LEVEL_STYLES: Record<RiskLevel, { bg: string; text: string; icon: string }> = {
  LOW: { bg: 'bg-green-100', text: 'text-green-800', icon: '🟢' },
  MODERATE: { bg: 'bg-yellow-100', text: 'text-yellow-800', icon: '🟡' },
  HIGH: { bg: 'bg-orange-100', text: 'text-orange-800', icon: '🟠' },
  CRITICAL: { bg: 'bg-red-100', text: 'text-red-800', icon: '🔴' }
};

export function RiskLevelBadge({ level, score }: { level: RiskLevel; score: number }) {
  const style = LEVEL_STYLES[level];
  
  return (
    <div className={cn('inline-flex items-center gap-2 px-3 py-1 rounded-full', style.bg)}>
      <span>{style.icon}</span>
      <span className={cn('font-semibold', style.text)}>
        {level}
      </span>
      <span className={cn('text-sm', style.text)}>({score})</span>
    </div>
  );
}
```

## Best Practices

<CardGroup cols={2}>
  <Card title="Validate Data Quality" icon="check-circle">
    Ensure gap fields are verified before risk analysis runs. Incomplete data leads to inaccurate scores.
  </Card>

  <Card title="Review AI Narratives" icon="eye">
    Always review AI-generated narratives and recommendations for accuracy and contextual relevance.
  </Card>

  <Card title="Track Score Changes" icon="chart-line">
    Monitor score changes over time to identify trends and measure mitigation effectiveness.
  </Card>

  <Card title="Use Subcategory Detail" icon="magnifying-glass">
    Don't rely solely on category-level scores. Drill down into subcategories for actionable insights.
  </Card>
</CardGroup>

## Related Resources

<CardGroup cols={2}>
  <Card title="Assessment Workflow" href="/features/assessments" icon="list-check">
    Understand the complete assessment lifecycle
  </Card>

  <Card title="AI Analysis Pipeline" href="/features/ai-analysis" icon="brain">
    Deep dive into the multi-agent AI system that generates scores
  </Card>

  <Card title="Report Generation" href="/features/report-generation" icon="file-pdf">
    Learn how scores are visualized in PDF reports
  </Card>
</CardGroup>