Quickstart Guide

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:

Account Access

A valid user account created by an administrator with your email address

Initial Password

The temporary password provided by your administrator (you’ll change this on first login)

Sample Data

A business plan document (PDF or DOCX) or business information ready for manual entry

Modern Browser

Chrome, Firefox, Safari, or Edge (latest version recommended)

Navigate to the login page

Open the application URL provided by your administrator and click Login.

Enter your credentials

Email: your.email@example.com
Password: [temporary password from admin]

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 (@$!%*?&)

Choose session persistence

Check Remember Me to stay logged in for 30 days. Leave unchecked for session-only authentication (expires when browser closes).

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

Step 2: Create a New Assessment

Access the dashboard

After login, you’ll see the dashboard with assessment statistics:

Total Assessments
Completed
Active (in progress)
Drafts

Start new assessment

Click the Start Assessment button in the top navigation bar.

Enter basic information

Assessment Name: "Q1 2026 - Acme Agro Ltd"
Company Name: "Acme Agro Ltd"
Company Type: "Agricultural SME" (optional)
Country: "Kenya" (default)

Select intake mode

Choose one of three data collection methods:

Upload
Guided Interview
Manual Entry

Best for: Businesses with existing business plans or pitch decksUpload 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

Step 3: Document Upload and Parsing

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

Upload business document

Drag and drop or click to select a PDF/DOCX file (max 10MB):

Supported formats:
- PDF (.pdf)
- Microsoft Word (.docx)

File size limit: 10 MB

Trigger document parsing

Click Parse Document to start AI extraction. This creates an asynchronous job.The system will:

Upload file to S3 with pre-signed URL
Create a PARSE_DOCUMENT job
Invoke Worker Lambda with Claude 3.5 Sonnet v2
Extract structured data across all 35 risk indicators

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)

API Request Pattern

// 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);
}

Automatic gap detection

Upon successful parsing, the system automatically chains a GAP_DETECTION job to identify missing data fields.

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

Step 4: Review and Fill Data Gaps

Navigate to Gap Detector

Click Review Gaps or navigate to the Gap Detector page from the assessment menu.

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

Example gap field:
{
  category: 'FINANCIAL',
  field: 'revenue_projection_year_1',
  label: 'Revenue Projection - Year 1',
  status: 'MISSING',
  extractedValue: null,
  correctedValue: null,
  isMandatory: true
}

Fill missing data

For each missing or partial field:

Review the extracted value (if any)
Enter the correct value or additional information
Click Save to update the field

The correctedValue field stores your input and takes precedence over extractedValue.

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)

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.

Step 5: Run Risk Analysis

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

View risk scorecard

Once analysis completes, navigate to the Risk Scorecard page to see:

{
  "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
  ]
}

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

Edit recommendations (optional)

Click Edit on any recommendation to:

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

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.

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.

Step 6: Generate PDF Report

Navigate to Report page

From the Risk Scorecard, click Generate Report or navigate to the Report page.

Preview report sections

Review the report structure:

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

Generate PDF

Click Download PDF to trigger the REPORT_GENERATION job.The system will:

Fetch all assessment data (gaps, scores, recommendations, comments)
Render HTML template with data
Convert HTML to PDF using headless Chrome (AWS Lambda)
Upload PDF to S3
Return pre-signed download URL (expires in 1 hour)

Download and review

Once generation completes (typically 20-30 seconds):

Click the download link
Save the PDF locally
Review for accuracy and completeness
Share with stakeholders as needed

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.

Step 7: Manage Assessments

Search and Filter

Use the dashboard search bar to find assessments:

// 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

DRAFT

Assessment created but not yet started. Intake mode selected, no data collected.

ANALYZING

Active jobs running (parsing, gap detection, or risk analysis in progress).

ACTION_REQUIRED

Gap detection complete, awaiting data input or corrections before analysis.

COMPLETE

Risk analysis finished, PDF report generated. Ready for review and export.

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)

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.

Next Steps

Architecture

Learn how the system works under the hood

API Reference

Explore all available API endpoints

User Management

Manage users and permissions (admin only)

Common Issues

Document parsing fails with 'Unsupported format' error

Cause: The uploaded file is not a valid PDF or DOCX, or is corrupted.Solution:

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

Risk analysis job stuck in PROCESSING for >5 minutes

Cause: Worker Lambda may have timed out or encountered a Bedrock throttling error.Solution:

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

Can't download PDF - 'Download link expired' error

Cause: Pre-signed S3 URLs expire after 1 hour for security.Solution:

Navigate back to the Report page for the assessment
Click Download PDF again to generate a fresh pre-signed URL
Download within 1 hour of generating the link

Session expired / logged out unexpectedly

Cause: JWT access token expired (default 60 minutes) and refresh token rotation failed.Solution:

Log in again with your email and password
Check Remember Me to extend session to 30 days
If using multiple browser tabs, close inactive tabs to prevent token conflicts

Get Started

Core Features

User Guides

Risk Model

Prerequisites

Account Access

Initial Password

Sample Data

Modern Browser

Step 2: Create a New Assessment

Step 3: Document Upload and Parsing

Step 4: Review and Fill Data Gaps

Step 5: Run Risk Analysis

Step 6: Generate PDF Report

Step 7: Manage Assessments

Search and Filter

Assessment Statuses

DRAFT

ANALYZING

ACTION_REQUIRED

COMPLETE

Edit or Delete Assessments

Next Steps

Architecture

API Reference

User Management

Common Issues

Build docs developers (and LLMs) love

Get Started

Core Features

User Guides

Risk Model

Documentation Index

​Prerequisites

Account Access

Initial Password

Sample Data

Modern Browser

​Step 1: First Login and Password Setup

​Step 2: Create a New Assessment

​Step 3: Document Upload and Parsing

​Step 4: Review and Fill Data Gaps

​Step 5: Run Risk Analysis

​Step 6: Generate PDF Report

​Step 7: Manage Assessments

​Search and Filter

​Assessment Statuses

DRAFT

ANALYZING

ACTION_REQUIRED

COMPLETE

​Edit or Delete Assessments

​Next Steps

Architecture

API Reference

User Management

​Common Issues

Build docs developers (and LLMs) love

Prerequisites

Step 1: First Login and Password Setup

Step 2: Create a New Assessment

Step 3: Document Upload and Parsing

Step 4: Review and Fill Data Gaps

Step 5: Run Risk Analysis

Step 6: Generate PDF Report

Step 7: Manage Assessments

Search and Filter

Assessment Statuses

Edit or Delete Assessments

Next Steps

Common Issues