Integration Boundaries
The web app's responsibilities at the model-server, storage, and queue boundaries.
Integration Boundaries
The Web App is the boundary between browser workflows and Marsad's asynchronous processing system. It creates and tracks application records, initiates Model Server work, receives status callbacks, and presents authorized results and downloads to users.
Model Server Requests
The Web App calls MODEL_API_URL, including the /api prefix, with JSON over a server-side connection. It must validate browser input, create the relevant database record, and send a request that contains the stable Web App job or file ID. It marks a job enqueued only when the Model Server accepts the request.
| Boundary | Web App sends | Web App retains |
|---|---|---|
| Analysis batch | One or more jobs with a Web App job_id, selected analysis/model/gateway, relative file path, text column, language, record range, and batch size. | AnalysisJob lifecycle and user-visible progress. |
| Platform collection | A platform-specific request plus job_id, dataset name, and a route identifier composed from the user and job IDs. | DataCollectionJob lifecycle and the resulting Dataset/FileMeta record. |
| Analytics | file_meta_id, relative file path, and optional date filters. | File authorization and the rendered analytics experience. |
| Report generation | File information, output filename, and a section choice from 1 to 6. | Report history, authorized download, and completion notification. |
Request validation failures are not background jobs. Preserve the Model Server's response semantics and show a clear application error instead of marking work as queued. See HTTP Endpoints for exact paths, fields, and known response variations.
Callbacks and Notifications
Workers never write the Web App database directly. A notification worker sends callbacks through Web App API routes; the Web App validates the payload, persists the state transition, and notifies the user when appropriate.
Callback handlers must be idempotent because an interrupted delivery can be retried. Use the stable job or file ID, tolerate a repeated status update, and prevent duplicate emails or duplicate publication of a collected dataset. Preserve processing counts and user-safe messages for analysis jobs.
The documented callbacks cover analysis providers, collection jobs, and report completion. Consult the callback table before adding or changing any callback.
Queue Boundary
Redis is the Model Server's broker; the Web App does not enqueue RQ work directly. Its responsibility is to persist the application request and call the Model Server API. The Model Server selects tasks, data_collection_tasks, or notifications as needed.
Do not make the browser depend on a queue ID as the source of truth. The Web App job record is the canonical status for user interfaces. It must tolerate a delay between enqueue acceptance, worker execution, and callback delivery.
Shared Storage and Downloads
The shared-data directory is a file boundary, not a public download directory. The Web App writes uploads and reads outputs through contract-defined relative paths; workers write collected data and generated outputs in their designated locations.
Before serving any file, the Web App must verify that the signed-in user is allowed to access the associated dataset or FileMeta. It must constrain report downloads to the file-specific report directory and validate the requested filename. Filename sanitization is necessary but does not replace resource authorization.
See Shared Storage for approved locations and the cleanup rules.
Change Rules
Treat a change as cross-repository when it changes an HTTP path, payload field, callback, status, queue behavior, shared-file path, service URL, or credential. Make compatible changes first, deploy both sides, and only then remove the previous behavior. Update the System contract and review the Model Server implementation in the same change.