Integration Boundaries
The model server's responsibilities at web-app, storage, and queue boundaries.
Integration Boundaries
The Model Server receives trusted processing requests from the Web App, uses shared storage for inputs and generated files, and runs asynchronous work through Redis-backed workers. It is an internal service boundary: browser clients must interact with the Web App, not directly with the Model Server.
The canonical paths, payload fields, response semantics, statuses, and credentials are defined in Cross-Repository Contracts. This page explains how the Model Server must uphold those agreements.
Web App Request Boundary
| Incoming work | Model Server responsibility | Do not do |
|---|---|---|
| Analysis batch | Authenticate, validate each job, reject invalid input with the documented error, and enqueue accepted jobs idempotently. | Change a Web App job record or silently accept an inaccessible file. |
| Platform collection | Validate the platform-specific request and retain the supplied Web App job ID for output and callbacks. | Create the Web App's collection record or use a new unrelated identifier. |
| Analytics and reports | Verify the supported operation, file metadata/path inputs, and report options before enqueueing. | Generate reports inline in the request handler or expose an output path to a browser. |
Requests are server-to-server JSON calls to MODEL_API_URL, including /api. A successful enqueue means the Model Server accepted responsibility for asynchronous execution; it does not mean the result is complete.
Callback Boundary
Workers must enqueue status delivery on notifications. The notification worker calls the relevant Web App callback route using MAIN_APP_API_BASE_URL and MAIN_APP_API_KEY. Send only the documented payload for the job type, correlate messages with stable job IDs, and redact errors in logs.
Callbacks may be retried or delivered more than once as failure handling improves. Pipeline code and callback helpers must therefore tolerate duplicate terminal and progress delivery. The Model Server must never bypass this boundary by connecting to the Web App database.
Queue Boundary
Redis is a Model Server runtime dependency. The API chooses the appropriate queue; the Web App does not enqueue RQ work directly. Keep execution work separate from notification delivery so callback outages can be diagnosed and recovered without replaying provider or collector work.
See Queue Ownership for the currently supported queues, job statuses, timeout, and retry behavior. Do not create a new queue or repurpose an existing one without updating Compose, worker deployment, monitoring, and the shared contract.
Shared-Storage Boundary
The Web App owns uploaded-file records and user access decisions. The Model Server may read the accepted relative input path and write repository-owned outputs only below the established shared-data directories. In particular:
- resolve paths relative to the configured shared-data root;
- reject absolute paths and paths that escape that root;
- preserve forward-slash
shared-data/paths in exchanges with other services; - use the Web App job ID or file meta ID where the storage convention requires it; and
- avoid deleting shared files without an agreed retention policy and reference check.
See Shared Storage for the authoritative locations and lifecycle rules.
Cross-Repository Change Procedure
- Identify whether the change affects a request, response, callback, status, queue, generated path, or credential.
- Update the canonical System contract and make the Model Server accept both old and new compatible forms where a deployment overlap is possible.
- Review and update the Web App consumer in the same change set.
- Deploy both sides, exercise the full request-to-callback path, then remove the old form only after consumers have migrated.