Talent Marketplace — technical documentation

Architecture and scope

The HR/manager journey is rendered by legacy Company/EmployeeBookBundle; the employee journey is implemented separately in Customer/EmployeeBookBundle. Nextgen-back exposes field metadata; access administration screens are shared dependencies. These APIs do not imply the marketplace search is implemented in nextgen-front.

Browser → Legacy controller → authorized filters and profiles
                       └→ AI Hub client → filter suggestions
                             └→ Mapper → browser form

AI prefill neither ranks nor searches profiles. AI Hub opportunity suggestion agents belong to a separate journey and must not be treated as this endpoint.

Components and data

Component	Responsibility
Company/EmployeeBookBundle/Controller/DefaultController.php	Directory page, AI request validation and employee details.
Service/AI/TalentMarketplace/TalentMarketplaceFilterClient.php	AI Hub HTTP request and error translation.
Service/AI/TalentMarketplace/TalentMarketplaceFilterMapper.php	Allowlist of displayed filters and response mapping.
TMKPFiltersType	Custom filter form for tmkp_bo.
Nextgen-back: Domain/V1/Field/DTO/AbstractFieldDTO.php	Field visibility properties.

Profile details use User, Customer, CompanyEntity and employee/job field values. Setting identifies the tenant. Visible custom fields are ordered by position.

Routes and authorization

Legacy route	Purpose
/company/annuaire/	HR/manager marketplace.
POST /company/annuaire/ai-filters	Prefill; XMLHttpRequest required.
/company/annuaire/{id}	HR/manager view of employee details.
/plateforme/annuaire/	Employee directory (EMPLOYEE_BOOK_FO_ACCESS).
/plateforme/annuaire/{employee}	Employee-context details.

Prefill requires a user with a school, EMPLOYEE_BOOK_BO_ACCESS, tmkp_ai_search and a valid CSRF token for that option. The query is trimmed and must contain 1–4,000 characters.

Details check permission against the target employee and the same Setting. When collaborator_can_change_visibility is enabled, getNoProfileVisibility() blocks hidden profiles. Failed detail access redirects the user.

Code map for the two personas

All paths below are relative to the named repository root. Claims in this map are Verified in code in the local working tree; deployed parity is Not verified.

Responsibility	Repository, path and symbol
Mount both directory bundles	legacy: config/routes.yaml, company_employee_book and customer_employee_book
HR/manager page, detail and AI	legacy: src/Company/EmployeeBookBundle/Controller/DefaultController.php, indexAction, detailAction, aiFiltersAction
Employee page and detail	legacy: src/Customer/EmployeeBookBundle/Controller/DefaultController.php, indexAction, detailAction
Module/role and tenant checks	legacy: src/Company/EmployeeBookBundle/Security/EmployeeBookVoter.php, voteOnAttribute, canAccessFo, canAccessBo
Shared custom filter form	legacy: src/Form/Type/TMKPFiltersType.php, buildForm
Select context-specific fields	legacy: src/Company/SwpBundle/Form/Type/SearchCompanyEntityType.php, buildForm
Legacy field editor	legacy: src/Form/Type/CompanyEntityForm.php and src/Company/SwpBundle/Resources/views/List/Forms/form.html.twig
Redesigned roles/visibility routing	nextgen-front: src/router/private-routes.ts, AppRoute.ROLES and AppRoute.VISIBILITY_GROUPS
Field metadata mapping	nextgen-back: src/Domain/V1/Field/DTO/AbstractFieldDTO.php, MappingProperty annotations
Matching availability check	legacy: src/Service/UserCustomJobMatching/UserCustomJobMatchingService.php, areScoresBySettingAvailable, getActiveSettings

The diagram describes responsibilities and dependencies, not a verified network topology or a claim that every legacy permission is configured through the new administration. The configuration guide separates customer-admin functionality from project/platform-core prerequisites in both generations.

Employee implementation and authorization

Verified in code: config/routes.yaml mounts the employee bundle under /plateforme/annuaire; its routing file defines the page, /{employee} detail and POST /action/visibility_profile/{user}. The last route changes profile visibility and requires XMLHttpRequest; it is separate from search and is not invoked during documentation inspection.

Customer/EmployeeBookBundle/Controller/DefaultController::indexAction checks EMPLOYEE_BOOK_FO_ACCESS and redirects to the employee home if access is denied. It builds TMKPFiltersType with filter_type = tmkp_fo, tenant and locale. The HR/manager controller supplies tmkp_bo. SearchCompanyEntityType::buildForm restricts definitions with filterTmkpFo / filterTmkpBo; these flags are distinct from general filterFo / filterBo.

