Mutaqamil ERP Documentation — ZATCA E-Invoicing

Overview

Mutaqamil ERP is a lightweight ERP covering Chart of Accounts, Product & Master Data, Multi-Warehouse Inventory, and Sales & Invoicing, built against a written product spec and flowchart. It runs on Laravel 12 with Filament 3 as the admin panel, fully dockerized for local development.

This documentation describes the product's own development environment and architecture. Mutaqamil ERP is in active development and not yet publicly available — see the product page for status.

Stack

Layer	Technology
Backend	Laravel 12, PHP 8.3
Admin UI	Filament 3 (Livewire-based), built-in RTL support for Arabic
Database	MySQL 8.4
Cache / Queue / Sessions	Redis
RBAC	spatie/laravel-permission
API	Laravel Sanctum, versioned under /api/v1, OpenAPI/Swagger docs
Containerization	Docker Desktop, docker-compose

ZATCA E-Invoicing (Saudi Arabia)

Saudi Arabia's ZATCA ("Fatoora") e-invoicing regulation rolls out in two phases, and Mutaqamil ERP is being built to both:

Phase	What it requires	Status in this app
Regulatory Phase 1 — Generation	QR-coded invoices, generated entirely offline, no ZATCA API call	Shipped
Regulatory Phase 2 — Integration	Cryptographically signed UBL XML, submitted to ZATCA for clearance (B2B) or reporting (B2C)	In progress

Within Phase 2, the offline pieces are done: ZatcaXmlBuilder generates structurally-complete UBL 2.1 XML for a posted Sales Invoice or Return, ZatcaHasher canonicalizes and hashes it to ZATCA's own conventions, ZatcaCsrGenerator produces a local keypair and CSR, and ZatcaSigner produces the ECDSA signature and full XAdES cryptographic stamp plus QR code.

A real document produced by this code — signed with a self-signed test certificate — has been validated end-to-end against ZATCA's own Compliance & Enablement Toolbox SDK (v3.0.8, downloaded directly from ZATCA's developer portal): its XSD schema, EN16931 core rules, and KSA-specific business rules (including the XAdES signature block's own rules) all pass. The only remaining failure is the SDK's separate certificate-trust-chain check, which needs a certificate ZATCA itself issues — that requires live Compliance API onboarding with a real taxpayer account, not a code fix.

ZatcaApiClient (the Compliance/Production CSID exchange over HTTP) is also built. Still missing before Phase 2 is complete: the compliance-check invoice-submission step, a Filament onboarding page tying CSR generation and credential storage together, and Phase 3 (the queued submission job, invoice-counter/hash-chain sequencing, and retry handling for production traffic).

ZATCA e-invoicing is optional per client and off by default — most of this app's client base isn't Saudi-registered and never touches this code path at all. Credential material (CSIDs, secrets, the signing private key) is encrypted at rest rather than stored as plain config, reflecting that it's a legally-binding signing identity, not just an API key.

Domain Model

The Chart of Accounts module is built around Account, JournalEntry and JournalEntryLine — a proper double-entry structure, not a flat transaction log. Product & master data, multi-warehouse inventory, and sales & invoicing build on top of that same accounting core, so a sale posts real journal entries rather than just decrementing a stock number.

Chart of Accounts — five account types, double-entry journal lines
Product & Master Data — the shared catalog every other module references
Multi-Warehouse Inventory — stock tracked per warehouse, not globally
Sales & Invoicing — the customer-facing workflow that ties it together

Roles & Permissions

Role-based access control uses spatie/laravel-permission, with four roles scoped to what each one should touch:

Admin — full access
Sales — customers, sales orders, invoicing
Warehouse — inventory, stock movements
Accounting — chart of accounts, journal entries, reporting

API

A REST API is versioned under /api/v1 and authenticated with Laravel Sanctum token auth — laid down as the foundation for a future POS or e-commerce integration rather than built for its own sake. It's fully documented via OpenAPI/Swagger, served locally at:

http://localhost:8080/api/documentation

Local Setup

The project is fully dockerized. After installing Docker Desktop (with WSL2 on Windows) and copying the environment file:

cp .env.example .env
make init

make init builds the images, then bootstraps a fresh Laravel install and overlays the ERP-specific application code (models, migrations, services, Filament resources, seeders) on top of it, runs migrations and seeders, and builds frontend assets.

URL	What
http://localhost:8080/admin	Filament admin panel
http://localhost:8080/api/documentation	Swagger UI
http://localhost:8081	phpMyAdmin
http://localhost:8025	Mailpit (catches outgoing local email)

These are development-only credentials and ports from the project's local Docker setup — they describe how the product is built, not a live environment you can access from this website.

Day-to-day commands: make up, make down, make artisan cmd="migrate:status", make shell, make frontend-dev, make test.

Status & Roadmap

The Docker-based development environment is confirmed working end-to-end (login, dashboard and seeded data verified in-browser). ZATCA e-invoicing Phase 1 is shipped and Phase 2's offline signing has passed ZATCA's own SDK validation, with live onboarding and production submission remaining. Mutaqamil ERP as a whole is in active development and has not launched publicly — see the product page for what's built today, or contact us to be notified at launch.

Mutaqamil ERP