New Developer Onboarding
A guided path from a new checkout to your first reviewed Marsad change.
New Developer Onboarding
Welcome to Marsad. This tutorial gives you a practical route through the system: build a useful mental model, run the stack, create small Next.js and Flask routes, connect them through a queued image job, follow one production request, make a safe change, and prepare your first pull request.
Expected time: Half a day for orientation, plus any time needed to obtain credentials or build the model image.
You will finish with: A working development environment and a small, validated change ready for review.
Before You Start
Ask your onboarding partner to confirm that you have:
- access to the Marsad repository and your team's issue tracker;
- Docker 24 or newer with Docker Compose, or the approved local toolchain;
- a development environment file for each service you need to run;
- access to a safe development account and non-sensitive test data; and
- a small starter issue with a named reviewer.
Never copy production secrets, customer data, or production database settings into your local environment. If a required value is missing, ask the value's owner instead of inventing or committing one.
The Onboarding Path
1. Understand Marsad
Learn the five pieces involved in most requests.
2A. Run with Docker
Start the integrated development stack with Docker Compose.
2B. Run Without Docker
Start the databases, Web App, Model Server, and workers as local processes.
3A. Build Hello Marsad
Create and verify your first Next.js App Router page.
3B. Build Hello Model Server
Create and test your first Flask blueprint and JSON endpoint.
3C. Integrate a Hello Image Job
Connect both services through Redis, an RQ worker, and a generated PNG.
4. Trace a Workflow
Follow an analysis request from the browser to its result.
5. Make a Small Change
Practice the repository workflow on a low-risk issue.
6. Test and Debug
Validate your change and diagnose common local failures.
7. Open Your First PR
Prepare a reviewable change and hand it to a teammate.
How to Use This Tutorial
Follow the pages in order the first time. Each page ends with a checkpoint that tells you when to continue. The tutorial deliberately stays on the shortest useful path; linked Product, System, Web App, and Model Server pages are reference material you can return to when you need more detail.
Onboarding Is Complete When
- you can explain which service owns browser behavior, jobs, queues, and generated files;
- the local Web App loads and its required supporting services are healthy;
- you can create and verify a small Next.js App Router page;
- you can create and test a small Flask blueprint without unrelated infrastructure;
- you can follow a tutorial job from the browser through both services and an RQ worker;
- you can trace one job using its stable ID without exposing secrets;
- your starter change passes the checks required by its repository; and
- you have opened a focused pull request with evidence of validation.