Refactor code structure for improved readability and maintainability

faceai/README.md

@@ -76,7 +76,7 @@ The checked-in `docker-compose.yml` starts:
 The local stack also mounts:
 
 - `../bin/Face_Recognition_Unix` into the processor container as the matcher binary source
-- `../test_pkl` into the processor container as fallback PKL test data
+- `../test_pkl` into both the public FaceAI container and the processor container as the shared read-only PKL dataset root
 - `../www` into the PHP container so the real bridge files are used
 
 ### Run The Browser Test
@@ -84,7 +84,7 @@ The local stack also mounts:
 Open:
 
 ```text
-http://localhost:8080/faceai_simulator.php?raceId=101&lang=it
+http://localhost:8080/faceai_simulator.php?raceId=202&lang=it
 ```
 
 That page simulates the legacy race 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`.
@@ -160,9 +160,11 @@ services:
       FACEAI_QUEUE_NAME: faceai-searches
       FACEAI_RUNTIME_ROOT: /data/runtime
       FACEAI_UPLOAD_ROOT: /data/runtime/uploads
+      FACEAI_PKL_ROOT: /data/pkl
       FACEAI_ENABLE_LOCAL_LEGACY_STATIC: 0
     volumes:
       - faceai-runtime:/data/runtime
+      - /srv/faceai/pkl:/data/pkl:ro
     ports:
       - "127.0.0.1:3001:3001"
     depends_on:
@@ -230,11 +232,22 @@ Processor settings:
 | Variable | Required | Example | Purpose |
 | --- | --- | --- | --- |
 | `FACEAI_PKL_ROOT` | yes | `/data/pkl` | mounted race-to-PKL dataset root |
-| `FACEAI_TEST_PKL_ROOT` | optional | `/data/pkl/test` | local-only fallback PKL location |
 | `FACEAI_MATCHER_BINARY` | yes | `/opt/face-recognition/face_matcher` | matcher executable inside the processor container |
 | `FACEAI_WORKER_CONCURRENCY` | optional | `2` | BullMQ worker concurrency |
 | `FACEAI_WORKER_TIMEOUT_MS` | optional | `300000` | matcher timeout in milliseconds |
 
+The mounted PKL root is expected to use this structure:
+
+```text
+/data/pkl/
+  2026/
+    04.APRILE/
+      PISA/
+        any-file-name.pkl
+```
+
+The public FaceAI site mounts the same path read-only so it can check availability during session bootstrap and refuse uploads immediately when the race has no `.pkl` data.
+
 Do not enable `FACEAI_ENABLE_LOCAL_LEGACY_STATIC` in production. That mode exists only for local simulator flows.
 
 ### Legacy-Side Configuration That Must Match
@@ -276,7 +289,7 @@ This scaffold can now be deployed with the public site, processor, and Redis, bu
 
 - search state is short-lived in Redis and is not backed by a durable database
 - runtime uploads and matcher output still need an agreed production retention and cleanup policy
-- the final production PKL/NAS layout is not yet locked down
+- the PKL mount contract is now defined, but final NAS operations and cleanup policy still need to be hardened
 - the backend currently sets the FaceAI session cookie with `secure: false`, which should be hardened before final public rollout
 - the local simulator endpoints under `/dev/*` are still present in the app and should be treated as non-production scaffolding
 - the processor CSV parser is still based on the current scaffolded matcher output assumptions
@@ -299,7 +312,6 @@ FACEAI_QUEUE_NAME=faceai-searches
 FACEAI_RUNTIME_ROOT=/data/runtime
 FACEAI_UPLOAD_ROOT=/data/runtime/uploads
 FACEAI_PKL_ROOT=/data/pkl
-FACEAI_TEST_PKL_ROOT=/data/pkl/test
 FACEAI_MATCHER_BINARY=/opt/face-recognition/face_matcher
 ```
 
@@ -311,6 +323,14 @@ In the provided Docker Compose stack, that wiring is already done with:
 FACEAI_LEGACY_RETURN_URL=http://localhost:8080/faceai_return.php
 ```
 
+The local PHP simulator also needs the legacy bridge feature flag enabled:
+
+```text
+FACEAI_FEATURE_ENABLED=1
+```
+
+The checked-in `docker-compose.yml` now sets that on the `legacy-php` service so the simulator can launch the FaceAI handoff flow locally.
+
 ## Notes
 
 - Search orchestration now uses Redis and a dedicated processor worker.