Documentation Standards

# Project Name

Brief description of what this project does and who it serves.

![Build Status](link-to-ci-badge)
![Licence](link-to-licence-badge)

## Prerequisites

- Node.js 18.0 or higher
- PostgreSQL 14 or higher
- Access to organisation's npm registry

## Installation

Clone the repository and install dependencies:

git clone https://github.com/org/project.git
cd project
npm install

Copy the example environment file and configure:

cp .env.example .env

## Configuration

| Variable | Description | Default | Required |
|----------|-------------|---------|----------|
| `DATABASE_URL` | PostgreSQL connection string | None | Yes |
| `API_KEY` | External service API key | None | Yes |
| `LOG_LEVEL` | Logging verbosity | `info` | No |
| `PORT` | HTTP server port | `3000` | No |

## Usage

Start the development server:

npm run dev

Run database migrations:

npm run migrate

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup
and contribution guidelines.

## Licence

[MIT](LICENCE)

paths:
  /beneficiaries/{id}:
    get:
      summary: Retrieve a beneficiary record
      description: |
        Returns the complete beneficiary record including demographic
        data and programme enrolments. Requires read access to the
        beneficiary's programme.
      operationId: getBeneficiary
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Beneficiary unique identifier
      responses:
        '200':
          description: Beneficiary record retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Beneficiary'
              example:
                id: "550e8400-e29b-41d4-a716-446655440000"
                givenName: "Maria"
                familyName: "Santos"
                dateOfBirth: "1985-03-15"
                programmes:
                  - id: "prog-001"
                    name: "Cash Assistance"
                    enrolledAt: "2024-01-15T10:30:00Z"
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient permissions for this beneficiary
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Beneficiary not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

components:
  schemas:
    Beneficiary:
      type: object
      description: |
        A beneficiary represents an individual registered to receive
        assistance through one or more programmes.
      required:
        - id
        - givenName
        - familyName
      properties:
        id:
          type: string
          format: uuid
          description: System-generated unique identifier
          readOnly: true
        givenName:
          type: string
          minLength: 1
          maxLength: 100
          description: First or given name as provided by the beneficiary
        familyName:
          type: string
          minLength: 1
          maxLength: 100
          description: Family name or surname
        dateOfBirth:
          type: string
          format: date
          description: Birth date in ISO 8601 format (YYYY-MM-DD)
        programmes:
          type: array
          description: Programmes in which the beneficiary is enrolled
          items:
            $ref: '#/components/schemas/ProgrammeEnrolment'

# Use insertion sort for small arrays because the overhead of
# quicksort exceeds its benefits below 10 elements. Benchmarked
# on target hardware: insertion wins below n=12.
if len(items) < 10:
    return insertion_sort(items)

# USAID requires beneficiary exports to exclude PII fields when
# destination is outside the implementing country. See compliance
# requirement DR-2024-0042.
if export_destination != programme.country:
    exclude_fields.extend(PII_FIELDS)

# WARNING: This timeout must exceed the payment provider's retry
# window (currently 180 seconds) to prevent duplicate transactions.
# Do not reduce without coordinating with finance team.
TRANSACTION_TIMEOUT = 200

# TODO(jsmith 2024-11-15): Replace with batch query once
# PostgreSQL 16 upgrade completes. Current approach makes
# N+1 queries. Issue #1234.

def calculate_distribution_amount(
    beneficiary_id: str,
    programme_id: str,
    distribution_date: date
) -> Decimal:
    """Calculate the distribution amount for a beneficiary.

    Determines the amount based on household size, programme rules,
    and any adjustments from previous distributions. The calculation
    accounts for partial periods when beneficiaries enrolled mid-cycle.

    Args:
        beneficiary_id: UUID of the registered beneficiary.
        programme_id: UUID of the distribution programme.
        distribution_date: Date of the planned distribution.

    Returns:
        Distribution amount in programme currency. Returns Decimal('0')
        if the beneficiary is ineligible for this distribution.

    Raises:
        BeneficiaryNotFoundError: If beneficiary_id does not exist.
        ProgrammeNotFoundError: If programme_id does not exist.
        IneligibleError: If beneficiary is suspended or exited.

    Example:
        >>> amount = calculate_distribution_amount(
        ...     beneficiary_id="550e8400-e29b-41d4-a716-446655440000",
        ...     programme_id="prog-001",
        ...     distribution_date=date(2024, 12, 1)
        ... )
        >>> print(amount)
        Decimal('150.00')
    """

