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

# Quickstart Guide

> Step-by-step guide from account setup to completing your first risk assessment

This guide walks you through creating your first risk assessment, from logging in to generating a final PDF report.

## Prerequisites

Before starting, ensure you have:

<CardGroup cols={2}>
  <Card title="Account Access" icon="user-check">
    A valid user account created by an administrator with your email address
  </Card>

  <Card title="Initial Password" icon="key">
    The temporary password provided by your administrator (you'll change this on first login)
  </Card>

  <Card title="Sample Data" icon="file-text">
    A business plan document (PDF or DOCX) or business information ready for manual entry
  </Card>

  <Card title="Modern Browser" icon="globe">
    Chrome, Firefox, Safari, or Edge (latest version recommended)
  </Card>
</CardGroup>

## Step 1: First Login and Password Setup

<Steps>
  <Step title="Navigate to the login page">
    Open the application URL provided by your administrator and click **Login**.
  </Step>

  <Step title="Enter your credentials">
    ```text theme={null}
    Email: your.email@example.com
    Password: [temporary password from admin]
    ```
  </Step>

  <Step title="Complete password change">
    On first login, you'll be prompted to set a new password. Your password must meet these requirements:

    * Minimum 8 characters
    * At least one uppercase letter
    * At least one lowercase letter
    * At least one number
    * At least one special character (@\$!%\*?&)
  </Step>

  <Step title="Choose session persistence">
    Check **Remember Me** to stay logged in for 30 days. Leave unchecked for session-only authentication (expires when browser closes).
  </Step>
</Steps>

<Warning>
  After 3 failed login attempts, your account will be temporarily locked. Contact your administrator to reset if this occurs.
</Warning>

## Step 2: Create a New Assessment

<Steps>
  <Step title="Access the dashboard">
    After login, you'll see the dashboard with assessment statistics:

    * Total Assessments
    * Completed
    * Active (in progress)
    * Drafts
  </Step>

  <Step title="Start new assessment">
    Click the **Start Assessment** button in the top navigation bar.
  </Step>

  <Step title="Enter basic information">
    ```typescript theme={null}
    Assessment Name: "Q1 2026 - Acme Agro Ltd"
    Company Name: "Acme Agro Ltd"
    Company Type: "Agricultural SME" (optional)
    Country: "Kenya" (default)
    ```
  </Step>

  <Step title="Select intake mode">
    Choose one of three data collection methods:

    <Tabs>
      <Tab title="Upload">
        **Best for**: Businesses with existing business plans or pitch decks

        Upload PDF or DOCX files containing business information. The AI parser will extract:

        * Company background and mission
        * Financial projections and statements
        * Market analysis and competitive landscape
        * Operational details and supply chain
        * Management team and governance
      </Tab>

      <Tab title="Guided Interview">
        **Best for**: Structured data collection with the business owner

        Step-by-step questionnaire covering:

        * Business model and value proposition
        * Revenue streams and cost structure
        * Risk exposure and mitigation strategies
        * Technology and operational capacity
      </Tab>

      <Tab title="Manual Entry">
        **Best for**: Analysts with pre-collected data

        Direct input of financial metrics, operational KPIs, and risk indicators across all 7 categories.
      </Tab>
    </Tabs>
  </Step>
</Steps>

## Step 3: Document Upload and Parsing

<Info>
  This section applies to assessments using the **Upload** intake mode. Skip to Step 4 if using Guided Interview or Manual Entry.
</Info>

<Steps>
  <Step title="Upload business document">
    Drag and drop or click to select a PDF/DOCX file (max 10MB):

    ```bash theme={null}
    Supported formats:
    - PDF (.pdf)
    - Microsoft Word (.docx)

    File size limit: 10 MB
    ```
  </Step>

  <Step title="Trigger document parsing">
    Click **Parse Document** to start AI extraction. This creates an asynchronous job.

    The system will:

    1. Upload file to S3 with pre-signed URL
    2. Create a `PARSE_DOCUMENT` job
    3. Invoke Worker Lambda with Claude 3.5 Sonnet v2
    4. Extract structured data across all 35 risk indicators
  </Step>

  <Step title="Monitor parsing progress">
    A progress indicator shows the current job status:

    * **Pending**: Job queued for processing
    * **Processing**: AI is extracting data (typically 30-60 seconds)
    * **Completed**: Data extracted successfully
    * **Failed**: Error occurred (check error message)

    <Accordion title="API Request Pattern">
      ```typescript theme={null}
      // Create parse job
      POST /api/assessments/:id/documents/:documentId/parse

      // Frontend polls every 3 seconds
      GET /api/jobs/:jobId

      // Stop polling when status is COMPLETED or FAILED
      if (job.status === 'COMPLETED') {
        // Proceed to gap detection
        navigateTo('/assessments/gap-detector?id=' + assessmentId);
      }
      ```
    </Accordion>
  </Step>

  <Step title="Automatic gap detection">
    Upon successful parsing, the system automatically chains a `GAP_DETECTION` job to identify missing data fields.
  </Step>
</Steps>

<Tip>
  Parsing and gap detection typically complete within 2 minutes. Large documents (>50 pages) may take up to 5 minutes.
</Tip>

## Step 4: Review and Fill Data Gaps

<Steps>
  <Step title="Navigate to Gap Detector">
    Click **Review Gaps** or navigate to the Gap Detector page from the assessment menu.
  </Step>

  <Step title="Review identified gaps">
    The system displays all 35 risk indicators grouped by category, each marked as:

    * **Verified** (green): Data extracted and validated
    * **Partial** (yellow): Data found but incomplete or low confidence
    * **Missing** (red): No data found

    ```typescript theme={null}
    Example gap field:
    {
      category: 'FINANCIAL',
      field: 'revenue_projection_year_1',
      label: 'Revenue Projection - Year 1',
      status: 'MISSING',
      extractedValue: null,
      correctedValue: null,
      isMandatory: true
    }
    ```
  </Step>

  <Step title="Fill missing data">
    For each missing or partial field:

    1. Review the extracted value (if any)
    2. Enter the correct value or additional information
    3. Click **Save** to update the field

    The `correctedValue` field stores your input and takes precedence over `extractedValue`.
  </Step>

  <Step title="Verify completeness">
    Before proceeding to risk analysis, ensure:

    * All **mandatory** fields are filled (marked with red asterisk)
    * At least 80% of fields have data for accurate scoring
    * Financial figures use consistent currency (KES by default)
  </Step>
</Steps>

<Warning>
  Risk analysis requires minimum data thresholds:

  * Financial: 4/5 subcategories
  * Climate-Environmental: 3/5 subcategories
  * All other categories: 3/5 subcategories minimum

  Insufficient data will result in `MODERATE` risk scores with low confidence.
</Warning>

## Step 5: Run Risk Analysis

<Steps>
  <Step title="Trigger risk analysis">
    Click **Analyze Risk** to create a `RISK_ANALYSIS` job.

    The AI agent will:

    * Score all 35 indicators on a 0-100 scale
    * Map scores to risk levels: 0-33 (Low), 34-66 (Medium), 67-100 (High)
    * Generate evidence-based narratives for each category
    * Create prioritized recommendations
  </Step>

  <Step title="View risk scorecard">
    Once analysis completes, navigate to the Risk Scorecard page to see:

    <CodeGroup>
      ```json Overall Risk Score theme={null}
      {
        "overallRiskScore": 54.3,
        "overallRiskLevel": "MODERATE",
        "categoryScores": [
          {
            "category": "FINANCIAL",
            "score": 68.5,
            "level": "HIGH",
            "subcategories": [
              { "name": "Revenue Stability", "score": 72, "level": "HIGH" },
              { "name": "Cost Management", "score": 65, "level": "MEDIUM" },
              // ... 3 more subcategories
            ]
          },
          // ... 6 more categories
        ]
      }
      ```

      ```json Risk Evidence theme={null}
      {
        "category": "FINANCIAL",
        "evidence": "Revenue projections show 40% dependency on single buyer contract expiring Q3 2026. Limited diversification in customer base creates concentration risk.",
        "narrative": "Financial risk is elevated due to revenue concentration and limited working capital reserves..."
      }
      ```
    </CodeGroup>
  </Step>

  <Step title="Review subcategory breakdowns">
    Click each category card to expand subcategory details:

    * Individual subcategory scores (0-100)
    * Traffic light indicators (red/yellow/green)
    * Data sources and assumptions
  </Step>

  <Step title="Edit recommendations (optional)">
    Click **Edit** on any recommendation to:

    * Clarify language for the business owner
    * Add context-specific details
    * Adjust priority (High/Medium/Low)

    ```typescript theme={null}
    PUT /api/assessments/:id/recommendations/:recId
    {
      "editedText": "Diversify customer base by targeting 3-5 additional buyers in Q2 2026 to reduce revenue concentration below 25% per customer.",
      "priority": "HIGH"
    }
    ```

    Original AI-generated text is preserved; your edits are stored separately.
  </Step>
</Steps>

<Note>
  Risk scores are recalculated automatically if you update data in the Gap Detector. Changes to gap fields do NOT trigger automatic re-analysis; you must manually click **Re-analyze** to refresh scores.
</Note>

## Step 6: Generate PDF Report

<Steps>
  <Step title="Navigate to Report page">
    From the Risk Scorecard, click **Generate Report** or navigate to the Report page.
  </Step>

  <Step title="Preview report sections">
    Review the report structure:

    1. Executive Summary (overall risk level + key findings)
    2. Company Profile (extracted from intake data)
    3. Risk Scorecard (all 7 categories with subcategory breakdowns)
    4. Evidence and Narratives (category-level explanations)
    5. Recommendations (prioritized by High/Medium/Low)
    6. Appendices (data sources, methodology)
  </Step>

  <Step title="Generate PDF">
    Click **Download PDF** to trigger the `REPORT_GENERATION` job.

    The system will:

    1. Fetch all assessment data (gaps, scores, recommendations, comments)
    2. Render HTML template with data
    3. Convert HTML to PDF using headless Chrome (AWS Lambda)
    4. Upload PDF to S3
    5. Return pre-signed download URL (expires in 1 hour)
  </Step>

  <Step title="Download and review">
    Once generation completes (typically 20-30 seconds):

    1. Click the download link
    2. Save the PDF locally
    3. Review for accuracy and completeness
    4. Share with stakeholders as needed
  </Step>
</Steps>

<Tip>
  Generated PDFs are stored in S3 for 90 days. You can re-download from the Report page within this period. After 90 days, click **Regenerate** to create a new PDF.
</Tip>

## Step 7: Manage Assessments

### Search and Filter

Use the dashboard search bar to find assessments:

```typescript theme={null}
// Search by company name, assessment name, or status
GET /api/assessments?search=acme&status=COMPLETE&limit=10

Response: {
  data: Assessment[],
  total: number,
  nextCursor?: string  // For pagination
}
```

### Assessment Statuses

<CardGroup cols={2}>
  <Card title="DRAFT" icon="file-edit">
    Assessment created but not yet started. Intake mode selected, no data collected.
  </Card>

  <Card title="ANALYZING" icon="loader">
    Active jobs running (parsing, gap detection, or risk analysis in progress).
  </Card>

  <Card title="ACTION_REQUIRED" icon="alert-circle">
    Gap detection complete, awaiting data input or corrections before analysis.
  </Card>

  <Card title="COMPLETE" icon="check-circle">
    Risk analysis finished, PDF report generated. Ready for review and export.
  </Card>
</CardGroup>

### Edit or Delete Assessments

* **Edit**: Click the row in the dashboard table to navigate to the Gap Detector page
* **Resume Draft**: Click **Resume** on draft assessments to continue from the intake step
* **Delete**: Click the trash icon and confirm deletion (cannot be undone)

<Warning>
  Deleting an assessment removes all associated data:

  * Uploaded documents (deleted from S3)
  * Gap fields and corrections
  * Risk scores and recommendations
  * Generated PDF reports
  * Assessment comments

  This action is **permanent** and cannot be reversed.
</Warning>

## Next Steps

<CardGroup cols={3}>
  <Card title="Architecture" href="/architecture" icon="network-wired">
    Learn how the system works under the hood
  </Card>

  <Card title="API Reference" href="/api/auth/login" icon="code">
    Explore all available API endpoints
  </Card>

  <Card title="User Management" href="/guides/user-management" icon="users-cog">
    Manage users and permissions (admin only)
  </Card>
</CardGroup>

## Common Issues

<Accordion title="Document parsing fails with 'Unsupported format' error">
  **Cause**: The uploaded file is not a valid PDF or DOCX, or is corrupted.

  **Solution**:

  1. Verify file extension is `.pdf` or `.docx` (not `.doc`, `.odt`, etc.)
  2. Try opening the file locally to confirm it's not corrupted
  3. Re-export from source application (Word, Google Docs) and re-upload
  4. If using scanned PDF, ensure it contains text (not just images)
</Accordion>

<Accordion title="Risk analysis job stuck in PROCESSING for >5 minutes">
  **Cause**: Worker Lambda may have timed out or encountered a Bedrock throttling error.

  **Solution**:

  1. Refresh the page - job status may be stale
  2. Check if status changed to FAILED (error message will be displayed)
  3. If still PROCESSING, wait 2 more minutes then contact administrator
  4. Administrator can check CloudWatch logs: `/aws/lambda/alliance-risk-worker`
</Accordion>

<Accordion title="Can't download PDF - 'Download link expired' error">
  **Cause**: Pre-signed S3 URLs expire after 1 hour for security.

  **Solution**:

  1. Navigate back to the Report page for the assessment
  2. Click **Download PDF** again to generate a fresh pre-signed URL
  3. Download within 1 hour of generating the link
</Accordion>

<Accordion title="Session expired / logged out unexpectedly">
  **Cause**: JWT access token expired (default 60 minutes) and refresh token rotation failed.

  **Solution**:

  1. Log in again with your email and password
  2. Check **Remember Me** to extend session to 30 days
  3. If using multiple browser tabs, close inactive tabs to prevent token conflicts
</Accordion>