Skip to main content

Quickstart

Goal: Upload evidence documents and run an assessment to see compliance results.

By the end of this guide, you will have:

  • Uploaded at least one evidence document
  • Started an assessment run
  • Viewed the assessment results showing coverage status

Prerequisites​

Before you begin, ensure you have:

  • Access to the platform (URL provided by your administrator)
  • At least one evidence document ready
  • An understanding of what requirements you're trying to satisfy

Step 1: Access the portal​

  1. Open your browser and navigate to the platform URL
  2. Click Portal or navigate directly to the portal path
  3. You should see the main portal interface with a requirements panel on the left
Current repo route

In this repository, Portal is served at /cm.

What you should see: A layout with requirements list, document panel, and AI copilot.

Step 2: Upload evidence documents​

  1. Locate the Upload button in the toolbar
  2. Click it to open the file picker
  3. Select one or more evidence documents from your computer
  4. Wait for the upload indicator to show completion

Alternatively, drag and drop files directly onto the document panel.

Supported formats: PDF, DOCX, XLSX, CSV, PNG, JPG, ZIP, TXT

(Verified: shared/schema.ts:172 — ALLOWED_FILE_TYPES)

What you should see: Your uploaded documents appear in the documents list with a status indicator.

tip

Upload multiple related documents in a single ZIP file. The platform extracts and processes each file individually while maintaining parent-child relationships.

Step 3: Wait for document processing​

The platform processes each document through several stages:

StatusDescription
UPLOADEDFile received and stored
EXTRACTEDText extracted from file
PARSEDContent chunked for indexing
INDEXEDVector embeddings created
READYAvailable for assessment

(Verified: shared/schema.ts:160-167 — EvidenceStatus enum)

What you should see: Document status changes to READY with a green indicator.

note

Processing time varies by document size and complexity. UI labels may differ from internal status names.

Portal vs Admin statuses

These statuses apply to Portal evidence uploads (EvidenceStatus — shared/schema.ts:160-167). Admin corpus ingestion uses a different enum (CorpusIngestionStatus — shared/schema.ts:1092-1098) with values: PENDING → FETCHING → PARSING → INDEXING → COMPLETED.

Step 4: Start an assessment run​

  1. Ensure at least one document has reached READY status
  2. Click the Run Assessment button in the toolbar
  3. Confirm when prompted

What you should see: A progress indicator showing the run status.

Run status values: PENDING → IN_PROGRESS → COMPLETED (or FAILED)

(Verified: shared/schema.ts:294-298 — RunStatus enum)

note

Assessment runs evaluate all requirements in your pack against all READY documents.

Step 5: Review results​

Once the run completes:

  1. The requirements panel updates to show assessment status for each item
  2. Click on any requirement to see its assessment details
  3. Review the status, citations, and AI reasoning

Assessment status values: COMPLETE, PARTIAL, MISSING, or FAILED

(Verified: shared/schema.ts:318-322 — AssessmentStatus enum)

What you should see: Color-coded status indicators on each requirement.

What success looks like​

You have successfully completed this quickstart when:

  • At least one document shows READY status
  • An assessment run shows COMPLETED status
  • Requirements display color-coded assessment results
  • You can click a requirement and see citations to your uploaded evidence

Common failures and what to check​

1. Document stuck in UPLOADED status​

Symptom: Document shows UPLOADED but never progresses.

Check:

  • File is not corrupted or password-protected
  • File size is under the limit (default: 100 MB per file) (Verified: server/routes.ts:88 — multer fileSize config)
  • Reload the page to refresh status

Files to inspect: server/lib/pipeline.ts, server/routes.ts (POST /api/documents/upload)

2. Document shows FAILED status​

Symptom: Document status shows FAILED with an error message.

Check:

  • View the failure reason in the document details
  • Common causes: unsupported format, empty file, extraction error
  • Try re-uploading after fixing the issue

Files to inspect: server/lib/evidenceStorage.ts

3. Run stays in PENDING status​

Symptom: Assessment run shows PENDING but never starts.

Check:

  • At least one document is in READY status
  • No other run is currently IN_PROGRESS for this tenant
  • Check browser console for API errors

Files to inspect: server/lib/assessmentPipeline.ts

4. Run shows FAILED status​

Symptom: Assessment run failed to complete.

Check:

  • View the failure reason in run details
  • Common causes: LLM service unavailable, timeout, missing requirements
  • Contact your administrator if the issue persists

Files to inspect: server/lib/assessmentPipeline.ts, server/lib/llmProvider.ts

5. All requirements show MISSING​

Symptom: Every requirement shows MISSING status after run completes.

Check:

  • Uploaded documents are relevant to the requirements
  • Documents have extractable text (not scanned images without OCR)
  • Vector search is returning results

Files to inspect: server/lib/vectorStore.ts

6. Requirements panel is empty​

Symptom: No requirements appear in the left panel.

Check:

  • Criteria and requirements are loaded for your tenant
  • Contact your administrator to verify pack configuration
  • Check browser console for API errors

Files to inspect: server/routes.ts (GET /api/criteria), server/storage.ts

7. Upload button does nothing​

Symptom: Clicking Upload shows no file picker.

Check:

  • Browser popup blocker is not interfering
  • JavaScript is enabled
  • Try a different browser

Files to inspect: client/src/pages/ComplianceManager.tsx

8. Session expired or access denied​

Symptom: Page redirects to login or shows access denied.

Check:

  • Session may have timed out—refresh and re-authenticate
  • Verify you have the correct role for portal access
  • Contact your administrator if access was revoked

Files to inspect: server/routes.ts (session endpoints)

Next steps​

Now that you've completed your first assessment:

  1. Review detailed results to understand gaps and recommendations
  2. Learn about evidence mapping to improve coverage
  3. Explore the Admin workflow if you manage the platform
  4. Understand Runs and Snapshots to learn about deterministic replay