Applications and APIs¶

AI Hub runs seven application surfaces in the same process. The main application owns startup and shutdown; it prepares the shared MongoDB connection, agent graphs, scheduler, message consumers and optional background knowledge-base synchronization before traffic is accepted.

The outer middleware chain adds the SRV backend cookie and handles CORS, request logging and sensitive-route rate limiting for all mounted paths. BackendIdentityFastAPI wraps the complete Main API middleware stack, including the server-error handler, so HTTP 500 responses also identify the serving host. Mounted applications share this single cookie layer. See the backend response cookie for its attributes and operational use. Generated documentation, Swagger, ReDoc and OpenAPI schemas are public. Authentication and tenant resolution remain explicit request dependencies on the relevant business routes. Prometheus instrumentation is enabled on every application. Rate-limit counters are shared by workers in one container and are configured as described in the configuration guide.

Application map¶

The Swagger paths above are the authoritative source for request and response schemas. This page describes the functional boundary of each application.

Main API¶

The Main API groups the historical AI Hub services. To keep /main/docs readable, its operations are presented under broad Swagger categories:

The main application also owns background execution:

• the scheduler;
• RabbitMQ consumers in MongoDB mode, or the PostgreSQL notification listener and independent job workers when PostgreSQL is configured;
• tenant-enabled knowledge-base synchronization;
• shutdown of shared AI-provider and database connections.

Main API routes are registered centrally by src/core/main_routes.py, while each router and its business workflow remain in the owning package. Entity adapters live under entity/{user,job,opportunity,training,skill}/api and JOM/JPM adapters live under their matching products. Every privileged adapter lives under admin/api instead, and calls the same business services owned by those packages. There is intentionally no global src/routers package.

Skills Library keeps its Main API router in api, request models in schemas, query, ranking and embedding-administration workflows in services, and its PostgreSQL search adapter in repositories.

Talent Intelligence keeps its HTTP adapters in api, request models in schemas, business workflows in services and PostgreSQL-specific search in repositories. Its root openai_utils.py remains a deliberate shared entry point because Lexi also consumes those established LLM helpers.

Request schemas follow the same ownership rule. Skills Library owns its search schemas; Talent Intelligence owns its experience schemas; Training Matching owns its search and development-objective schemas; Lexi owns its Job-to-Skills schema and error handling. There is intentionally no global src/models package.

Several entity query routes retain /api/v1/admin/... in their URL solely for HTTP compatibility. They stay in the Main API, are grouped under Users, Jobs or Opportunities in Swagger and use the standard authentication dependency: the segment is a historical name, not an administrator-key marker. JOM/JPM compatibility routes that were historically public remain public; see authentication.

The five migrated pwc-jom-php operations intentionally retain their /v1 paths and JSON or plain-text response contracts. They require AI Hub's standard X-API-Key; in MongoDB mode they prefer its clientId and fall back to Client-ID with the fixed smartmobility data source and remain unavailable in PostgreSQL mode. They are documented together under PwC JOM Compatibility.

Administration¶

Every administrator operation is served by its own application mounted at /admin, with Swagger on /admin/docs and resource paths under /admin/api/v1. They validate AI_HUB_ADMIN_API_KEY directly. When that variable is absent or empty, MongoDB fallback requires isAdmin: true and is available only without DATABASE_URL; PostgreSQL mode rejects authentication. Isolating them keeps /main/docs free of privileged operations and makes the administrator surface auditable in one place. Its 50 operations are grouped under 12 Swagger categories:

The application owns the HTTP adapters only. Business behavior stays in the package that owns it, so an entity import still runs the entity workflow and a matching batch still runs the matching service. Consumer controls act on the single background task owned by the main application rather than starting a second one.

PostgreSQL user-skill maintenance returns a durable reconciliation jobId. The Entity Maintenance category also exposes a PostgreSQL-only status route with paginated progress and child inference counters. MongoDB keeps its historical synchronous launch behavior and does not expose that status route. PostgreSQL job diagnostics expose exact global, per-table and per-job-type status counts without modifying or retrying queued work.

The PostgreSQL Initialization category exposes one route for each entity family and a global route that sequences skills, users, opportunities, jobs and trainings. Its optional client_id targets a PostgreSQL setting.id; without it, every LIVE or DEMO setting is included. The returned durable run is complete when all eligible rows have been added to the child job queues, not when those long-running jobs have finished executing.

Chatbot / Oria¶

The Chatbot application is the public conversational surface around the LangGraph workflows.

Chat uses the main_graph. See agent orchestration.

On PostgreSQL, prompt suggestions select their five recent message pairs (or one conversation identifier) directly in SQL. History pagination uses a SQL count and a bounded page query, then applies the shared feedback overlay. These reads use the existing user/conversation history indexes, retaining tenant, visibility and cutoff filters without loading the complete history into Python.

Data Exchange¶

Data Exchange is the synchronization boundary between business systems and AI Hub. It retrieves users and imports or updates data used by matching and conversational features.

All resource paths start with /data_exchange/api/v1. The detailed contracts are available in /data_exchange/docs and in the API reference for users, opportunities and feedback.

Functional data flow¶

Source HR / talent system
        |
        v
Data Exchange validation and tenant resolution
        |
        +--> direct resource persistence
        |
        +--> standardization / processing workflow
                    |
                    v
          AI Hub operational collections
                    |
                    +--> matching
                    +--> Skills Library
                    └--> Oria agents

Data Exchange and the Main API therefore have different roles: Data Exchange manages its supported inbound resources, while the Main API performs AI processing, matching and administration on business entities.

MCP server¶

The MCP application exposes Streamable HTTP transport for MCP-compatible clients. It has no Swagger UI because its routes and schemas are owned by the MCP protocol.

Its current functional tools are:

The agent wrappers resolve the tenant and user from the authenticated request and enforce tenant agent availability. The opportunity wrapper returns text and structured opportunity data; the talent wrapper returns the specialist's text result.

Lexi¶

Lexi groups content-enrichment services used to build and maintain job and skills referentials.

Its package follows the same application boundaries as the other API surfaces: src/lexi/api owns HTTP adapters, src/lexi/schemas owns transport and workflow models, src/lexi/services owns business orchestration, and src/lexi/common contains Lexi-specific constants, errors and technical utilities.

See the Lexi functional documentation for input/output examples.

Shared runtime versus application ownership¶