SADEV-2443: Add pre-registration reference architecture

[alanvalz]

Add Pre-Registration Reference Architecture

📖 Summary

This change introduces a production-ready reference implementation for YubiKey pre-registration ordering, demonstrating modern best practices for secure, type-safe web applications with OIDC authentication.

🛠 Technical Implementation

⚛️ React Client (TypeScript)

• Architecture: Implemented a scalable, feature-based architecture (auth, orders, shared)
• UI/Theming: Upgraded to Material UI v7 with custom color palette
• State Management: Integrated React Query for server state (stale time: 5min, retry: 3)
• Authentication: Added OIDC support via react-oidc-context
• Validation: Implemented Zod for runtime validation at API boundaries and environment variable validation (fail-fast)
• Error Handling: Added professional error screen component with dev-mode technical details
• Type Safety: Fully typed API client with robust error handling

☕ Spring Cloud Gateway (Java 17)

• Security: Implemented OIDC JWT authentication with token relay pattern
• Configuration: Externalized configuration via environment variables; added CORS support for cross-origin requests
• Observability: Added SLF4J structured logging (profile-based: verbose in dev, minimal in prod) and Spring Boot Actuator for health/info endpoints
• Resilience: Configured graceful shutdown support and UserInfoGatewayFilter for downstream context propagation
• Error Handling: Enhanced security config to properly handle 401/403 states

🏗 Infrastructure

• Local Dev: Added run-local.sh startup script for rapid development
• Configuration: Centralized .gitignore for Node/Env files and standardized .env-based configuration
• Health: Exposed /actuator/health and /actuator/info endpoints

🛡 Security & Verification

• Secrets Management: No secrets in source control (all externalized to .env)
• Sanitization: Production-safe error messages (no stack traces leaked in prod)
• Traffic: CORS properly configured; JWT validation enforced on all API endpoints
• Manual Testing Completed:
  • ✅ Authentication flow
  • ✅ Order submission
  • ✅ Address validation & country lists
  • ✅ Error states & health checks

🚀 What's Next

🐳 Docker & Deployment

• Create Dockerfiles for client and gateway
• Add docker-compose.yml for local development
• Create deployment scripts and documentation

🔐 Keycloak Integration

• Integrate fully with existing Keycloak instance
• Configure realm and client settings
• Test end-to-end authentication flow

📚 Documentation

• Create ARCHITECTURE.md with system design overview
• Create DEPLOYMENT.md with deployment procedures
• Create DEVELOPMENT.md with setup and contribution guidelines

📦 Shipment Tracking

• Add Gateway routes for tracking endpoints
• Implement React UI with timeline component
• Display order status and history

♿ UI/UX Polish

• Conduct accessibility audit (WCAG compliance)
• Optimize for mobile devices
• Simplify visual design and user flows

🤖 AI Development Context

• Add .ai/ folder with project context
• Create .cursorrules for AI-assisted development
• Document domain-specific patterns

🛡️ Robust Error Handling

• Global API Interceptor: Handle 401/403/500 errors centrally in src/shared/api/client.ts.
• Error Reporting Integration: Replace console.error in ErrorBoundary with Sentry/Datadog SDK.
• Toast Notification System: Implement a global provider for transient success/error messages.
• Error Message Sanitization: Ensure no raw stack traces or internal IDs are ever displayed to the user in the UI.

🔒 Security Review

• Create production readiness checklist
• Conduct comprehensive security audit
• Document security best practices

🧪 Testing & CI/CD

• Implement unit and integration test suites
• Set up CI/CD pipeline
• Add automated security scanning

[elukewalker]

What looks good

• architecture
• code quality
• spring security best practices
• secrets management
• modern frontend patterns

Requested changes

• Documentation
  • Add the FPR use case and integration guidance to /docs/docs/fido-pre-registration/intro.md ...
    • What is FPR?
    • Describe the business model Bank -> Yubico ->phishing resistant customer with YubiKey
    • When to use this pattern
  • /docs/docs/fido-pre-registration/architecture.md
    • Architecture overview
    • Why API Gateway
    • Components (gateway, fido-connector, frontend
  • /docs/docs/fido-pre-registration/integration.md
    • Integration guide, flow diagram, etc...
  • /docs/docs/fido-pre-registration/setup.md
    • prerequisites, environment setup, running with docker, manual setup
• Docker Integration
  • the workshop uses docker compose for all examples, this PR currently requires a manual setup. update the deploy/compose.yaml to spin up the required services.
  • create docker files for the services
  • update the deploy scripts
• Add testing Frontend, gateway, E2E tests with playwright
• Use consistent dependency versions: the gateway uses Java 17 and spring boot 3.2.5. the rp uses Java 21 and spring boot 2.7.12
• save the gateway openAPI spec to the project, perhaps in /api.