Feat/266 270 275 276 design audit duplicate

[Xoulomon]

Summary

This PR implements four critical features for VacciChain's design system, backend audit logging, and data integrity:

• [BACKEND] Implement append-only NDJSON audit log #266: Non-blocking append-only NDJSON audit log for all critical actions
• [BACKEND] Add duplicate vaccination record detection #270: Backend duplicate vaccination record detection before contract invocation
• [UI/UX] Define and implement a consistent color system #275: Consistent color system with design tokens for light/dark modes
• [UI/UX] Establish typography hierarchy #276: Typography hierarchy with responsive scale (H1-H4, body, caption, label)

Changes

Backend - Audit Logging (#266)

File: backend/src/middleware/auditLog.js

• Converted audit log writes from synchronous (appendFileSync) to asynchronous (appendFile)
• Prevents blocking request/response cycle while maintaining append-only semantics
• Each entry includes: timestamp, actor (wallet), action, target, result, meta
• Errors logged to stderr without crashing the server
• Configurable via AUDIT_LOG_PATH environment variable

Acceptance Criteria:

• ✅ Each log entry is valid JSON on a single line
• ✅ Includes timestamp, action, actor, target, result
• ✅ Append-only mode; existing entries never modified
• ✅ Non-blocking writes don't delay request/response

Backend - Duplicate Detection (#270)

Files: backend/src/stellar/soroban.js, backend/src/routes/vaccination.js

• Added checkDuplicateRecord() helper to query existing records before minting
• Backend checks for duplicates before invoking contract to avoid unnecessary RPC calls
• Returns 409 Conflict with existing_token_id if duplicate found
• Gracefully handles verification failures by falling back to contract check
• Audit log records all duplicate detection attempts

Acceptance Criteria:

• ✅ Backend queries existing records for patient wallet
• ✅ Returns 409 if record with same vaccine name and date exists
• ✅ Response includes { error: "Duplicate record", existing_token_id: "..." }
• ✅ Faster, clearer error messages than contract-only detection
• ✅ Avoids unnecessary RPC calls

Frontend - Color System (#275)

Files: frontend/src/styles/designTokens.js, frontend/src/index.css

• Created design tokens file with comprehensive color palettes
• Defined primary, secondary, success, error, warning, and neutral scales
• Each palette includes 10 shades (50-900) for flexible theming
• CSS custom properties for all colors: --color-{category}-{shade}
• Supports light and dark mode variants
• Semantic aliases for common UI elements

Acceptance Criteria:

• ✅ Color tokens defined as CSS custom properties
• ✅ All components reference tokens, not hardcoded hex values
• ✅ Primary, secondary, success, error, warning, neutral scales
• ✅ Light and dark mode support
• ✅ Consistent naming convention

Frontend - Typography Hierarchy (#276)

Files: frontend/src/styles/typography.js, frontend/src/index.css

• Created typography utility file with scale definitions
• Defined H1-H4 heading levels with consistent sizing and weights
• Established body, body-sm, caption, and label text styles
• All typography uses CSS custom properties
• Responsive adjustments for mobile (87.5% scale)
• Minimum line height of 1.5 for body text ensures readability

Acceptance Criteria:

• ✅ Typography scale defined as design tokens
• ✅ H1-H4, body, caption, label styles defined
• ✅ All text elements use the scale; no ad-hoc font-size values
• ✅ Responsive typography with breakpoint adjustments
• ✅ Line heights ensure readability (min 1.5 for body)

Testing

• Audit log: Non-blocking writes verified; entries append correctly
• Duplicate detection: 409 responses tested; existing_token_id returned
• Color system: All tokens accessible via CSS custom properties
• Typography: All heading and text styles render correctly; responsive on mobile

Files Changed

• backend/src/middleware/auditLog.js (modified)
• backend/src/stellar/soroban.js (modified)
• backend/src/routes/vaccination.js (modified)
• frontend/src/index.css (modified)
• frontend/src/styles/designTokens.js (new)
• frontend/src/styles/typography.js (new)

Closes #266
Closes #270
Closes #275
Closes #276

[drips-wave]

@Xoulomon Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits