1. Understand Marsad
Build the minimum system mental model needed for development.
Understand Marsad
Expected time: 15 minutes
Outcome: You can name the owner of a change and describe how asynchronous work crosses service boundaries.
Marsad is an Arabic social-media insights platform. Researchers use it to collect or upload data, run analysis, inspect analytics, and generate reports. Administrators manage datasets, access, and platform operations.
The Five Pieces to Remember
| Piece | Responsibility | Look here when… |
|---|---|---|
Web App (main/) | Browser UI, authentication, authorization, PostgreSQL/Prisma data, and server-side integration routes. | A page, user action, database record, or access rule changes. |
Model Server (model-server/) | Validates processing requests and implements analysis, collection, and report pipelines. | A model, collector, pipeline, or processing result changes. |
| Redis and RQ workers | Queue and execute long-running work outside HTTP requests. | A job is accepted but does not start or finish. |
Shared data (main/shared-data/) | Holds uploaded inputs and generated outputs visible to both services. | A worker cannot find a file or a result cannot be downloaded. |
| PostgreSQL | Stores Web App-owned users, datasets, files, jobs, and notifications. | UI state or job status is missing or incorrect. |
The browser communicates with the Web App. The Web App makes authenticated server-to-server calls to the Model Server; browser code must not call the private Model Server directly.
The Asynchronous Pattern
Most processing work follows the same shape:
- The Web App validates the user and creates or updates its job record.
- The Web App sends an authenticated request containing a stable job or file identifier.
- The Model Server validates the request and enqueues the work in Redis.
- The matching RQ worker reads or writes a relative
shared-data/path. - The notification worker calls the Web App back with the stable identifier and final state.
- The Web App persists the result and exposes it to the authorized user.
The System Architecture page gives the wider view. The Cross-Repository Contracts page is authoritative when you change an API payload, status, queue, shared path, or credential pairing.
Choose the Owner Before Editing
Use this quick test:
- If the change affects what a person sees or may do, begin in
main/. - If it affects how processing happens, begin in
model-server/. - If both services must agree, treat it as a contract change and plan compatible updates.
- If it only explains existing behavior, update
marsad-docs/and link to the owning reference page.
Checkpoint
Without looking above, explain to your onboarding partner what happens after the Web App accepts an analysis request. Include Redis, the worker, shared storage, the callback, and the stable job ID.
When that explanation is clear, choose Docker Compose or local processes without Docker.