Examples & Patterns
This page provides reusable templates and examples for common documentation patterns.
Examples on this page are marked as either:
- ✅ Verified — Matches current UI/API code exactly (file path cited)
- 🧩 Template — Format example only; labels and values may differ by deployment
Request/Response blocks
When documenting API calls, use this format:
Pattern
### Endpoint name
**Request:**
```bash
curl -X POST https://{API_HOST}/v1/endpoint \
-H "Authorization: Bearer {TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"field": "value"
}'
```
**Response (200 OK):**
```json
{
"id": "abc123",
"status": "success",
"data": {
"result": "value"
}
}
```
**Error Response (400 Bad Request):**
```json
{
"error": "VALIDATION_ERROR",
"message": "Field 'name' is required"
}
```
Example 🧩 Template
Request:
curl -X GET https://{API_HOST}/v1/health \
-H "Accept: application/json"
Response (200 OK):
{
"status": "healthy",
"version": "0.1.0",
"timestamp": "2025-12-29T12:00:00Z"
}
Authentication pattern
When documenting authenticated endpoints:
Pattern
### Authentication
All API requests require a Bearer token in the Authorization header.
**Request:**
```bash
curl -X GET https://{API_HOST}/v1/protected-resource \
-H "Authorization: Bearer {TOKEN}" \
-H "Content-Type: application/json"
```
**Common errors:**
| Code | Error | Cause |
|------|-------|-------|
| 401 | UNAUTHORIZED | Missing or invalid token |
| 403 | FORBIDDEN | Token valid but lacks permission |
Example 🧩 Template
Authenticated request:
curl -X GET https://{API_HOST}/api/runs/{RUN_ID} \
-H "Authorization: Bearer {TOKEN}" \
-H "Content-Type: application/json"
401 Unauthorized response:
{
"error": "UNAUTHORIZED",
"message": "Authentication required"
}
403 Forbidden response:
{
"error": "CROSS_TENANT_ACCESS_DENIED",
"message": "Access to requested resource is forbidden"
}
Troubleshooting authentication errors:
| Symptom | Likely Cause | Solution |
|---|---|---|
| 401 on all requests | Token expired or malformed | Re-authenticate to obtain new token |
| 401 intermittent | Clock skew | Sync server time |
| 403 on specific resources | Wrong tenant context | Verify tenant ID in session matches resource |
Error response pattern
Standard error response structure:
Pattern
**Error Response:**
```json
{
"error": "ERROR_CODE",
"message": "Human-readable description",
"details": {
"field": "Additional context if available"
},
"requestId": "req-abc-123"
}
```
**Fields:**
| Field | Required | Description |
|-------|----------|-------------|
| `error` | Yes | Machine-readable error code (uppercase, underscores) |
| `message` | Yes | Human-readable explanation |
| `details` | No | Additional context object |
| `requestId` | TBD | Trace ID for debugging (see `server/routes.ts` error handlers) |
Example 🧩 Template
Validation error:
{
"error": "VALIDATION_ERROR",
"message": "Request body validation failed",
"details": {
"field": "tenantId",
"issue": "Required field missing"
}
}
Resource not found:
{
"error": "NOT_FOUND",
"message": "Run not found",
"details": {
"runId": "{RUN_ID}"
}
}
Cross-tenant access denied:
{
"error": "CROSS_TENANT_ACCESS_DENIED",
"message": "Access to requested resource is forbidden"
}
The platform may include a requestId or traceId in error responses for debugging. Check server/routes.ts error handler middleware for current implementation.
UI walkthrough format
When documenting UI interactions:
Pattern
## Task name
1. Navigate to **Section → Subsection**
2. Click **Button Name**
3. In the dialog, enter:
- **Field 1**: Description of what to enter
- **Field 2**: Description of what to enter
4. Click **Submit**
:::tip
Helpful tip about this workflow.
:::
**Expected result:** Description of what happens after completing the steps.
Example ✅ Verified
Upload a document
- Open the document upload dialog
- Click Upload New
(Verified:
client/src/components/modals/Modals.tsx:235) - In the upload dialog:
- File: Select your PDF, DOCX, or Excel file
- Category: Choose the evidence category (if applicable)
- Click Upload
File size limits are deployment-configured (default: 100 MB per file). If upload fails, see troubleshooting below.
(Verified: server/routes.ts:88 — multer fileSize: 100 * 1024 * 1024)
Expected result: The document appears in the list with an ingestion status indicator.
For Portal evidence uploads, status progresses through: UPLOADED → EXTRACTED → PARSED → INDEXED → READY (or FAILED).
(Verified: shared/schema.ts:160-167 — EvidenceStatus enum)
For Admin corpus ingestion, status progresses through: PENDING → FETCHING → PARSING → INDEXING → COMPLETED (or FAILED).
(Verified: shared/schema.ts:1092-1098 — CorpusIngestionStatus enum)
Troubleshooting format
Every guide should end with a troubleshooting section:
Pattern
## Troubleshooting
### Issue: Description of the problem
**Symptoms:**
- What the user observes
**Cause:**
Brief explanation of why this happens.
**Solution:**
1. Step to fix
2. Step to fix
---
### Issue: Another problem
**Symptoms:**
- What the user observes
**Cause:**
Brief explanation.
**Solution:**
Steps to resolve.
Example 🧩 Template
Troubleshooting
Issue: Upload fails with size error
Symptoms:
- Error message appears after selecting file
- Upload button is disabled or upload rejected
Cause:
The selected file exceeds the configured size limit.
Solution:
- Reduce file size by compressing images or removing unnecessary pages
- Split the document into multiple smaller files
- Re-attempt the upload
(Default limit: 100 MB per file — see server/routes.ts:88)
Issue: Document stuck in processing status
Symptoms:
- Document shows extended processing status
- No error message displayed
Cause:
Large or complex documents may take longer to process. In rare cases, processing may fail silently.
Solution:
- Wait for processing to complete (🧩 timing varies by document size and system load)
- If still processing after an extended period, contact your administrator to check system logs
- Try re-uploading the document
Issue: ZIP extraction fails
Symptoms:
- ZIP upload rejected with error message
- Child documents not created
Cause:
ZIP exceeds extraction limits.
Solution:
Check against deployment limits:
- Max depth: 5 levels (Verified:
shared/schema.ts:177) - Max files: 1000 (Verified:
shared/schema.ts:178) - Max total size: 500 MB (Verified:
shared/schema.ts:179)
Concept explanation format
When explaining concepts:
Pattern
# Concept Name
Brief one-sentence definition.
## Overview
2-3 paragraphs explaining the concept in more detail.
## How it works
Technical explanation with diagrams if helpful.
## Example
Concrete example showing the concept in action.
## Related concepts
- [Related Concept 1](./related-1)
- [Related Concept 2](./related-2)
Placeholder reference
Use these consistent placeholders throughout documentation:
| Placeholder | Description |
|---|---|
{API_HOST} | API server hostname |
{TOKEN} | Authentication bearer token |
{TENANT_ID} | Tenant identifier |
{DOCUMENT_ID} | Document identifier |
{RUN_ID} | Assessment run identifier |
{PACK_ID} | Pack identifier |