PARALLAX

PARALLAX is a local, internet-independent distributed computing platform built for ENSPY (École Nationale Supérieure Polytechnique de Yaoundé). It federates the campus's underused, heterogeneous machines (old desktops, thin clients) into a local supercomputer: researchers upload annotated source code through a web portal, and the cluster handles decomposition into sub-tasks, distributed execution across worker nodes, fault detection/retries, and result collection.

How the pieces fit together

┌────────────────────────────────────────────────┐
│   PARALLAX Portal — React + Vite (Nginx)        │   web UI for researchers & admins
└──────────────────────┬───────────────────────────┘
                        │ HTTPS / JWT
                        ▼
┌────────────────────────────────────────────────┐
│   Backend API — Flask + Gunicorn                │   auth, project/task storage,
│   /api/auth  /api/tasks  /api/nodes              │   cluster supervision, internal
│   /api/programmes  /api/cluster                  │   API for the C cluster agents
└──────────────────────┬───────────────────────────┘
                        │ X-Cluster-Key (internal API)
                        ▼
┌────────────────────────────────────────────────┐
│   C cluster agents (run on the physical nodes)   │
│   Execution Master · Execution Workers           │
│   Receptionist · Controller · Parser             │
└────────────────────────────────────────────────┘

This repository contains both layers:

Directory	What it is	Language / stack
backend_ui_parallax/	REST API: auth, project uploads, task submission, cluster/node supervision, internal API consumed by the C agents	Python / Flask 3, SQLAlchemy, JWT
Parallax-Portal/	Web portal used by researchers (submit code, track progress, download results) and admins (supervise nodes/tasks)	React 19, Vite, Tailwind
Execution_Master/	Orchestrator that receives a submitted program, splits it into atomic tasks, and dispatches them to worker nodes	C
Execution_Worker/	Runs on each cluster node; executes the atomic tasks assigned by the master and reports results	C
Receptionnist/	Cluster-facing service that registers agents, receives heartbeats, and exposes a live view of nodes/logs (HTTP, port 9010)	C
Controller/	Tracks node/task state (heartbeats, metrics) on the master side	C
Agent_Init/	Bootstrap/init logic shared by the C agents (heartbeat, monitoring, networking)	C
Parser/	Parses/annotates submitted C source so it can be split into distributable tasks	C++
report/	Academic report / diagrams (LaTeX) describing the system design	LaTeX

The C components run directly on the cluster's physical/VM nodes (that's the whole point — they're what turns spare lab machines into compute nodes), so they are not part of the Docker setup below. The Docker Compose file only runs the two pieces that make sense as containerized services: the backend API and the frontend portal.

Two user roles

Role	Can do
chercheur (researcher)	Upload source code/archives, submit for execution, track sub-task progress in real time, download results
gestionnaire (admin)	Supervise all nodes (CPU/RAM, heartbeats, election score), view/cancel any program, put nodes in maintenance

Running it with Docker Compose

Prerequisites

• Docker and Docker Compose v2 (docker compose version)
• Git

1. Get the code

The backend and frontend live in their own repositories. Clone both into this project directory, using the exact folder names below — docker-compose.yml expects them at ./backend_ui_parallax and ./Parallax-Portal:

git clone https://github.com/PARALLAX-PROJECT/backend_ui_parallax.git backend_ui_parallax
git clone https://github.com/PARALLAX-PROJECT/Parallax-Portal.git Parallax-Portal

(Skip this step if you already have both cloned/checked out under those names, e.g. because you cloned this parent repository directly.)

2. Configure the backend environment

cd backend_ui_parallax
cp -n .env.example .env   # skips this if you already have a .env
# edit .env: set SECRET_KEY, JWT_SECRET_KEY, CLUSTER_INTERNAL_KEY to real random values,
# and MASTER_NODE_IP / BACKEND_CALLBACK_HOST to this machine's LAN IP if the C agents
# will run on other physical machines and need to reach this backend.
cd ..

The backend uses SQLite by default (DATABASE_URL=sqlite:///parallax.db), which is fine for local/dev use. For production, point DATABASE_URL at a PostgreSQL instance.

3. Build and start both services

From the repository root:

docker compose up -d --build

This builds and runs:

• parallax-backend — Flask API on http://localhost:5000 (Swagger docs at http://localhost:5000/api/docs/)
• parallax-frontend — the React portal, built and served via Nginx, on http://localhost:8080

The backend's SQLite database (backend_ui_parallax/instance/) and uploaded project files (named volume parallax_storage) persist across restarts.

3. Open the app

Visit http://localhost:8080, register an account, and log in.

Useful commands

docker compose logs -f              # follow logs from both services
docker compose ps                   # check container/health status
docker compose down                 # stop and remove containers (keeps volumes)
docker compose down -v              # also remove the storage volume

Pointing the frontend at a different backend

The frontend bakes VITE_API_URL into its static build at build time (Vite/React apps can't read environment variables at runtime). If the backend is reachable at a different host/port (e.g. deploying frontend and backend on separate machines), edit the args.VITE_API_URL value for parallax-frontend in docker-compose.yml and rebuild:

docker compose up -d --build parallax-frontend

Running without Docker (local development)

Backend:

cd backend_ui_parallax
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env   # edit as needed
flask db upgrade
python run.py          # http://localhost:5000

Frontend:

cd Parallax-Portal
npm install
cp .env.example .env.local   # set VITE_API_URL=http://localhost:5000
npm run dev            # http://localhost:5173

See backend_ui_parallax/README.md and Parallax-Portal/README.md for full details on each service (API endpoints, project structure, security model), and backend_ui_parallax/workflow.md for the end-to-end frontend↔backend integration workflow.

Building/running the C cluster agents

The Execution Master, Execution Worker, Receptionist and Controller are meant to run directly on the physical/VM machines that make up the cluster (not in Docker). See report/ for the full system architecture and design rationale.

1. Agent (Master / Controller / Worker)

Every cluster node — whether it acts as master, controller, or worker — runs the same parallax_agent binary. Which role it plays is decided by parallax/parallax.conf:

role=Master
interface=wlp3s0

• role — one of Master, Controller, or Worker (case-sensitive). Set this to whichever role the current machine should play.
• interface — the network interface the agent should bind to (e.g. eth0, wlp3s0).

Build and run from the repository root (the binary reads ./parallax/parallax.conf and ./parallax/parallax_uuid.dat as relative paths, so it must be launched from there):

make                # builds ./parallax_agent (and the Parser tool it depends on)
./parallax_agent

The agent watches parallax.conf for changes and hot-reloads the role without needing a restart — edit role= and save to switch a node from Worker to Controller/Master on the fly.

2. Receptionist

The Receptionist is the cluster-facing HTTP gateway (port 9010): it accepts submitted programs, forwards them to the master, and exposes a live view of nodes/logs that the backend proxies to the frontend. Build and run it from the Receptionnist/ folder:

cd Receptionnist
make
./receptionist
cd ..

3. Point the backend/frontend at the Receptionist

Once the Receptionist is running somewhere on the LAN, tell the backend how to reach it — either at startup via .env:

# backend_ui_parallax/.env
RECEPTIONIST_IP=192.168.1.100
RECEPTIONIST_HTTP_PORT=9010

or live, without restarting the backend, from the frontend itself: log in as a gestionnaire, and use the Receptionist widget in the sidebar (ReceptionistConfigWidget) to set/update its IP and port (PUT /api/nodes/receptionist-config). This is the easiest way to repoint the cluster connection when the Receptionist's machine gets a new DHCP address, without touching .env or rebuilding anything.