/
 * Validates beneficiary registration data against programme requirements.
 *
 * Checks required fields, data formats, and programme-specific eligibility
 * rules. Returns validation errors grouped by field for display in forms.
 *
 * @param data - Registration form data from client
 * @param programmeId - Target programme for enrolment
 * @returns Validation result with any errors grouped by field name
 *
 * @example
 * const result = validateRegistration(formData, 'prog-001');
 * if (!result.valid) {
 *   console.log(result.errors);
 *   // { dateOfBirth: ['Must be 18 or older'], phone: ['Invalid format'] }
 * }
 */
export function validateRegistration(
  data: RegistrationData,
  programmeId: string
): ValidationResult {

docs/adr/
├── 0001-use-postgresql-for-primary-database.md
├── 0002-adopt-event-sourcing-for-audit-log.md
├── 0003-select-keycloak-for-identity-provider.md
└── README.md

# NNNN. Title of Decision

Date: YYYY-MM-DD

## Status

Proposed | Accepted | Deprecated | Superseded by [NNNN](link)

## Context

Describe the situation that requires a decision. Include:
- The problem or need driving the decision
- Constraints (technical, organisational, regulatory)
- Forces in tension that make this decision non-trivial

## Decision

State the decision in active voice. "We will use X" not
"X was chosen". Be specific about scope and boundaries.

## Consequences

Describe the results of the decision:
- Positive outcomes and benefits
- Negative outcomes and risks accepted
- New constraints this creates
- Follow-up actions required

## Alternatives Considered

For each rejected alternative:
- Brief description
- Why it was not selected

# 0003. Select Keycloak for Identity Provider

Date: 2024-09-15

## Status

Accepted

## Context

The organisation requires centralised identity management to
support single sign-on across 12 applications, multi-factor
authentication, and federation with partner organisations.
Current state has each application managing its own user
database, creating credential sprawl and inconsistent
security controls.

Requirements:
- Support SAML 2.0 and OIDC protocols
- Self-hosted option for data sovereignty (field offices
  operate in countries with data localisation requirements)
- Integration with existing Active Directory for HQ staff
- Support for social login for external stakeholders
- Budget constraint: no per-user licensing fees

## Decision

We will deploy Keycloak as the organisation's identity
provider. Keycloak will run on the existing Kubernetes
cluster in the EU region with a replica deployment in
the East Africa regional data centre.

## Consequences

Positive:
- No licensing costs regardless of user count
- Full control over data location
- Active community and extensive documentation
- Native Kubernetes operator simplifies deployment

Negative:
- Requires internal expertise for maintenance
- Upgrades require manual intervention and testing
- No vendor support SLA (mitigated by commercial support
  option if needed)

New constraints:
- All new applications must integrate via OIDC
- Identity team must maintain Keycloak expertise
- Quarterly security patching required

## Alternatives Considered

Microsoft Entra ID: Strong Active Directory integration
but per-user pricing exceeds budget at scale. Data residency
options do not cover all required countries.

Okta: Excellent developer experience but licensing costs
prohibitive. Nonprofit discount still exceeded budget by 3x.

Authentik: Promising open-source alternative but smaller
community and less mature federation support. Considered too
risky for production identity infrastructure.

# Changelog

All notable changes to this project are documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/),
and this project adheres to [Semantic Versioning](https://semver.org/).

## [Unreleased]

### Added
- Beneficiary export to CSV format

### Changed
- Increased API rate limit from 100 to 500 requests per minute

## [2.1.0] - 2024-11-01

### Added
- Multi-factor authentication support for API access
- Bulk beneficiary import from Excel files
- Arabic language support in beneficiary portal

### Changed
- Upgraded PostgreSQL client to version 3.4.0
- Distribution calculations now round to 2 decimal places

### Fixed
- Corrected timezone handling in distribution scheduling
- Resolved memory leak in long-running export jobs

### Security
- Patched CVE-2024-1234 in authentication library

## [2.0.0] - 2024-08-15

### Changed
- BREAKING: Renamed `participant` to `beneficiary` in all APIs
- BREAKING: Date fields now use ISO 8601 format exclusively

### Removed
- BREAKING: Deprecated v1 API endpoints removed

### Migration
- Run `npm run migrate:v2` before deploying
- Update API clients to use new field names
- See [Migration Guide](docs/migration-v2.md) for details

## Health Checks

### Application Health

Endpoint: `GET /health`

Expected response:
```json
{
  "status": "healthy",
  "version": "2.1.0",
  "checks": {
    "database": "ok",
    "cache": "ok",
    "queue": "ok"
  }
}
```

Check frequency: Every 30 seconds

Alert threshold: 3 consecutive failures

### Database Connectivity

Command:
```bash
psql $DATABASE_URL -c "SELECT 1"
```

Expected: Returns `1` within 5 seconds

Alert threshold: Response time exceeds 5 seconds or connection fails

## Troubleshooting

### High Memory Usage

Symptom: Container memory exceeds 80% of limit; OOMKilled events
in logs.

Possible causes:
1. Memory leak in export processing (common)
2. Excessive concurrent connections (occasional)
3. Large payload processing (rare)

Diagnosis:

Check current memory consumers:
```bash
kubectl top pods -n production
kubectl exec -it $POD -- ps aux --sort=-%mem | head -20
```

Check for export jobs:
```bash
kubectl logs $POD | grep "export" | tail -50
```

Resolution:

For export-related memory growth:
```bash
# Cancel running exports
curl -X POST http://$POD:8080/admin/exports/cancel-all

# Restart pod to reclaim memory
kubectl rollout restart deployment/beneficiary-service -n production
```

For connection pool exhaustion:
```bash
# Check connection count
kubectl exec -it $POD -- psql $DATABASE_URL -c \
  "SELECT count(*) FROM pg_stat_activity WHERE application_name = 'beneficiary-service'"

# If above 80, restart to reset connections
kubectl rollout restart deployment/beneficiary-service -n production
```

Prevention: Configure export jobs to process in batches of 1,000
records. Set connection pool maximum to 20 (see config `DB_POOL_MAX`).

+--------------------------------------------------------------------+
|                       DOCUMENTATION PIPELINE                       |
+--------------------------------------------------------------------+
|                                                                    |
|   SOURCE                BUILD                    PUBLISH           |
|   +-------------+       +----------------+       +-------------+   |
|   |             |       |                |       |             |   |
|   | Markdown    +------>| Static Site    +------>| Web Server  |   |
|   | in Git      |       | Generator      |       | or CDN      |   |
|   |             |       |                |       |             |   |
|   +------+------+       +-------+--------+       +-------------+   |
|          |                      |                                  |
|          |              +-------+--------+                         |
|          |              |                |                         |
|          +------------->| Linting and    |                         |
|                         | Validation     |                         |
|                         |                |                         |
|                         +----------------+                         |
|                                                                    |
+--------------------------------------------------------------------+

<!-- Poor -->
![Diagram](architecture.png)

<!-- Better -->
![System architecture showing web server connecting to API
gateway, which routes requests to three microservices, each
with its own PostgreSQL database](architecture.png)

docs/
├── v1/                    # Legacy version (maintenance only)
│   ├── api.md
│   └── guide.md
├── v2/                    # Current stable version
│   ├── api.md
│   ├── guide.md
│   └── migration-from-v1.md
└── next/                  # Upcoming version (pre-release)
    ├── api.md
    └── guide.md

<Aside variant="caution" title="Deprecated version">
  This documentation covers API v1, which is deprecated and will
  be removed on 2025-06-01. See the [v2 documentation](/docs/v2/)
  for the current version and [migration guide](/docs/v2/migration-from-v1/)
  for upgrade instructions.
</Aside>