ComplyKSA Documentation — GOSI & Qiwa Integration

Overview

ComplyKSA is a multi-tenant SaaS for Saudi HR & payroll compliance — GOSI (social insurance), Qiwa (labor market platform) and Mudad (wage protection) — designed to be sellable standalone or as a cross-sell add-on to an existing ERP.

ComplyKSA is genuinely early-stage. This page describes exactly what's built today versus what's only specified — read the Status section before assuming a feature exists.

Stack

Layer	Technology
Backend	Laravel, PHP 8.3+, Sanctum (SPA cookie auth), SQLite for local dev
Frontend	React, Vite, TypeScript, Tailwind v4
HTTP client	axios, react-router-dom

Architecture

The multi-tenant foundation is built first, on purpose: tenants, establishments and users (with a tenant_id and role on each user) plus an integration_credentials table for per-tenant government API credentials. A shared API response envelope (App\Http\ApiResponds) is used consistently by both the driver layer and the HTTP controllers, so every endpoint returns data in the same shape.

GOSI & Qiwa Integration

The two systems every Saudi employer answers to — GOSI and Qiwa — plus Mudad for wage protection, are each modeled as their own interface: GosiApiInterface, QiwaApiInterface, MudadApiInterface. All three have a mock driver returning fixture data today, so the app is fully demoable without live government credentials. All three drivers swap at once via a single environment variable:

KSA_API_DRIVER=mock   # or: live

The wiring lives in app/Providers/KsaIntegrationServiceProvider.php. This means the rest of the application — controllers, frontend, tests — is written against the interface, not the mock, so switching to real GOSI/Qiwa/Mudad credentials later doesn't require touching application code.

Local Setup

Backend (served at http://127.0.0.1:8000):

cd backend
composer install
cp .env.example .env   # already has KSA_API_DRIVER=mock
php artisan key:generate
php artisan migrate
php artisan serve

Frontend (served at http://localhost:5173):

cd frontend
npm install
cp .env.example .env
npm run dev

Opening the frontend calls the backend's /api/health endpoint and shows the mock GOSI/Qiwa/Mudad driver status — confirming the two apps are wired together correctly.

Status & Roadmap

What's built so far (Epic A + Epic B):

Multi-tenant data model — tenants, establishments, users with role scoping
GOSI/Qiwa/Mudad driver interfaces with a working mock mode
Shared API response envelope
SPA cookie authentication, CORS configured for the local frontend

What's specified in detail but not yet built (Epic C onward):

Employee/salary CRUD
GOSI contribution calculations
Qiwa/Nitaqat compliance tracking
Payroll/WPS (wage protection system) processing
An AI layer for compliance guidance
Employee self-service (ESS) portal
The ERP integration/packaging layer

See the product page for a summary, or contact us to be notified as modules ship.

ComplyKSA