Regalamiunsorriso/faceai/README.md

FaceAI Scaffold

This folder scaffolds the new FaceAI app described in the integration plan.

It includes:

• a Vue frontend for the FaceAI upload and polling flow
• a Node/Express backend for session exchange, mocked searches, and return handoff
• a local legacy simulator so the launch and return flow can be tested without the old Java site
• a Dockerized PHP Apache stack for exercising the real www/faceai_handoff.php and www/faceai_return.php bridge files

Structure

faceai/
  apps/
    backend/
    frontend/
  docker/
    Dockerfile

What The Local Test Covers

The local simulator exercises the exact flow the plan is aiming for:

1. a legacy-like race page shows a Face ID button instead of tipoPuntoFoto
2. clicking it hits a mock legacy handoff endpoint
3. the backend signs a short-lived handoff token and redirects to the Vue app
4. the Vue app exchanges the token for its own FaceAI session cookie
5. the user uploads a selfie and starts a mocked race-scoped search
6. the frontend polls until the job completes
7. FaceAI requests a signed return URL
8. the browser is redirected back to a legacy-like filtered race page showing only the matched photos

Local Run

From this folder:

npm install
npm run dev

Then open:

http://localhost:3001/dev/legacy/race?raceId=101&lang=it

That page simulates the old site and launches the FaceAI app at http://localhost:5173.

Docker Run With PHP Simulator

If you do not have PHP locally, use Docker instead:

npm install
npm run build
docker compose up --build

The Docker stack reuses the local FaceAI workspace and only containerizes the runtime services. That means PHP is fully containerized, while the Node service runs inside Docker against the already-installed local workspace dependencies and the already-built frontend assets.

This starts:

• FaceAI app on http://localhost:3001
• PHP Apache serving www on http://localhost:8080

For the end-to-end test through the PHP bridge, open:

http://localhost:8080/faceai_simulator.php?raceId=101&lang=it

That page loads the original race-page JavaScript from www/_js/rus-ecom-240621.js, lets the script replace the visible tipoPuntoFoto selector with the new Face ID button, and launches the real PHP handoff bridge at www/faceai_handoff.php.

If you change frontend code and want Docker to serve the updated UI, rebuild first with:

npm run build

Environment

Defaults are already set for local development, but these can be overridden:

PORT=3001
FACEAI_FRONTEND_URL=http://localhost:5173
FACEAI_PUBLIC_BASE_URL=http://localhost:3001
FACEAI_LEGACY_RETURN_URL=http://localhost:3001/dev/legacy/return
FACEAI_SHARED_SECRET=change-me
FACEAI_SESSION_COOKIE=rus_faceai_session

If you want FaceAI to return through the new PHP bridge prepared under www, point FACEAI_LEGACY_RETURN_URL to that endpoint instead, for example http://localhost/faceai_return.php or the equivalent URL in your local PHP setup.

In the provided Docker Compose stack, that wiring is already done with:

FACEAI_LEGACY_RETURN_URL=http://localhost:8080/faceai_return.php

Notes

• The backend currently uses in-memory stores and mocked search results.
• No database or real queue is wired yet.
• The local legacy simulator is intentionally backend-driven so the handoff can be tested without compiling the existing Java application.
• www/faceai_simulator.php exists only for local testing. It does not replace the actual JSP race page.
• The final legacy integration still needs a real signed identity source and a real return-filter implementation on the old site.