EmployeeBookVoter::voteOnAttribute checks tenant consistency for a target User. Employee access uses the annuaire module. HR/manager access uses the high-potential branch or the annuaire_bo branch with master-school/active-manager and role conditions; see canAccessBo, hasHighPotentialAccess and hasEmployeeBookBOAccess. A user switching spaces does not bypass these checks.

Employee detailAction checks EMPLOYEE_BOOK_FO_ACCESS for the target, loads non-default fields with isVisibleOnTalentMarketplaceDetailedProfile = true, orders them by position, and renders the employee detail template. HR/manager details use the BO visibility property and additional checks described above. Exact result-query authorization beyond these controller/voter paths remains Not verified in this review.

No AI prefill route or action was found in the inspected employee routing/controller. The manager AI contract below must not be documented as an employee endpoint.

Matching data and platform boundaries

Verified in code: HR/manager offer matching requires job_matching_bo; employee offer matching requires job_matching_fo. Both also call UserCustomJobMatchingService::areScoresBySettingAvailable(). The employee controller filters available offers by validity before passing them to its template.

areScoresBySettingAvailable() checks whether the tenant is listed by getActiveSettings(), whose implementation enumerates tenant-specific matching tables. It does not check row completeness, score freshness or business quality. The presence of storage, the generation of matching scores and feature activation are separate concerns. Provisioning is a platform responsibility; this document does not prescribe a manual database mutation.

AbstractFieldDTO maps employee/manager filter properties to filterTmkpFo / filterTmkpBo, and detailed-profile properties to isVisibleOnTalentMarketplaceDetailedProfile / isVisibleOnTalentMarketplaceDetailedProfileBo. Its false initializers are DTO defaults, not proof of persisted tenant values or a cross-generation override policy.

AI Hub exchange

The server sends:

POST {AI_HUB_BASE_URL}/api/v1/talent-intelligence/talent-marketplace/filters
Accept: application/json
X-API-Key: <server key>
Content-Type: application/json

Illustrative structure; available keys are calculated from displayed filters:

{
  "client_id": "123",
  "query": "Find HR employees open to mobility",
  "locale": "en_GB",
  "filters": [
    {"key": "job"},
    {"key": "internal_mobility"},
    {"key": "company_entity", "company_entity_id": 456}
  ]
}

Locale is optional and must match the accepted language format, such as en or en_GB. The client requires HTTP 200 and a filters array. The mapper retains authorized filters and the applicable key, company_entity_id, kind, values, value, start and end attributes. Examples do not define every business value schema.

The browser receives the mapper's {"filters": [...]} envelope. The user then confirms the profile search.

Errors and limits

Case	Prefill response
Missing access or feature activation	403, forbidden.
Invalid CSRF	403, invalid_token.
Empty/too-long query	400, invalid_query.
Missing configuration, network failure or invalid response	502, unavailable.
Timeout	504, unavailable.

HTTP max_duration is 20 seconds. This is not an end-to-end search performance commitment. Failure must not be interpreted as no matching profiles.

Configuration and operations

• AI_HUB_BASE_URL: server-side AI Hub URL.
• AI_HUB_API_KEY: server secret passed in the header, never exposed to the browser.
• tmkp_ai_search: business activation option.
• job_matching_bo: used alongside score availability to expose offer matching.
• Log prefix: [TALENT MARKETPLACE] AI filters prefill - , with setting_id context.

Technical acceptance criteria

1. Verify access/CSRF failures and query length boundaries, including 4,000 and 4,001 characters.
2. Verify tenant isolation and hidden profiles.
3. Verify each visibility property in both contexts.
4. Verify custom filters and suggestions outside the allowlist.
5. Simulate valid HTTP 200, missing array, remote errors and timeout.
6. Verify prefill never runs the search automatically and manual search remains available.

Constraints and exclusions

This guide describes inspected code interfaces, not universal tenant activation. AI costs, rate limits and SLAs are not defined by these components. Opportunity suggestion agents and application workflows are outside scope.

Browser request and filter lifecycle

Verified in code: the browser posts form parameters query and _token to the legacy AI route using an XMLHttpRequest. The controller trims the description, validates access and CSRF, derives the available filters from the user's tenant and form, then calls the server-side client. The AI Hub JSON request shown above is a separate server-to-server contract.

The browser keeps existing filters when the response has no usable suggestions. With usable suggestions, it resets the current filters and applies the returned values. It does not submit the employee search. Repeated descriptions therefore replace criteria rather than accumulate them. The mapper identifies custom fields by the pair key / company_entity_id, removes unrequested filters and enriches skill values with tenant-specific display information.

Runtime, privacy and extension points

Verified in code: prefill depends on the legacy Symfony HTTP client, tenant configuration, authorization services, the custom filter form and the browser script. No background job or profile-write operation is invoked by aiFiltersAction. The ordinary profile-detail action is separate; this statement does not describe every side effect of profile viewing.

