Architecture
Responsibilities and major technical areas of the main web application.
Web App Architecture
The main/ repository is Marsad's Next.js and TypeScript application. It owns the user and administrator experience, authentication, PostgreSQL records accessed through Prisma, uploads and downloads, user-visible job state, notifications, and requests to the Model Server.
This page records the verified ownership boundary. The main/ repository remains the source of truth for its route tree, Prisma schema, and implementation details. Keep end-to-end service behavior in System Architecture and shared request shapes in Cross-Repository Contracts.
Responsibilities and Module Ownership
| Area | Web App responsibility | Related system boundary |
|---|---|---|
| User and administration UI | Render workflows for datasets, collection, analysis, analytics, reports, and public-dataset administration. | Product behavior belongs in Product. |
| Authentication and authorization | Identify the signed-in user and authorize access to the requested dataset, file, job, or administration action. | See Security Boundaries. |
| API routes | Validate browser input, create or update application records, call the Model Server, and serve authorized results. | The Model Server's HTTP APIs are a shared contract. |
| Data access | Own Prisma-backed PostgreSQL records and their user-visible state. | The Model Server never writes the Web App database directly. |
| Files | Accept uploads, associate them with application records, and provide authorized downloads. | Input and generated files use the shared-data contract. |
| Job tracking | Create pending jobs, mark accepted work enqueued, persist callbacks, and notify users. | Redis and workers belong to the Model Server runtime. |
C4 Level 3 — Web App Components
The diagram shows logical Web App components, not a required folder structure. Keep authentication, authorization, service credentials, Model Server calls, and shared-file access on the server-side boundary; the browser should interact only with pages and authorized Web App APIs.
Request and Route Ownership
The browser talks to the Web App over HTTPS. The Web App is the only service that should turn browser actions into database changes or access to shared files. It then calls the Model Server over its server-side API.
The following endpoint families have a Web App ownership role:
| Workflow | Web App route responsibility | Model Server interaction |
|---|---|---|
| Analysis | Create AnalysisJob records as pending; send accepted jobs for batch enqueue; persist progress and completion callbacks. | POST /api/analyze/enqueue-batch and provider-specific callback routes. |
| Data collection | Create DataCollectionJob records; initiate a platform collection; publish the resulting dataset when it is usable. | Platform collection routes and PATCH /api/data-collection/jobs/{jobId} callback. |
| Analytics and reports | Validate the target file, request analytics or report generation, list permitted report versions, and download permitted PDFs. | Analytics/report APIs and the report-generation callback. |
| Dataset files | Validate uploaded data, create the dataset/file metadata records, and enforce access checks before serving a file. | Read and write only contract-compliant shared-data paths. |
Do not expose Model Server credentials, provider credentials, or shared-file paths to browser code. Browser-facing handlers should return an application-safe error and log the technical failure without sensitive payloads.
Persistent Data and Files
The Web App owns the persistent records that connect a person to their data and job history. The current system contracts refer to these key records:
| Record | Web App purpose |
|---|---|
Dataset | A user-owned or public dataset available for product workflows. |
FileMeta | Metadata and relative shared-data location for a dataset file and its generated reports. |
AnalysisJob | Requested analysis, its state, progress counts, messages, and results. |
DataCollectionJob | Requested platform collection, its state, totals, and published result. |
Files are not database payloads. Store and exchange paths relative to the service root with forward slashes, beginning with shared-data/. The Web App owns upload cleanup when a dataset create or update fails. It must not delete a file that is referenced by a record or active job. See Shared Storage for the canonical paths and lifecycle rules.
See Domain Model for the core Prisma relationships, logical references, and ownership invariants.
Authentication and Authorization
Authentication alone is not sufficient for a data operation. Every route that reads, changes, or downloads a dataset, file, job, or report must establish both:
- Identity: the request comes from a signed-in user or an authenticated internal service.
- Authorization: that identity owns the resource, has an explicit grant, or is permitted by the resource's public/admin policy.
In particular, report downloads must check ownership or public access for the target FileMeta; a sanitized filename only prevents path traversal. Internal Model Server callbacks must use a separate, server-only service credential. The current integration documentation notes that callback-token validation still needs to be implemented; keep callback routes private-network-only until it returns 401 for invalid credentials.
Job State Lifecycle
The Web App is authoritative for the state users see. It creates a job as pending, changes it to enqueued only after the Model Server accepts the request, and persists callbacks as work progresses. Shared values are pending, enqueued, started, failed, completed, and checkpointed; checkpointed denotes a usable partial collection result.
Workers may retry or deliver a callback more than once. Callback handlers must therefore be idempotent: use the job ID, tolerate duplicate status updates, and avoid repeating completion notifications or dataset publication. The detailed flows are Analysis Job Flow, Data Collection Flow, and Report Generation Flow.
The Web App's persisted notifications, Pusher refresh events, completion emails, and current delivery limitations are documented in Notification Architecture.