> ## 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.

# Introduction

> Overview of the CGIAR Risk Intelligence Tool for agricultural SME risk assessment

The CGIAR Risk Intelligence Tool is a web-based platform designed to assess the risk profile of agricultural small and medium enterprises (SMEs) in Kenya. The system enables analysts to evaluate businesses across seven risk dimensions, generating comprehensive risk assessments and actionable recommendations.

## What It Does

The platform automates the risk assessment workflow from data intake to final report generation:

<Steps>
  <Step title="Data Intake">
    Analysts can collect business information through three modes:

    * **Upload**: Extract data from business plan PDFs or DOCX files
    * **Guided Interview**: Step-by-step questionnaire for structured data collection
    * **Manual Entry**: Direct input of financial and operational data
  </Step>

  <Step title="Gap Detection">
    AI-powered validation identifies missing or incomplete data fields across all risk categories, ensuring data completeness before analysis.
  </Step>

  <Step title="Risk Analysis">
    The system scores the business across 7 risk categories with 35 total indicators (5 subcategories per category), each rated as High, Medium, or Low.
  </Step>

  <Step title="Report Generation">
    Generate downloadable PDF reports with risk scorecards, evidence-based narratives, and prioritized recommendations.
  </Step>
</Steps>

## Risk Assessment Model

Every assessment evaluates businesses across **7 risk categories**, each containing **5 subcategories** for a total of **35 risk indicators**:

<CardGroup cols={2}>
  <Card title="Financial Risk" icon="dollar-sign">
    Revenue stability, cost management, credit access, liquidity, capital structure
  </Card>

  <Card title="Climate-Environmental Risk" icon="cloud-rain">
    Weather exposure, climate adaptation, water access, biodiversity impact, carbon footprint
  </Card>

  <Card title="Behavioral Risk" icon="users">
    Management competence, governance practices, compliance, innovation capacity, stakeholder relations
  </Card>

  <Card title="Operational Risk" icon="settings">
    Supply chain resilience, production capacity, technology adoption, HR management, quality control
  </Card>

  <Card title="Market Risk" icon="trending-up">
    Demand volatility, competitive pressure, pricing power, distribution channels, regulatory environment
  </Card>

  <Card title="Governance & Legal Risk" icon="shield">
    Legal structure, contract management, intellectual property, regulatory compliance, financial reporting
  </Card>

  <Card title="Technology & Data Risk" icon="laptop">
    IT infrastructure, data management, cybersecurity, digital tools adoption, analytics capabilities
  </Card>
</CardGroup>

<Info>
  Each indicator uses a **traffic light scoring system**: High (Red), Medium (Yellow), Low (Green). The overall risk score is calculated as a weighted average across all 35 indicators.
</Info>

## Who It's For

### Analysts

Analysts are the primary users who create and manage risk assessments. Key capabilities:

* Create new assessments and select intake mode
* Upload business documents (PDF/DOCX) for automated parsing
* Review and correct data gaps identified by the system
* View risk scorecards with subcategory breakdowns
* Edit AI-generated recommendations for clarity and context
* Generate and download PDF reports
* Search and filter assessments on the dashboard

### Administrators

Administrators have full system access with additional management privileges:

* All analyst capabilities
* User management (create, edit, disable accounts)
* Prompt management for AI agents (parser, gap detector, risk analyzer, report generator)
* Version control and change tracking for prompts
* System configuration and monitoring

<Note>
  User roles are managed through AWS Cognito user groups. Users in the `admin` group have administrator privileges.
</Note>

## Key Features

### Multi-Agent AI Pipeline

The platform uses **AWS Bedrock** with Claude 3.5 Sonnet v2 across four specialized agents:

```mermaid theme={null}
graph LR
    A[Document Upload] --> B[Parser Agent]
    B --> C[Gap Detector Agent]
    C --> D[Risk Analysis Agent]
    D --> E[Report Generator Agent]
    E --> F[PDF Report]
```

* **Parser Agent**: Extracts structured data from unstructured business documents
* **Gap Detector Agent**: Validates completeness across all 35 risk indicators
* **Risk Analysis Agent**: Scores each indicator and generates evidence-based narratives
* **Report Generator Agent**: Creates formatted PDF reports with recommendations

### Asynchronous Job Processing

Long-running AI operations use a fire-and-forget pattern:

1. API creates a Job record with status `PENDING`
2. Worker Lambda processes the job asynchronously
3. Frontend polls job status until `COMPLETED` or `FAILED`

<Accordion title="API Endpoints for Job Polling">
  ```typescript theme={null}
  // Create a job (returns immediately with job ID)
  POST /api/assessments/:id/documents/:documentId/parse

  // Poll job status
  GET /api/jobs/:jobId
  Response: {
    id: string,
    type: 'PARSE_DOCUMENT' | 'GAP_DETECTION' | 'RISK_ANALYSIS' | 'REPORT_GENERATION',
    status: 'PENDING' | 'PROCESSING' | 'COMPLETED' | 'FAILED',
    result?: object,
    error?: string
  }
  ```
</Accordion>

### Real-Time Collaboration

* **Assessment Comments**: Add notes and observations to assessments
* **Prompt Comments**: Threaded discussions on AI prompt improvements (admin only)
* **Change History**: Track all modifications to prompts with version snapshots

### Data Security

<CardGroup cols={2}>
  <Card title="Authentication" icon="lock">
    AWS Cognito with email-based authentication, password policies, and forgot-password flows
  </Card>

  <Card title="Authorization" icon="user-shield">
    Role-based access control with JWT tokens, session management, and auto-refresh
  </Card>

  <Card title="Data Encryption" icon="shield-check">
    RDS PostgreSQL with encryption at rest, Secrets Manager for credentials
  </Card>

  <Card title="File Storage" icon="database">
    S3 with pre-signed URLs for secure upload/download, private bucket with VPC endpoints
  </Card>
</CardGroup>

## Technology Stack

### Frontend

* **Next.js 15** with App Router and static export for S3 hosting
* **React 19** with TypeScript
* **Tailwind CSS** v4 for styling
* **shadcn/ui** component library
* **React Query** for server state management
* **React Hook Form** for form validation

### Backend

* **NestJS 10** REST API with TypeScript
* **Prisma** ORM with PostgreSQL
* **AWS SDK** for Bedrock, S3, Lambda, Cognito
* **AWS Lambda** on ARM64 architecture (Node.js 20)
* **API Gateway HTTP API** with 30-second timeout

### Infrastructure

* **AWS CloudFormation** / **CDK** for infrastructure as code
* **RDS PostgreSQL 15** in private VPC
* **CloudFront** CDN for web hosting
* **Cognito User Pool** for authentication
* **Bedrock** for AI model orchestration

<Tip>
  The platform uses a **monorepo architecture** with pnpm workspaces:

  * `@alliance-risk/api` - NestJS backend
  * `@alliance-risk/web` - Next.js frontend
  * `@alliance-risk/shared` - Shared types and constants
  * `@alliance-risk/infra` - AWS infrastructure
</Tip>

## Getting Help

For technical support or questions:

* **Repository**: Internal CGIAR repository
* **License**: Proprietary - CGIAR / Alliance of Bioversity International and CIAT
* **Support**: Contact your system administrator for access issues or bug reports