Guide Summaries - striae-org/striae GitHub Wiki

Guide Summaries

This page provides a quick TL;DR for major Striae wiki guides so contributors can orient quickly before diving into full documentation.

Public API surface is same-origin Pages Functions under /api/*, which proxy to domain workers.
Auth is two-hop: Firebase bearer from client, then internal service auth from Pages to worker.
Worker contracts are documented by domain: user, data, image, audit, and PDF.
Annotation/PDF payloads support split left/right item fields and side-specific notes, with legacy class-era fields retained for compatibility.
Most worker responses are JSON error shapes; user worker remains the main plain-text outlier.

Striae is edge-first with strict boundaries: app UI, Pages gateway, domain workers, and storage-by-concern.
Browser clients should call Pages APIs, not worker domains directly.
Worker internals are modularized (handlers, storage, registry, etc.) while preserving stable public endpoints.
Core architectural priorities: typed contracts, service isolation, forensic integrity, and fail-safe observability.

Audit logging is append-oriented and immutable, stored per-user per-day in encrypted audit files.
AuditService is best-effort: audit failures generally should not block primary workflows.
Badge/ID propagation is built into audit details for consistent filtering and attribution.
Case audit PDF export is case-scoped and uses full case history; bundled archived data is exported in full.

Confirmation workflows are signature-based (not hash-only) and fail closed when signature requirements are not met.
Import enforces strong validation: designated reviewer checks, owner checks, signature checks, integrity checks, and anti-self-confirmation rules.
Confirmation status is cached in summary metadata for performance, not recomputed from all annotations each time.
Audit events are recorded across export/import/confirmation phases for chain-of-custody traceability.

Frontend components are organized by feature domain under app/components/.
App patterns favor modular composition, typed props, and focused subcomponents/hooks.
Canvas and annotation flows are central to casework, with read-only and confirmation-aware behavior.
Notes and item-detail workflows use split left/right item data paths and item-centric terminology.
Archive import UX relies on centralized import message constants to keep alert text consistent across preview and execution surfaces.
Shared form, toast, auth, audit-viewer, and toolbar primitives support consistent UX and state handling.

Live storage encryption uses hybrid RSA-OAEP-AES-256-GCM envelopes across Data, Audit, Image, and User workers.
Design is fail-closed: missing/invalid key material or envelope mismatch blocks decryption.
Key rotation is supported via key registries (*_KEYS_JSON + active key id) with fallback resolution.
Encryption scope is separated by purpose: DATA_AT_REST, USER_KV, and EXPORT.

.env is deployment input; scripts sync generated config and push worker/pages secrets.
deploy-config is the central orchestration script for validation, placeholder replacement, and key generation.
Worker domain values are required for proxy routing but are not written as runtime worker secrets.
Firebase Admin credentials must be present in app/config/admin-service.json before setup flows.
Email allowlists for registration and PrimerShear PDF routing are managed via deploy-members and deploy-primershear workflows, which sync .env plus Pages secrets.

Error handling is layered: route boundary, auth error mapping, utility-level validation, and worker status handling.
API clients throw structured errors on auth/request failures; callers should use try/catch.
Permission checks return result objects and fail closed on internal issues.
Audit logging failures are typically non-blocking by design to protect primary user workflows.

Export package encryption is mandatory for case exports, confirmation exports, and archive packages.
Packages require ENCRYPTION_MANIFEST.json; import flows decrypt first, then run normal hash/signature validation.
Public encryption keys are client-visible by design; private decryption keys stay in Data Worker secrets.
Data Worker decrypt endpoint is the trusted server-side boundary for import-time plaintext recovery.

Integrity trust is anchored in Data Worker-issued signatures using RSASSA-PSS-SHA-256.
Manifest and confirmation payloads use deterministic canonicalization before signing and verification.
Import key precedence is ZIP-bundled PEM first, then configured key lookup by key id.
Signature checks are fail-closed and enforced before allowing import workflows to continue.

PDF generation is modular: worker dispatches by report format and delegates rendering to format modules.
Pages proxy resolves report format server-side from verified identity (for public browser requests).
Report assets are embedded in-worker as generated base64 constants for deterministic rendering.
Audit trail PDF mode is a dedicated path that supports chunking and raw JSON appendix output.

Security is layered across identity, authorization, gateway, worker auth, integrity, and audit boundaries.
Case permissions must run through centralized utilities (canCreateCase, canAccessCase, canModifyCase).
Worker/service trust relies on Pages verification plus per-worker secrets/tokens.
Encryption-at-rest, signed import/export validation, and MFA flows provide defense in depth.

Utilities are domain-organized under app/utils/ and should be accessed via barrel exports.
Centralized API clients manage Firebase token transport and same-origin /api/* communication.
Permission and data-operation utilities are the required path for case/file operations.
Notes panel open/close and read-only mode decisions are centralized in getNotesViewPermission; use getNotesButtonTooltip for consistent tooltip text across navbar and sidebar.
File modal filtering/sorting is item-type oriented (itemType) with runtime migration from legacy class-type preferences.
Forensics helpers centralize hashing/signature/export validation logic to avoid drift across workflows.