Architecture
Responsibilities and major technical areas of the model-server repository.
Model Server Architecture
The Model Server owns asynchronous processing. It accepts trusted server-to-server requests from the Web App, validates and queues repository-owned work, runs that work in RQ workers, writes generated artifacts to the shared-data mount, and sends status updates back through the notification queue.
It does not own browser traffic, Web App database records, user-facing job state, or authorization to download a result. Those responsibilities remain with the Web App. End-to-end behavior and shared agreements are documented in System Architecture and Cross-Repository Contracts.
Major Components
The Flask API is the synchronous boundary: it authenticates the calling service, validates a request, rejects invalid work without creating a background job, and returns once the work has been accepted for execution. Workers perform provider calls, collection, report generation, file writes, and callback delivery outside the HTTP request lifecycle.
Ownership Map
| Area | Model Server responsibility | Boundary to preserve |
|---|---|---|
| Request API | Validate trusted Web App requests and enqueue accepted work. | Do not accept browser-originated work or let a request write Web App records. |
| Analysis | Select the requested supported processor and produce per-job output. | Gateway/model semantics and payload fields are a shared contract. |
| Collection | Run platform-specific collectors and write the resulting CSV. | The Web App creates the collection record and publishes a usable result. |
| Analytics and reports | Read an authorized shared input and create generated artifacts. | The Web App owns access control and download presentation. |
| Workers | Execute RQ jobs, isolate failures, and schedule callback delivery. | Redis is the broker; Web App code never enqueues these jobs directly. |
| Callback delivery | Send redacted, stable status updates to the Web App through notifications. | Never write to the Web App database directly. |
| Provider credentials | Use provider secrets only for the requested work and keep them out of logs and output. | Do not persist or expose user-supplied provider keys. |
Repository Boundaries
Keep the repository organized around these technical responsibilities, even if implementation folders evolve:
- Flask blueprints expose request-specific validation and enqueue behavior.
- Pipeline and processor code owns analysis, collection, analytics, and report execution.
- Queue setup and worker entry points own worker selection, timeouts, and failure handling.
- Provider and platform adapters isolate external API details from pipeline orchestration.
- Shared-storage helpers resolve only approved, relative paths under
shared-data/. - Callback helpers centralize authenticated delivery, redaction, and error logging.
Architecture Change Rules
Treat a change as cross-repository when it modifies an HTTP route, payload, callback, job status, queue, shared-data path, service credential, or generated-file location. Make a compatible change first, update the canonical system contract, deploy both consumers, and only then remove the previous behavior.
Service-only refactors may change internal module layout or implementation details without changing this contract. Preserve the request validation, queue ownership, relative-path, and callback boundaries while doing so.