A Multi-Brand Waybill & Invoice Document System - Bolisa

Overview

This application was developed to provide a modern and efficient experience for managing internal shipping policy documents (waybills and air freight bills of lading), with a strong emphasis on branding flexibility, strict data integrity, and role-based operational compliance. The application, named Bolisa (بوليصة), was designed to automate and standardize the process of creating, validating, storing, and exporting shipping policies across different divisions while eliminating the operational friction of manual tracking.

The system follows a "Single-Codebase, Dual-Deployment" architecture, where three distinct platforms—Bolisa - Logistic (بوليصة - لوجستيك) and Bolisa - Cargo (بوليصة - كارجو) run from the exact same frontend repository. By utilizing runtime configuration variables, each deployment automatically renders its own branding, connects to its isolated database backend, and gates specialized features without code branching or separate codebases.

The Challenge

Managing shipping waybills across multiple service divisions traditionally introduces substantial maintenance overhead and operational risks. Prior to the project, the primary challenges included:

• Codebase fragmentation and branching to maintain separate branding, logo assets, database connections, and operational logic for the Logistic and Cargo divisions.
• Complex billing differences, where Cargo required specialized, multi-item tax invoices matching official Excel templates, while Logistic used standard land freight waybills.
• High risk of data exposure for public share links, which are accessed by anonymous viewers via QR codes.
• Human errors in manually typing waybill numbers, which led to duplicates, gaps, and validation inconsistencies.
• Correctly rendering complex Arabic scripts (RTL layout) in generated PDF documents, where standard PDF libraries frequently truncate text, break ligatures, or fail to correctly space character strings.

The Solution

The application was designed as a unified, dual-tenant single-page application built on a modern frontend stack linked directly to Supabase. This architecture delivers a secure, lightning-fast, and responsive user experience optimized for both desktops and mobile devices.

The system enables users to:

• Dynamically create, edit, duplicate, and manage shipping policies with instant validation.
• Switch between Bolisa Logistic and Bolisa Cargo configurations purely via environment variables.
• Auto-generate sequential, gap-free, unique policy numbers tailored to the city and policy type.
• Preview documents on-screen using a high-fidelity rendering pipeline before exporting them.
• Securely share published policies via public QR code URLs that enforce strict database-level column-level access controls.
• Maintain full audit trails of document revisions and user operations.

Policy Management & Lifecycle

Instead of relying on unorganized logs, Bolisa features a robust state-driven workflow for handling waybills and air policies.

Core capabilities include:

• Bilingual City Prefixes: Selection of origin cities (Riyadh, Jeddah, Dammam) that automatically generate corresponding human-readable numbers like Ri000001 or Je000042 via PostgreSQL Atomic Counters.
• Air Freight Lifecycle (Cargo Only): Cargo deployments activate a dedicated air policy path to generate standard tax invoices (فاتورة ضريبية), featuring customizable tables of 11 charge codes, MAWB numbers, pieces, and weight calculations.
• Draft and Publish States: Policies are created as drafts (with no issued policy number or content hash), allowing operators to edit details before finalizing them.
• Duplicate Prevention: Upon publishing, the system builds a canonical JSON of all editable fields and computes a SHA-256 hash. The database enforces uniqueness on this hash, blocking operators from publishing identical business documents.
• Administrative Trash & Soft Delete: Operations use a soft-delete mechanism (deleted_at), ensuring that data is never hard-deleted accidentally, and allows administrators to easily restore policies.

Security & Access Control

Bolisa is built around a privacy-first, secure-by-default architecture that ensures strict data isolation and prevents unauthorized document access.

Key security features include:

• Row-Level Security (RLS): Enforced directly in PostgreSQL, ensuring that data-access rules cannot be bypassed even if a client-side route is modified.
• Role-Based Access Control (RBAC): Distinguishes between admin and user accounts. Administrators have access to a dedicated Control Panel for managing users, updating roles, and activating or deactivating profiles.
• Granular Viewing Scopes: Non-admin users can be configured by admins to have a policies_scope of either own (viewing only the waybills they created) or all (viewing all waybills in the deployment).
• Public Policy Viewer Hardening: Public-facing URLs (/p/<uuid>) fetch documents using column-level database permissions. This limits PostgreSQL from returning sensitive operational fields, hashes, or user IDs to anonymous clients.

Bilingual PDFs & Dynamic Branding

Despite running on a unified codebase, Bolisa delivers high-fidelity, customized branding assets and professional exports for both platforms.

Key features include:

• Dynamic Asset Injection: Brand logos and signature stamps are stored in isolated Supabase storage buckets. They are loaded dynamically based on the active Supabase URL, allowing branding updates without rebuilding or deploying the frontend.
• Arabic Ligature Rendering Fix: A custom, slot-based deduplication patch was applied. This prevents the PDF layout engine from dropping repeated character sequences and guarantees perfect typography.
• Gated Stamp Delivery: Physical signature stamps are stored in a private bucket. A secure Supabase Edge Function verifies that a policy is published before streaming the stamp PNG, preventing anonymous users from extracting clean stamp images.
• Responsive RTL Interface: The entire system is built in Arabic with full RTL styling, providing a native look and feel on both desktop screens and mobile preview devices.

Technology & Architecture

The system utilizes a modern, highly optimized technology stack designed for performance, correctness, and developer productivity:

Core technologies include:

• React (v19) & TypeScript (v5.6): The frontend is written under a strict type-safety configuration, ensuring code quality and preventing runtime errors.
• Tailwind CSS (v3.4): Used for responsive UI styling configured with native RTL text support.
• Zustand & TanStack Query (v5): Zustand handles lightweight client-side state (such as auth sessions), while TanStack Query manages caching, automatic refetching, and backend synchronization.
• React Hook Form & Zod: Form validation is bound directly to Zod schemas to ensure inputs conform to schema types before submission.
• Supabase Backend: Provides user authentication, PostgreSQL 15, private and public storage buckets, and Edge Functions.
• @react-pdf/renderer (v4.5): Generates high-fidelity PDF exports directly in the browser.
• Vitest & SQL RLS Matrix Tests: Combined unit tests and database tests to verify security boundaries and atomic counting.

Value Delivered

Bolisa delivers a comprehensive document management system that balances multi-brand flexibility, strict data security, and operational simplicity:

Key advantages include:

• Zero Code Branching: One repository serves both Bolisa Logistic and Bolisa Cargo, dramatically reducing code maintenance and hosting costs.
• Error-Free Policy Numbering: Sequential, gap-free numbering prevents administrative auditing conflicts.
• Strict Data Security: RLS and column-level grants protect company and client secrets from unauthorized scanning.
• Bespoke Arabic PDF Engine: Patched text layout ensures perfect Arabic invoicing exports.
• Role-Based Control: Admin control tools allow simple, direct management of user access scopes.

Conclusion

The Bolisa application represents a powerful, production-grade solution for shipping policy management, combining branding flexibility, data protection, and a refined Arabic user experience. By replacing fragmented workflows and branched codebases with a modern, single-codebase dual-deployment architecture. The app ensures absolute control over policy numbering, data security, and PDF generation, optimizing daily logistics workflows across all business divisions.