## ADDED Requirements ### Requirement: REST API endpoints The system SHALL expose REST API endpoints for all operations currently served by WebForms page methods and Json-*.aspx pages. Endpoints return JSON and follow consistent conventions: resource-oriented URLs, standard HTTP methods, and consistent error response format. #### Scenario: List financial accounts - **WHEN** an authenticated client sends `GET /api/organizations/{orgId}/accounts` - **THEN** the API returns the chart of accounts for that organization as JSON #### Scenario: Create expense claim - **WHEN** an authenticated client sends `POST /api/organizations/{orgId}/expense-claims` with claim data - **THEN** the API creates the claim and returns the new resource with its ID #### Scenario: Unauthenticated request - **WHEN** an unauthenticated client calls any API endpoint - **THEN** the API returns 401 Unauthorized ### Requirement: WebSocket for real-time updates The system SHALL provide a WebSocket endpoint for real-time notifications to connected clients. Authentication on WebSocket upgrade uses the same session cookie as REST API requests. Events include: new blockchain deposits detected, task list changes, backend worker status updates. #### Scenario: WebSocket connection - **WHEN** an authenticated client connects to the WebSocket endpoint (session cookie sent on upgrade) - **THEN** the client receives real-time events scoped to their active organization #### Scenario: Unauthenticated WebSocket rejected - **WHEN** a client without a valid session cookie attempts a WebSocket upgrade - **THEN** the server rejects the upgrade with 401 #### Scenario: Blockchain deposit notification - **WHEN** the backend worker detects a new deposit to a hot wallet address - **THEN** connected clients for that organization receive a notification via WebSocket ### Requirement: Consistent error responses All API errors SHALL return a JSON body with `error` (machine-readable code), `message` (human-readable description), and optional `details` (field-level validation errors). HTTP status codes follow REST conventions (400 for validation, 401 for auth, 403 for permission, 404 for not found, 500 for server errors). #### Scenario: Validation error - **WHEN** a client submits an expense claim missing a required field - **THEN** the API returns 400 with an error body listing the missing fields #### Scenario: Permission denied - **WHEN** a user without the `CanAttestExpenses` permission attempts to attest a claim - **THEN** the API returns 403 with an error body indicating the missing permission ### Requirement: Organization-scoped routing All resource endpoints SHALL be scoped under `/api/organizations/{orgId}/` to enforce multi-tenant data isolation at the routing level. The API layer verifies the authenticated user has access to the specified organization before processing. #### Scenario: Cross-org access denied - **WHEN** a user belonging only to Organization A requests data for Organization B - **THEN** the API returns 403 ### Requirement: Static file serving The API server SHALL serve the React SPA's static assets (HTML, JS, CSS) from a configured directory. All non-API routes SHALL fall through to the SPA's `index.html` for client-side routing. #### Scenario: SPA route fallthrough - **WHEN** a browser navigates to `/ledgers/balance-sheet` - **THEN** the server serves `index.html` and the React router handles the route