The description, tenant identifier, optional locale and displayed-filter descriptors are transmitted to AI Hub. The server builds that payload rather than sending employee result profiles. Users should describe professional criteria and avoid including personal or confidential information in free text. Not verified: deployed AI provider, retention, residency, rate limits and logging policy across the remote service. Validate those points before enabling AI for a customer.

For a new filter, review the actual form/template, BO_FILTER_SWITCHES or custom-field descriptor, toFrontPayload and the browser's applyFilter implementation together. Add the matching remote contract only after confirming AI Hub support. Existing legacy unit tests under tests/Unit/Service/AI/TalentMarketplace/ cover the client and mapper; they were inspected as available validation targets, not executed for this documentation update.

Legacy, redesign and remote-service boundary

Verified in code: this request path belongs to legacy Company/EmployeeBookBundle. Nextgen-back field metadata maps to the legacy field controls; nextgen-front visibility administration is a dependency, not evidence of an equivalent search implementation. Not verified: a full redesigned search route, migration behavior and deployment compatibility between repository revisions.

The endpoint path above is Verified in code in the legacy client. No matching Talent Marketplace endpoint implementation was found in the local aihub/src checkout. The request example therefore describes the caller's expected contract; remote validation rules, returned business-value schemas and production availability remain Not verified.

Evidence and limitations

Reviewed on 15 October 2026 against local working-tree sources, which may include uncommitted changes.

Evidence	Source relative to repository root
Verified in code: HR/manager routes and controller validation	legacy: src/Company/EmployeeBookBundle/Resources/config/routing.yml, src/Company/EmployeeBookBundle/Controller/DefaultController.php
Verified in code: integration and allowlist	legacy: src/Service/AI/TalentMarketplace/TalentMarketplaceFilterClient.php, TalentMarketplaceFilterMapper.php in the same directory
Verified in code: browser filter replacement	legacy: web/assets_profile/tmkp-ai-search.js
Verified in code: field metadata	nextgen-back: src/Domain/V1/Field/DTO/AbstractFieldDTO.php
Verified in code: visibility administration exists	nextgen-front: src/modules/Users/VisibilityGroups/
Verified in code: employee routes and access	legacy: config/routes.yaml, src/Customer/EmployeeBookBundle/Resources/config/routing.yml, src/Customer/EmployeeBookBundle/Controller/DefaultController.php, src/Company/EmployeeBookBundle/Security/EmployeeBookVoter.php
Not verified: remote endpoint implementation	No corresponding file found in local aihub/src

Observed in application: the functional guide records manager search/profile observations and employee-directory redirection from smartmobility.io; these observations are supplementary and do not establish code parity. The configuration guide records administrator screens. No AI end-to-end execution was performed. Error mappings above are verified caller behavior. Technical acceptance criteria are proposed verification steps, not completed runtime tests. Tenant-specific activation and complete result-query authorization require separate application validation.

See Configuration for rollout checks and Functional guide for the user journey.

Functional-guide evidence

These implementation and product references support the functional guide. Local source behavior does not establish which revision or optional features are deployed. Application observations remain distinct from code and documentary evidence.

• Observed in application: the same supplied test account was switched between manager and personal spaces. Manager controls, expanded contract/matching choices, high-potential criteria, manual search, pagination and a profile were inspected. Employee navigation was inspected; direct employee-directory access redirected to home. Separate admin visibility screens and the legacy field dialog support the configuration guide.
• Verified in code: legacy src/Company/EmployeeBookBundle/Controller/DefaultController.php, src/Customer/EmployeeBookBundle/Controller/DefaultController.php, their Resources/views/Default/ templates, src/Company/EmployeeBookBundle/Security/EmployeeBookVoter.php, src/Form/Type/TMKPFiltersType.php and web/assets_profile/tmkp-ai-search.js establish the distinct contexts, controls and conditional AI behavior.
• Verified in code: nextgen-back src/Domain/V1/Field/DTO/AbstractFieldDTO.php and nextgen-front src/modules/Users/VisibilityGroups/ describe field metadata and administration dependencies. The four reference repositories are present; a local source tree does not prove deployment parity.
• Inferred: illustrative search scenarios describe uses of verified controls, not guaranteed matches.
• Not verified: employee search/results/profile contents, live AI requests, offer scores, complete AND/OR and ranking behavior, all optional controls and every result-query authorization branch. Screenshots of unavailable employee-directory and AI controls are intentionally absent. Result screenshots redact identifying card contents; full profile screenshots are omitted to exclude personal information.

Journey verification — 26 October 2026

Observed in application: PS Testing 2026, Jim Carter. Personal-space Annuaires is now present. A self-name search for Jim Carter returned no results; no distinct employee detail or AI result was inspected. Earlier no-entry evidence is historical and does not describe the current menu.