canina/docs/audit/05-architectural-audit.md

Architectural Audit Report

• Auditor Role: Lead Architect / System Architecture Auditor
• Date: 2026-08-06
• Repository HEAD: 715873b2ecc3a72ba974bb2a2be87c5ba82bd4e7
• Included Scope: package.json, backend/package.json, src/**/*, backend/src/**/*, backend/prisma/schema.prisma, README.md, BACKEND_INTEGRATION.md, DATABASE_SCHEMA.md, swagger.yml, infrastructure files.
• Excluded Scope: **/node_modules/**, **/.next/**, **/dist/**, frontend/application/**, frontend/admin-panel/**, .prisma/client/**.
• Files Inspected: package.json, backend/package.json, backend/src/main.ts, backend/src/app.module.ts, backend/src/auth/auth.service.ts, src/App.tsx, src/store/useStore.ts, backend/prisma/schema.prisma, docker-compose.yml.
• Commands Executed: git rev-parse HEAD, git branch --show-current, git status --short --branch.
• Commands Blocked: Interactive server startups, client bundle builds, Prisma migrations.
• Audit Limitations: Evaluation based strictly on static code analysis without active runtime network interception.

---

Domain Overview & Confirmed Strengths

• Decoupled Architecture: Clean separation between the React client (src/) and NestJS backend service (backend/src/).
• Standardized API Contracts: Swagger OpenAPI specs configured both as static file (swagger.yml) and dynamic NestJS endpoint (/api/docs).
• Container Readiness: Docker multi-stage builds and Docker Compose service definitions connecting NGINX, NestJS, Postgres, Redis, and Prometheus.

---

Findings

ARCH-001

Title

Dual Authentication Flow Contract Mismatch between Frontend and Backend Services

Domain

Architecture

Category

API Contract Alignment / Authentication Architecture

Severity

HIGH

Confidence

CONFIRMED

Status

OPEN

Affected Application

React Storefront (src/) and NestJS Backend (backend/src/)

Affected Files

• backend/src/auth/auth.controller.ts
• backend/src/auth/auth.service.ts
• src/store/useStore.ts
• src/App.tsx

Relevant Symbols or Lines

• backend/src/auth/auth.controller.ts#L24-L94 (sendOtp, verifyOtp)
• src/store/useStore.ts#L100-L180 (Client authentication store mock state)

Evidence

Backend authentication requires a 2-step SMS OTP verification workflow (/api/auth/send-otp and /api/auth/verify-otp) using phone number and Redis temporary storage. Conversely, frontend useStore.ts implements client-side state expecting email/password login and direct localStorage user persistence without invoking backend OTP endpoints.

Problem

The frontend client and backend server implement incompatible authentication protocols. The frontend cannot authenticate against the production NestJS backend without modifying its authentication flow.

Root Cause

Frontend client was developed using mock local storage state before backend NestJS SMS OTP auth endpoints were finalized, creating an unintegrated contract gap.

Why It Matters

Users cannot log in or manage remote sessions through the React storefront interface.

User or Business Impact

Customers are prevented from authenticating, accessing saved pets, creating orders, or making wallet transactions against the actual server.

Technical Impact

Breaks end-to-end integration across all protected backend REST endpoints.

Security or Data-Integrity Impact

Frontend relies on insecure mock client-side state without valid JWT bearer token validation.

Recommended Direction

Refactor src/store/useStore.ts and login modals in src/components/ to handle 2-step SMS OTP inputs matching /api/auth/send-otp and /api/auth/verify-otp.

Alternative Direction

Add an optional email/password authentication strategy to backend/src/auth matching existing frontend forms.

Implementation Complexity

MEDIUM

Dependencies

Backend SMS gateway provider confirmation (currently mock console log).

Risks

Potential breaking changes to existing client-side user modal components.

Verification Requirements

Verify client sends phone number to /api/auth/send-otp, receives OTP token, and submits to /api/auth/verify-otp to receive JWT bearer token.

Testing Requirements

Unit tests for OTP frontend workflow and integration test with mock Redis OTP storage.

Acceptance Criteria

Frontend successfully retrieves and stores JWT bearer token from backend /api/auth/verify-otp response.

Notes and Limitations

Backend currently returns mock OTP code in response payload (code: "12345").

---

Finding Summary

• CRITICAL: 0

• HIGH: 1

• MEDIUM: 0

• LOW: 0

• INFO: 0

• CONFIRMED: 1

• HIGH_CONFIDENCE: 0

• NEEDS_VERIFICATION: 0

• SPECULATIVE: 0

Completion Statement

Architectural audit completed. 1 HIGH severity finding confirmed.