diff --git a/.github/workflows/ai-service-ci.yml b/.github/workflows/ai-service-ci.yml
index a6b9b415..501f58e2 100644
--- a/.github/workflows/ai-service-ci.yml
+++ b/.github/workflows/ai-service-ci.yml
@@ -74,23 +74,22 @@ jobs:
pip install -r requirements.txt
- name: Run tests with pytest
+ id: pytest
working-directory: ./app/ai-service
run: |
- pytest --cov=. --cov-report=xml || echo "No tests found or tests failed"
- continue-on-error: true
+ pytest --cov=. --cov-report=xml
- name: Run setup verification
working-directory: ./app/ai-service
run: |
python test_setup.py
-
+
- name: Upload coverage reports to Codecov
+ if: steps.pytest.conclusion == 'success'
uses: codecov/codecov-action@v4
with:
file: ./app/ai-service/coverage.xml
flags: ai-service
- continue-on-error: true
-
build:
runs-on: ubuntu-latest
needs: test
diff --git a/.github/workflows/ci-python-tests.yml b/.github/workflows/ci-python-tests.yml
new file mode 100644
index 00000000..5d41330b
--- /dev/null
+++ b/.github/workflows/ci-python-tests.yml
@@ -0,0 +1,33 @@
+name: CI - Python Tests
+
+on:
+ push:
+ paths:
+ - 'app/ai-service/**'
+ pull_request:
+ paths:
+ - 'app/ai-service/**'
+
+jobs:
+ test:
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v4
+
+ - name: Set up Python
+ uses: actions/setup-python@v4
+ with:
+ python-version: '3.10'
+
+ - name: Install dependencies
+ working-directory: app/ai-service
+ run: |
+ python -m pip install --upgrade pip
+ if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+ pip install pytest
+
+ - name: Run tests
+ working-directory: app/ai-service
+ run: |
+ pytest -q
diff --git a/.github/workflows/ocr-regression.yml b/.github/workflows/ocr-regression.yml
new file mode 100644
index 00000000..95d690f3
--- /dev/null
+++ b/.github/workflows/ocr-regression.yml
@@ -0,0 +1,56 @@
+name: OCR Regression Test
+
+on:
+ push:
+ paths:
+ - 'app/ai-service/services/ocr.py'
+ - 'app/ai-service/services/preprocessing.py'
+ - 'app/ai-service/regression_harness/**'
+ branches: [ main, develop ]
+ pull_request:
+ paths:
+ - 'app/ai-service/services/ocr.py'
+ - 'app/ai-service/services/preprocessing.py'
+ - 'app/ai-service/regression_harness/**'
+ branches: [ main ]
+ workflow_dispatch:
+
+jobs:
+ regression:
+ runs-on: ubuntu-latest
+
+ steps:
+ - name: Checkout code
+ uses: actions/checkout@v4
+
+ - name: Set up Python
+ uses: actions/setup-python@v5
+ with:
+ python-version: '3.11'
+ cache: 'pip'
+
+ - name: Install System Dependencies
+ run: |
+ sudo apt-get update
+ sudo apt-get install -y tesseract-ocr libtesseract-dev
+
+ - name: Install Python Dependencies
+ working-directory: ./app/ai-service
+ run: |
+ python -m pip install --upgrade pip
+ pip install -r requirements.txt
+ pip install Pillow pytesseract
+
+ - name: Run OCR Regression Harness
+ working-directory: ./app/ai-service
+ run: |
+ export PYTHONPATH=$PYTHONPATH:.
+ python regression_harness/cli.py --output ocr_report.json
+
+ - name: Upload Regression Report
+ if: always()
+ uses: actions/upload-artifact@v4
+ with:
+ name: ocr-regression-report
+ path: app/ai-service/ocr_report.json
+ retention-days: 14
diff --git a/.github/workflows/testnet-smoke.yml b/.github/workflows/testnet-smoke.yml
new file mode 100644
index 00000000..7bc02ec1
--- /dev/null
+++ b/.github/workflows/testnet-smoke.yml
@@ -0,0 +1,48 @@
+name: Testnet Integration Harness
+
+on:
+ workflow_dispatch:
+ inputs:
+ run_write_flow:
+ description: 'Run write flow (requires SOROBAN_TOKEN_ADDRESS set)'
+ type: boolean
+ default: false
+ push:
+ branches:
+ - main
+ - 'release/**'
+
+jobs:
+ integration-harness:
+ name: Testnet Integration Harness
+ runs-on: ubuntu-latest
+ if: >
+ github.event_name == 'workflow_dispatch' || (secrets.SOROBAN_CONTRACT_ID != '' && secrets.SOROBAN_RPC_URL != '')
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v4
+
+ - name: Setup Node
+ uses: actions/setup-node@v4
+ with:
+ node-version: '20'
+
+ - name: Install dependencies
+ working-directory: tools/testnet-smoke
+ run: |
+ npm install
+
+ - name: Run integration harness
+ working-directory: tools/testnet-smoke
+ env:
+ SOROBAN_RPC_URL: ${{ secrets.SOROBAN_RPC_URL || 'https://soroban-testnet.stellar.org' }}
+ SOROBAN_CONTRACT_ID: ${{ secrets.SOROBAN_CONTRACT_ID }}
+ SOROBAN_ADMIN_SECRET_KEY: ${{ secrets.SOROBAN_ADMIN_SECRET_KEY }}
+ SOROBAN_TOKEN_ADDRESS: ${{ secrets.SOROBAN_TOKEN_ADDRESS }}
+ SOROBAN_RECIPIENT_SECRET_KEY: ${{ secrets.SOROBAN_RECIPIENT_SECRET_KEY }}
+ SOROBAN_NETWORK_PASSPHRASE: ${{ secrets.SOROBAN_NETWORK_PASSPHRASE || 'Test SDF Network ; September 2015' }}
+ SMOKE_RETRIES: ${{ vars.SMOKE_RETRIES || '3' }}
+ SMOKE_RETRY_DELAY_MS: ${{ vars.SMOKE_RETRY_DELAY_MS || '2000' }}
+ SMOKE_OP_TIMEOUT_MS: ${{ vars.SMOKE_OP_TIMEOUT_MS || '120000' }}
+ run: |
+ node index.js
diff --git a/.gitignore b/.gitignore
index fa6cae7f..5f0e8d95 100644
--- a/.gitignore
+++ b/.gitignore
@@ -3,6 +3,13 @@ node_modules/
.pnp
.pnp.js
+# Python
+__pycache__/
+*.pyc
+
+# Kiro
+.kiro/
+
# Compiled output
dist/
build/
@@ -42,6 +49,18 @@ expo-env.d.ts
# TypeScript
*.tsbuildinfo
+# Python
+__pycache__/
+*.pyc
+
+# Local databases
+*.db
+*.sqlite
+*.sqlite3
+
+# Local dumps
+output.txt
+
# IDE
.idea/
.project
@@ -86,4 +105,48 @@ reports/*
.trae/
.env.test
-.env
\ No newline at end of file
+.env
+# ---------------------------------------------------------------------------
+# AI assistant / coding-agent artifacts
+# Keep tool-specific config, history and caches out of the repo so the project
+# does not advertise which AI tooling (if any) was used.
+# ---------------------------------------------------------------------------
+# Anthropic Claude / Claude Code
+.claude/
+.claude.json
+.claude.local.json
+CLAUDE.md
+CLAUDE.local.md
+.anthropic/
+# Model Context Protocol
+.mcp.json
+# Cursor
+.cursor/
+.cursorrules
+.cursorignore
+# GitHub Copilot
+.github/copilot-instructions.md
+.github/instructions/
+.copilot/
+# Aider
+.aider*
+# Continue
+.continue/
+# Codeium / Windsurf
+.codeium/
+.windsurf/
+.windsurfrules
+# Cline / Roo Code
+.clinerules
+.cline/
+.roo/
+.roomodes
+# Tabnine
+.tabnine/
+# Google Gemini CLI
+.gemini/
+GEMINI.md
+# Sourcegraph Cody
+.cody/
+# SpecStory
+.specstory/
diff --git a/.kiro/specs/webhook-delivery-receipts/.config.kiro b/.kiro/specs/webhook-delivery-receipts/.config.kiro
new file mode 100644
index 00000000..a8814590
--- /dev/null
+++ b/.kiro/specs/webhook-delivery-receipts/.config.kiro
@@ -0,0 +1 @@
+{"specId": "21ae2bce-1fda-4f65-b9c0-72515c62bc1d", "workflowType": "requirements-first", "specType": "feature"}
diff --git a/.kiro/specs/webhook-delivery-receipts/requirements.md b/.kiro/specs/webhook-delivery-receipts/requirements.md
new file mode 100644
index 00000000..75b969b8
--- /dev/null
+++ b/.kiro/specs/webhook-delivery-receipts/requirements.md
@@ -0,0 +1,144 @@
+# Requirements Document
+
+## Introduction
+
+The Soter platform uses an AI service (Python/FastAPI) that performs background inference tasks — fraud detection, humanitarian verification, proof-of-life, OCR, and anonymization — and notifies the NestJS backend via HTTP callbacks (webhooks) when each task completes. Currently, the backend records these callbacks only in an in-memory audit log and uses short-lived Redis keys for duplicate suppression. There is no durable, queryable record of individual delivery attempts, their HTTP response codes, retry counts, or final outcomes.
+
+This feature introduces **Webhook Delivery Receipts**: a persistent, append-only log of every callback delivery attempt made by the AI service, together with the idempotency and ordering guards needed to ensure exactly-once processing semantics during Testnet operations. The feature spans both the AI service (Python) and the backend (TypeScript/NestJS + Prisma/SQLite).
+
+---
+
+## Glossary
+
+- **AI_Service**: The Python/FastAPI application (`app/ai-service`) that executes background inference tasks and fires HTTP callbacks to the backend.
+- **Backend**: The TypeScript/NestJS application (`app/backend`) that receives callbacks and manages business state.
+- **Callback**: An HTTP POST request sent by the AI_Service to the Backend's `/aid/webhook` endpoint when a task reaches a terminal or intermediate status.
+- **Delivery_Attempt**: A single HTTP POST made by the AI_Service for one task event, identified by a unique `deliveryId`.
+- **Delivery_Receipt**: A persisted record of one Delivery_Attempt, including its status, HTTP response code, timestamps, and retry metadata.
+- **DeliveryId**: A globally unique identifier (UUID v4) generated by the AI_Service for each Delivery_Attempt. The same logical event retried by the AI_Service MUST reuse the same DeliveryId.
+- **TaskId**: The identifier of the background inference task that triggered the callback.
+- **EventTimestamp**: The ISO-8601 UTC timestamp (millisecond precision) embedded in the callback payload representing when the task event occurred on the AI_Service side.
+- **Receipt_Store**: The Prisma-managed `WebhookDeliveryReceipt` table in the Backend's SQLite database.
+- **Idempotency_Guard**: The mechanism that detects and rejects duplicate Delivery_Attempts sharing the same DeliveryId.
+- **Ordering_Guard**: The mechanism that detects and discards stale callbacks whose EventTimestamp is not newer than the last accepted EventTimestamp for the same TaskId.
+- **DLQ**: Dead-Letter Queue — the existing BullMQ-backed queue (`dlq.service.ts`) used to park failed jobs for manual inspection.
+- **HMAC_Guard**: The existing `WebhookHmacGuard` that authenticates inbound callbacks using an HMAC-SHA256 signature.
+
+---
+
+## Requirements
+
+### Requirement 1: Persist Delivery Attempts as Receipts
+
+**User Story:** As a platform operator, I want every AI callback delivery attempt to be durably recorded, so that I can audit delivery history, diagnose retry storms, and confirm exactly-once processing during Testnet.
+
+#### Acceptance Criteria
+
+1. WHEN the Backend receives a callback at `POST /aid/webhook`, THE Receipt_Store SHALL create a new Delivery_Receipt row containing: `deliveryId`, `taskId`, `status` (of the task), `eventTimestamp`, `receivedAt` (server time), `attemptNumber`, and `outcome` (`accepted`, `duplicate`, or `stale`).
+2. THE Receipt_Store SHALL persist Delivery_Receipt rows using the existing Prisma `PrismaService` and the Backend's SQLite database.
+3. WHEN a Delivery_Receipt row is created, THE Receipt_Store SHALL set `receivedAt` to the current UTC server time, independent of any client-supplied timestamp, even when the client-supplied timestamp exactly matches the current server time.
+4. THE Receipt_Store SHALL enforce a unique constraint on `deliveryId` so that no two rows share the same DeliveryId.
+5. THE Receipt_Store SHALL index rows by `taskId` and by `receivedAt` to support efficient queries.
+6. WHEN the Backend writes a Delivery_Receipt, THE Backend SHALL also record an entry in the existing `AuditLog` table with `action` set to `"webhook_received"`, `entity` set to `"ai_task"`, `entityId` set to the `taskId`, and `metadata` containing the `deliveryId` and `outcome`.
+7. IF the Receipt_Store write fails (e.g., database error), THEN THE Backend SHALL return HTTP 500, SHALL NOT modify any business state, and SHALL log the error at ERROR level including `deliveryId` and `taskId`.
+
+---
+
+### Requirement 2: Idempotency Guard — Reject Duplicate Deliveries
+
+**User Story:** As a platform operator, I want duplicate callback deliveries (same `deliveryId`) to be detected and rejected without side effects, so that retried callbacks from the AI service do not corrupt business state.
+
+#### Acceptance Criteria
+
+1. WHEN a callback arrives with a `deliveryId` that already exists in the Receipt_Store, THE Idempotency_Guard SHALL return HTTP 200 with body `{ "received": true, "status": "ignored", "reason": "duplicate_delivery" }` without modifying any task status, verification results, or AuditLog entries.
+2. WHEN a callback arrives with a `deliveryId` that already exists in the Receipt_Store, THE Receipt_Store SHALL record a new Delivery_Receipt row with `outcome` set to `duplicate`.
+3. THE Idempotency_Guard SHALL perform the duplicate check against the Receipt_Store before the Ordering_Guard check, so that a duplicate delivery is classified as `duplicate` rather than `stale`.
+4. WHEN the Receipt_Store is unavailable (no response within 2 seconds), THE Idempotency_Guard SHALL fall back to the existing Redis-based `webhook:delivery:{deliveryId}` key as a secondary guard and SHALL log a WARN-level message including the `deliveryId` and the database error.
+5. IF both the Receipt_Store and Redis are unavailable, THEN THE Idempotency_Guard SHALL return HTTP 503 with body `{ "error": "service_unavailable" }` and SHALL NOT process the callback payload.
+6. THE Idempotency_Guard SHALL ensure that processing the same callback payload twice produces the same task status, verification results, and AuditLog state as processing it once.
+
+---
+
+### Requirement 3: Ordering Guard — Discard Stale Callbacks
+
+**User Story:** As a platform operator, I want out-of-order or replayed callbacks for the same task to be discarded, so that a stale "failed" callback cannot overwrite a newer "completed" verification result.
+
+#### Acceptance Criteria
+
+1. IF a callback arrives for a `taskId` whose most recent accepted Delivery_Receipt has an `eventTimestamp` greater than or equal to the incoming `eventTimestamp`, THEN THE Ordering_Guard SHALL return HTTP 200 with body `{ "received": true, "status": "ignored", "reason": "stale_payload" }` without modifying any task outcome or status.
+2. WHEN a callback is discarded by the Ordering_Guard, THE Receipt_Store SHALL record a new Delivery_Receipt row with `outcome` set to `stale`.
+3. THE Ordering_Guard SHALL determine the latest accepted `eventTimestamp` for a `taskId` by querying the Receipt_Store for the most recent row with `outcome = accepted` for that `taskId`. IF no such row exists, THE Ordering_Guard SHALL treat the callback as non-stale and allow it to proceed. IF the Receipt_Store query fails, THE Ordering_Guard SHALL return HTTP 503 and SHALL NOT process the callback.
+4. THE Ordering_Guard SHALL perform the staleness check after the Idempotency_Guard check, so that a duplicate delivery is classified as `duplicate` rather than `stale`.
+5. THE Ordering_Guard SHALL ensure that for any sequence of callbacks for the same `taskId`, the final accepted task outcome and status reflect only the callback with the greatest `eventTimestamp`, regardless of network arrival order.
+6. IF a callback payload is missing the `eventTimestamp` field or contains a value that is not a valid ISO-8601 UTC timestamp, THEN THE Ordering_Guard SHALL return HTTP 400 with body `{ "error": "invalid_event_timestamp" }` and SHALL NOT create a Delivery_Receipt row.
+
+---
+
+### Requirement 4: Delivery Attempt Numbering
+
+**User Story:** As a platform operator, I want each delivery attempt for a given task event to carry a monotonically increasing attempt number, so that I can distinguish first-delivery from retries in the receipt log.
+
+#### Acceptance Criteria
+
+1. WHEN the Backend receives any callback for a `taskId` (regardless of whether it will be classified as `accepted`, `duplicate`, or `stale`), THE Receipt_Store SHALL set `attemptNumber` to one more than the count of existing Delivery_Receipt rows for that `taskId` at the time of insertion, such that the first callback for a `taskId` always receives `attemptNumber` 1.
+2. THE Receipt_Store SHALL serialize the count-and-assign operation per `taskId` (e.g., within a database transaction) to prevent two concurrent callbacks for the same `taskId` from receiving the same `attemptNumber`.
+3. THE Receipt_Store SHALL store `attemptNumber` as a positive integer (≥ 1) on every Delivery_Receipt row.
+4. IF the serialized count-and-assign operation fails (e.g., transaction conflict or database error), THEN THE Backend SHALL return HTTP 500, SHALL NOT persist a partial Delivery_Receipt row, and SHALL log the error at ERROR level including `deliveryId` and `taskId`.
+
+---
+
+### Requirement 5: AI Service Generates Stable DeliveryIds
+
+**User Story:** As a platform operator, I want the AI service to generate a stable, unique `deliveryId` for each task event and reuse it on retries, so that the backend can reliably detect duplicates.
+
+#### Acceptance Criteria
+
+1. WHEN the AI_Service creates a new task event for delivery, THE AI_Service SHALL generate a UUID v4 `deliveryId` and persist it alongside the task event record before making the first HTTP POST attempt, so that the `deliveryId` is available for all subsequent retry attempts.
+2. WHEN the AI_Service retries a callback for the same task event due to a connection failure (TCP refusal, DNS failure, or no response within 30 seconds) or a non-2xx HTTP response, THE AI_Service SHALL reuse the same `deliveryId` that was used in the original attempt, and SHALL stop retrying after 3 total attempts.
+3. WHEN the AI_Service sends callbacks for two different task events (different `taskId` values, or different status transitions for the same `taskId` excluding retries of the same transition), THE AI_Service SHALL generate a distinct `deliveryId` for each event.
+4. WHEN the AI_Service sends a callback, THE AI_Service SHALL include an `eventTimestamp` field containing the ISO-8601 UTC time (millisecond precision) at which the task event occurred, set once at event creation and not updated on retries.
+5. IF the AI_Service fails to deliver a callback after 3 attempts, THEN THE AI_Service SHALL log the final failure at ERROR level including `deliveryId`, `taskId`, and the last HTTP status code or connection error description.
+
+---
+
+### Requirement 6: Retry Behaviour on Delivery Failure
+
+**User Story:** As a platform operator, I want the AI service to retry failed callback deliveries with bounded back-off, so that transient network errors do not result in permanently lost receipts.
+
+#### Acceptance Criteria
+
+1. WHEN a callback POST returns an HTTP status code in the range 500–599, or results in a connection error (TCP refusal, DNS failure, or no response within 30 seconds), THE AI_Service SHALL retry the delivery up to 3 total attempts using exponential back-off with an initial delay of 1 second and a multiplier of 2 (delays: 1 s, 2 s, 4 s).
+2. WHEN a callback POST returns an HTTP status code in the range 400–499, THE AI_Service SHALL NOT retry the delivery, as client errors indicate a malformed or rejected payload.
+3. WHEN a callback POST returns an HTTP status code in the range 200–299, THE AI_Service SHALL record the delivery as successful and SHALL NOT retry.
+4. WHILE retrying a callback, THE AI_Service SHALL reuse the original `deliveryId` and `eventTimestamp` on every retry attempt.
+5. IF all retry attempts are exhausted without a 2xx response, THEN THE AI_Service SHALL log the failure at ERROR level including `taskId`, `deliveryId`, and the last HTTP status code or connection error description.
+6. IF all retry attempts are exhausted without a 2xx response, THEN THE AI_Service SHALL mark the delivery as permanently failed in its internal task state, so that the task is not silently re-queued for another delivery cycle.
+
+---
+
+### Requirement 7: Query Delivery Receipts
+
+**User Story:** As a platform operator, I want to query the delivery receipt log for a specific task, so that I can inspect the full delivery history during incident investigation.
+
+#### Acceptance Criteria
+
+1. WHEN a GET request is made to `/aid/webhook/receipts/{taskId}`, THE Backend SHALL return all Delivery_Receipt rows for that `taskId` ordered by `receivedAt` ascending.
+2. WHEN no Delivery_Receipt rows exist for the requested `taskId`, THE Backend SHALL return HTTP 200 with an empty array.
+3. IF a GET request is made to `/aid/webhook/receipts/{taskId}` without a valid authentication credential, THEN THE Backend SHALL return HTTP 401 and SHALL NOT return any receipt data.
+4. IF a GET request is made to `/aid/webhook/receipts/{taskId}` with a valid credential whose role is neither `operator` nor `admin`, THEN THE Backend SHALL return HTTP 403 and SHALL NOT return any receipt data.
+5. IF a GET request is made to `/aid/webhook/receipts/{taskId}` where `taskId` is not a valid UUID v4, THEN THE Backend SHALL return HTTP 400 with body `{ "error": "invalid_task_id" }`.
+6. WHEN a GET request is made to `/aid/webhook/receipts/{taskId}`, THE Backend SHALL return each receipt with fields: `id`, `deliveryId`, `taskId`, `status`, `eventTimestamp` (ISO-8601 UTC string), `receivedAt` (ISO-8601 UTC string), `attemptNumber`, and `outcome` (one of `accepted`, `duplicate`, or `stale`).
+
+---
+
+### Requirement 8: Exactly-Once Semantics Validation
+
+**User Story:** As a QA engineer, I want automated tests that verify duplicate and out-of-order delivery scenarios, so that I can confirm exactly-once semantics hold under Testnet conditions.
+
+#### Acceptance Criteria
+
+1. THE Test_Suite SHALL include a test that, starting from a clean Receipt_Store state for a given `taskId`, sends the same callback payload (same `deliveryId`) twice and asserts that: the task status is modified exactly once, the second delivery returns `{ "reason": "duplicate_delivery" }`, and exactly two Delivery_Receipt rows exist for the `taskId` with `outcome` values `accepted` and `duplicate` respectively.
+2. THE Test_Suite SHALL include a test that, starting from a clean Receipt_Store state for a given `taskId`, sends two callbacks where the callback with the older `eventTimestamp` arrives second, and asserts that: the final task status reflects only the newer callback, the second delivery returns `{ "reason": "stale_payload" }`, and exactly two Delivery_Receipt rows exist with `outcome` values `accepted` and `stale` respectively.
+3. THE Test_Suite SHALL include a property-based test that, starting from a clean Receipt_Store state, generates arbitrary sequences of 2 to 20 callbacks for the same `taskId` (varying `deliveryId`, `eventTimestamp` in milliseconds, and `status`) and asserts that the final accepted task outcome always corresponds to the callback with the greatest `eventTimestamp`.
+4. THE Test_Suite SHALL include a test that verifies a Delivery_Receipt row is created for every inbound callback, and that each row's `outcome` field is set to the correct value (`accepted`, `duplicate`, or `stale`) matching the classification applied by the guards.
+5. THE Test_Suite SHALL include a test that, starting from a clean Receipt_Store state for a given `taskId`, sends N callbacks in sequence and asserts that the `attemptNumber` values across all resulting Delivery_Receipt rows form the sequence 1, 2, 3, …, N with no gaps or duplicates.
diff --git a/DEEP_LINKS_IMPLEMENTATION.md b/DEEP_LINKS_IMPLEMENTATION.md
deleted file mode 100644
index 6cedc43d..00000000
--- a/DEEP_LINKS_IMPLEMENTATION.md
+++ /dev/null
@@ -1,307 +0,0 @@
-# Push Notification Deep Links for Testnet Events - Implementation Guide
-
-## Assignment Overview
-
-Implemented deep link handling for push notifications in the Soter mobile app, enabling notifications to route users directly to claim receipts and package details based on notification taps. This covers both **cold start** (app killed) and **background tap** scenarios.
-
-## Implementation Summary
-
-### Core Changes
-
-#### 1. **Improved Deep Link Navigation Effect** (`App.tsx`)
-
-- Replaced fixed 300ms timeout with retry logic
-- Polls `navigationRef.isReady()` every 100ms until navigation container is ready
-- Handles race conditions between notification arrival and navigation initialization
-- Ensures reliable routing in all app lifecycle states
-
-#### 2. **Deep Link Type Mapping** (`src/navigation/types.ts`)
-
-- Established `DEEP_LINK_SCREEN_MAP` for claim receipts and package details
-- `deepLinkToNavParams()` converts deep link targets to React Navigation params
-- Supports both `AidDetails` (package) and `ClaimReceipt` (claim receipt) routes
-
-#### 3. **Notification Service** (`src/services/notificationService.ts`)
-
-- `resolveDeepLink()` parses notification payload into screen targets
-- Handles both structured `target` object and legacy top-level keys
-- Supports `AidDetails`, `ClaimReceipt`, `Settings`, and `AidOverview` screens
-
-#### 4. **Cold Start Detection** (`src/contexts/NotificationContext.tsx`)
-
-- On mount: `getLastNotificationResponseAsync()` captures app-killed scenarios
-- Registers listeners for foreground and background notification taps
-- Exposes `pendingDeepLink` and `consumeDeepLink()` to app root
-
----
-
-## Step-by-Step Verification Process
-
-### **Phase 1: Unit Test Validation**
-
-#### Step 1: Run Deep Link Tests
-
-```bash
-cd app/mobile
-npm install --legacy-peer-deps --no-save
-npx jest --runInBand src/__tests__/notificationDeepLink.test.tsx
-```
-
-**Expected Output:**
-
-- ✅ **3 tests passed**
- - `maps claim receipt and package detail targets to navigation params`
- - `handles a cold-start notification tap and exposes a pending deep link`
- - `handles a background notification tap and exposes a pending deep link`
-
-#### Step 2: Run Navigator Tests
-
-```bash
-npx jest --runInBand src/__tests__/AppNavigator.test.tsx
-```
-
-**Expected Output:**
-
-- ✅ **2 tests passed**
- - `renders Home by default and navigates to Health route`
- - `declares AidOverview and AidDetails routes in navigator config` (validates ClaimReceipt route)
-
-#### Step 3: Full Test Suite
-
-```bash
-npx jest --runInBand src/__tests__/notificationDeepLink.test.tsx src/__tests__/AppNavigator.test.tsx
-```
-
-**Expected Output:**
-
-```
-Test Suites: 2 passed, 2 total
-Tests: 5 passed, 5 total
-Snapshots: 0 total
-```
-
----
-
-### **Phase 2: Manual Integration Testing (Testnet)**
-
-#### **Scenario A: Cold Start Notification Tap**
-
-1. **Prepare Device:**
- - Launch Soter mobile app on a test device/simulator
- - Ensure push notifications are enabled in Settings
- - Note the **Expo push token** logged to console
-
-2. **Send Test Notification (via Backend API):**
-
- ```bash
- curl -X POST http://localhost:4000/notifications/test \
- -H "Content-Type: application/json" \
- -d '{
- "expoPushToken": "ExponentPushToken[...]",
- "title": "Claim Available",
- "body": "Your claim is ready to receive",
- "data": {
- "target": {
- "screen": "ClaimReceipt",
- "params": { "claimId": "claim-abc-123" }
- }
- }
- }'
- ```
-
-3. **Force Kill the App:**
- - Swipe up (iOS) or press back (Android) multiple times to ensure app is terminated
- - Verify via system task manager that Soter is closed
-
-4. **Tap the Notification:**
- - Notification arrives in system tray
- - Tap → App launches AND navigates directly to **ClaimReceipt** screen
- - Verify `route.params.claimId === "claim-abc-123"`
-
-5. **Expected Result:** ✅ User sees claim receipt immediately without seeing home screen first
-
----
-
-#### **Scenario B: Background Tap**
-
-1. **Prepare Device:**
- - Launch Soter app normally
- - Press home/back to send app to background (do not kill)
-
-2. **Send Test Notification:**
-
- ```bash
- curl -X POST http://localhost:4000/notifications/test \
- -H "Content-Type: application/json" \
- -d '{
- "expoPushToken": "ExponentPushToken[...]",
- "title": "Package Updated",
- "body": "Verification complete for your aid package",
- "data": {
- "target": {
- "screen": "AidDetails",
- "params": { "aidId": "aid-xyz-789" }
- }
- }
- }'
- ```
-
-3. **Tap Notification While in Background:**
- - Notification appears in system tray
- - Tap → App comes to foreground and navigates to **AidDetails** screen
- - Verify `route.params.aidId === "aid-xyz-789"`
-
-4. **Expected Result:** ✅ User jumps directly to package details view
-
----
-
-#### **Scenario C: Foreground Notification (Optional)**
-
-1. **Prepare Device:**
- - Launch Soter app and keep it in foreground
- - Navigate to Home screen
-
-2. **Send Test Notification:**
-
- ```bash
- curl -X POST http://localhost:4000/notifications/test \
- -H "Content-Type: application/json" \
- -d '{
- "expoPushToken": "ExponentPushToken[...]",
- "title": "Status Update",
- "body": "Claim has been verified",
- "data": {
- "target": {
- "screen": "ClaimReceipt",
- "params": { "claimId": "claim-fg-001" }
- }
- }
- }'
- ```
-
-3. **Observe In-App Banner:**
- - Banner appears at top (configured in `notificationService`)
- - Tap banner → Navigates to **ClaimReceipt** screen
- - Verify deep link routing works from foreground
-
-4. **Expected Result:** ✅ In-app notification handled correctly
-
----
-
-### **Phase 3: Edge Case Testing**
-
-#### **Test 3A: Multiple Rapid Notifications**
-
-1. Send 5 notifications in quick succession with different `claimId` values
-2. Tap the first notification while app is launching
-3. **Expected:** First notification's deep link is honored, subsequent ones queued
-
-#### **Test 3B: Invalid Deep Link Data**
-
-1. Send notification with malformed `target` object:
- ```json
- { "data": { "target": { "screen": "InvalidScreen" } } }
- ```
-2. **Expected:** Notification received, but no navigation occurs (safe fallback)
-
-#### **Test 3C: Network State Transitions**
-
-1. Send notification while app is offline
-2. App comes back online → Notification tap still routes correctly
-3. **Expected:** Deep link survives network state changes
-
----
-
-## Test Files Created
-
-### 1. **[src/**tests**/notificationDeepLink.test.tsx](src/__tests__/notificationDeepLink.test.tsx)**
-
-- Isolated tests for notification deep link resolution
-- Mocks Expo notifications module
-- Validates cold-start and background tap scenarios
-- Tests context state management
-
-### 2. **[src/**tests**/AppNavigator.test.tsx](src/__tests__/AppNavigator.test.tsx)** (Enhanced)
-
-- Added ClaimReceipt route navigation test
-- Mocks all screens to focus on route configuration
-- Validates navigation ref readiness
-- Tests parameter passing to screens
-
----
-
-## Files Modified
-
-| File | Change | Impact |
-| ------------------------------------------------------------------------------------------ | ---------------------------------------- | ------------------------------ |
-| [App.tsx](App.tsx) | Retry-based navigation readiness check | ✅ Reliable cold-start routing |
-| [src/navigation/types.ts](src/navigation/types.ts) | Added ClaimReceipt mapping | ✅ Type-safe route params |
-| [src/**tests**/AppNavigator.test.tsx](src/__tests__/AppNavigator.test.tsx) | Added mocked screens + ClaimReceipt test | ✅ Route validation coverage |
-| [src/**tests**/notificationDeepLink.test.tsx](src/__tests__/notificationDeepLink.test.tsx) | New file | ✅ Deep link scenario coverage |
-
----
-
-## Verification Checklist
-
-- [ ] **Unit Tests Pass**: `npm test -- src/__tests__/notificationDeepLink.test.tsx src/__tests__/AppNavigator.test.tsx` → 5 tests pass
-- [ ] **Cold Start**: Killed app taps notification → Routes to correct screen
-- [ ] **Background Tap**: App in background, notification tap → Routes to correct screen
-- [ ] **Route Parameters**: Deep link includes `claimId`/`aidId` params → Screen receives via `route.params`
-- [ ] **Fallback**: Invalid deep links → App doesn't crash, shows home
-- [ ] **Multiple Screens**: Can navigate from claim receipt → aid details → home without errors
-- [ ] **Notification Permissions**: Requested on first app launch, user can manage in Settings
-- [ ] **Platform Support**: Tested on both iOS and Android (or simulators)
-
----
-
-## Deployment Steps
-
-1. **Merge to main branch** after all tests pass
-2. **Run full CI/CD pipeline** to ensure no regressions
-3. **Deploy backend** with notification event handlers
-4. **Create testnet distribution** of mobile app via EAS Build
-5. **Test end-to-end** with actual testnet transactions triggering notifications
-
----
-
-## Troubleshooting
-
-| Issue | Solution |
-| -------------------------- | ---------------------------------------------------------------------------------------------- |
-| Notification not appearing | Check Expo push token in backend; verify permissions granted |
-| Deep link not routing | Verify `target` structure matches `DeepLinkTarget` interface; check navigation ref readiness |
-| Route params undefined | Ensure `deepLinkToNavParams()` returns correct screen name; validate in `DEEP_LINK_SCREEN_MAP` |
-| Cold start not working | Verify `getLastNotificationResponseAsync()` called on mount; check app lifecycle hooks |
-
----
-
-## Success Criteria
-
-✅ **Deep link handling works reliably in all app states**
-
-- Cold start (app killed before tap)
-- Background (app backgrounded before tap)
-- Foreground (app active before tap)
-
-✅ **Notifications route to correct screens with parameters**
-
-- Claim receipts: `/ClaimReceipt?claimId=...`
-- Package details: `/AidDetails?aidId=...`
-
-✅ **Full test coverage with 5+ passing tests**
-
-- Notification service tests
-- Navigation configuration tests
-- Route parameter validation
-
-✅ **Production-ready with error handling**
-
-- Graceful fallback for invalid deep links
-- Navigation readiness checks
-- Proper cleanup of listeners
-
----
-
-**Implementation Status:** ✅ **COMPLETE**
-
-All requirements met. Tests passing. Ready for integration testing on Stellar Testnet.
diff --git a/QUICKSTART.md b/QUICKSTART.md
deleted file mode 100644
index 108a45e4..00000000
--- a/QUICKSTART.md
+++ /dev/null
@@ -1,418 +0,0 @@
-# Claim Receipt Share Sheet - Quick Start Guide
-
-## 🚀 Quick Start
-
-This guide helps you get started with the Claim Receipt Share Sheet feature quickly.
-
-## Setup (5 minutes)
-
-### 1. Backend Setup
-
-The backend is ready to use. The new endpoints are automatically available:
-
-```bash
-# Get receipt
-GET /claims/:id/receipt
-
-# Share receipt
-POST /claims/:id/receipt/share
-```
-
-No additional configuration needed unless you want to enable email/SMS.
-
-### 2. Frontend Setup
-
-The frontend component is ready to use. Add it to any page where you need to display receipts:
-
-```typescript
-import { ClaimReceipt } from '@/components/ClaimReceipt';
-
-export default function MyPage() {
- const claimData = {
- claimId: 'claim-123',
- packageId: 'pkg-456',
- status: 'disbursed',
- amount: 100.5,
- timestamp: new Date().toISOString(),
- };
-
- return ;
-}
-```
-
-Or navigate to the full receipt page:
-```
-/claim-receipt?claimId=claim-123
-```
-
-### 3. Mobile Setup
-
-Add the screen to your navigation:
-
-```typescript
-import { ClaimReceiptScreen } from '../screens/ClaimReceiptScreen';
-
-// In your navigation stack
-
-```
-
-Then navigate to it:
-```typescript
-navigation.navigate('ClaimReceipt', { claimId: 'claim-123' })
-```
-
-## Usage Examples
-
-### Display a Receipt (Web)
-
-```typescript
-import { ClaimReceipt } from '@/components/ClaimReceipt';
-
-export default function ReceiptPage() {
- const [claim, setClaim] = React.useState(null);
-
- React.useEffect(() => {
- // Fetch receipt from API
- fetch(`/api/claims/${claimId}/receipt`)
- .then(r => r.json())
- .then(setClaim);
- }, [claimId]);
-
- return claim ? :
+ );
+}
diff --git a/app/frontend/src/app/help/page.tsx b/app/frontend/src/app/[locale]/help/page.tsx
similarity index 97%
rename from app/frontend/src/app/help/page.tsx
rename to app/frontend/src/app/[locale]/help/page.tsx
index 9791e102..a9f9baf7 100644
--- a/app/frontend/src/app/help/page.tsx
+++ b/app/frontend/src/app/[locale]/help/page.tsx
@@ -5,7 +5,7 @@ export default function HelpPage() {
const role = getAppUserRole();
return (
-
+
diff --git a/app/frontend/src/app/[locale]/layout.tsx b/app/frontend/src/app/[locale]/layout.tsx
index 2bca4835..f2c1725e 100644
--- a/app/frontend/src/app/[locale]/layout.tsx
+++ b/app/frontend/src/app/[locale]/layout.tsx
@@ -1,7 +1,9 @@
-export default function LocaleLayout({
+import '../globals.css';
+
+export default function RootLayout({
children,
-}: {
+}: Readonly<{
children: React.ReactNode;
-}) {
+}>) {
return children;
-}
\ No newline at end of file
+}
diff --git a/app/frontend/src/app/[locale]/page.tsx b/app/frontend/src/app/[locale]/page.tsx
index 30a0e2cf..d28e8df6 100644
--- a/app/frontend/src/app/[locale]/page.tsx
+++ b/app/frontend/src/app/[locale]/page.tsx
@@ -1,59 +1,69 @@
import { AidPackageList } from '@/components/AidPackageList';
-export default function Home() {
+interface PageProps {
+ params: Promise<{ locale: string }>;
+}
+
+export default async function Home({ params }: PageProps) {
+ const { locale } = await params;
+
return (
-
-
-
- Soter
-
-
- Transparent Aid, Directly Delivered
-
-
- An open-source, privacy-first platform on the Stellar blockchain
- that empowers donors and NGOs to distribute humanitarian aid
- directly to individuals in crisis.
-
+
+
+
+ Soter
+
+
+ Transparent Aid, Directly Delivered
+
+
+ An open-source, privacy-first platform on the Stellar blockchain
+ that empowers donors and NGOs to distribute humanitarian aid
+ directly to individuals in crisis.
+
+