SOFRS-EA-Frontend

Report Traceability Matrix

This matrix maps report claims to implementation evidence in the repository.

Note:

  1. Evidence links use direct file+line anchors for report citation.
  2. Revalidate line anchors after major refactors.

Core Claims

Claim ID Report Claim Primary Evidence Supporting Evidence Validation Method
C-01 The backend exposes separate employee, visitor, and image route groups. main include_router image main include_router employee Confirm route mounting and endpoint list parity.
C-02 Protected routes require X-API-Key authentication. get_api_key dependency employee router dependency wiring Verify APIRouter dependencies and auth failure status codes.
C-03 Employee and Visitor IDs are generated with distinct prefixes. employee id default factory visitor id default factory Check generated ID prefix usage in model defaults.
C-04 Enrollment supports multi-image upload linked to owner ID. upload_multiple_images endpoint desktop register upload call Verify multipart fields owner_id + files[] and upload response shape.
C-05 Uploaded images are preprocessed and stored with owner-prefixed filenames. upload_image persistence path prepare_image_bytes processor Trace upload_image -> prepare_image_bytes -> _build_filename.
C-06 Recognition uses a multi-stage pipeline (preprocess, search, analyze, verify, decide). search_image orchestration search_identity stage function Follow search endpoint execution path end-to-end.
C-07 Candidate search uses DeepFace with owner-grouping and ambiguity checks. _select_best_owner_match _is_ambiguous_owner_match Validate owner grouping and ambiguity branch handling.
C-08 Verification uses pairwise embedding comparisons and minimum match counts. verify_identity function match_count threshold decision Confirm match_count/min_matches_required decision logic.
C-09 Soft attributes are gated by face confidence and eye visibility checks. _is_soft_attribute_ready gate analyze_identity uses gate Validate readiness-gate behavior before soft attribute analysis.
C-10 Image search returns multiple decision branches to frontend. no-match branch ambiguous branch Confirm no-match, ambiguous, unconfirmed, confirmed responses.
C-11 Desktop maps backend response to a normalized verification model. mapResponse normalizer message-based recognition fallback Verify mapResponse and recognized inference behavior.
C-12 Mobile onboarding persists record ID and uploads five-pose captures. setRecordId on create mobile uploadImages call Confirm setRecordId and uploadImages flow.
C-13 Mobile global state is context-based, not redux-based. UserProvider definition UserProvider app wrapper Validate provider composition and context fields.
C-14 Backend includes health and warmup visibility for operations. health_check endpoint health payload includes deepface_warmup Confirm /health payload includes deepface_warmup details.
C-15 Repeated invalid image-search requests trigger temporary blocking. _record_search_failure 422 failure path triggers record Verify failure window, limit, block duration, and 429 behavior.

Schema Claims

Claim ID Report Claim Primary Evidence Validation Method
S-01 Employee API schema includes fullName, optional DoB/email/Phone/gender. EmployeeBase schema Compare fields across EmployeeBase and EmployeeCreate.
S-02 Visitor API schema mirrors employee profile shape minus employee_id. VisitorBase schema Compare VisitorBase fields with EmployeeBase overlap.
S-03 Persistence models use Beanie documents with Employees/Visitors collection names. Employees collection mapping Inspect collection mappings for both employee and visitor documents.

Frontend Contract Claims

Claim ID Report Claim Primary Evidence Validation Method
F-01 Desktop and mobile share create/search/upload endpoint conventions. Desktop API create/search/upload functions, Mobile API create/search/upload functions Compare function names and endpoint paths in both API clients.
F-02 Frontend sends phone as Phone (capital P), matching backend schemas. Desktop API Phone contract key Confirm key name in payload builders and schema fields.
F-03 Date of birth is transmitted as DoB with date-like string input in frontend forms. ISO date validation in mobile form Confirm YYYY-MM-DD validation and payload mapping.

Usage Guidance

For academic report writing:

  1. Use the claim IDs in your draft notes.
  2. Cite at least one primary evidence file per claim.
  3. Prefer adding a second supporting file for higher-stakes claims.
  4. Revalidate claims after major code changes by rechecking the listed files.

How to Cite in Report

Use the following sentence template when referencing implementation evidence:

“Claim is supported by implementation in and corroborated by . Validation was performed by ."

Example A (single-source citation):

“Claim C-02 is supported by implementation in get_api_key dependency. Validation was performed by checking auth dependency wiring and expected status-code behavior.”

Example B (dual-source citation):

“Claim C-12 is supported by implementation in setRecordId on create and corroborated by mobile uploadImages call. Validation was performed by tracing record ID persistence and upload flow execution.”

Compact Citation Form

For short-form report footnotes, use:

  1. <CLAIM_ID>: <PRIMARY_EVIDENCE_LINK>; <SUPPORTING_EVIDENCE_LINK>

Example:

  1. C-10: [no-match branch](../Backend/SOFRS-EA-Backend/backend/routers/Image.py#L539); [ambiguous branch](../Backend/SOFRS-EA-Backend/backend/routers/Image.py#L620)
This site is open source. Improve this page.