121 lines
4.8 KiB
Markdown
121 lines
4.8 KiB
Markdown
# 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.
|