business-setup

byMeem Kollection

Build a production-ready multi-role B2B/B2C service platform for a UAE-based government-approved business setup and visa services company. The platform must be managed from a SINGLE ADMIN DASHBOARD and support three distinct user types: B2B Partners, B2C Direct Customers, and Commission-Based Agents. All services originate from UAE Freezone authorities (government-approved licenses). CORE BUSINESS CONTEXT: We are a service-based industry offering business setup, visa services, and other government-related services. We have multiple service categories and operate across multiple regions globally. The platform must handle B2B licensing where we officially issue UAE Freezone-approved licenses directly to B2B partners. USER ROLES & PERMISSIONS: 1. Super Admin (Single control center): Manage all B2B partners, B2C customers, agents, services, pricing, commissions, approvals, announcements, inbox, media, and system settings. 2. B2B Partners: Apply for Freezone licenses, manage their sub-accounts, view billing, access services at B2B rates, receive official documents. 3. B2C Direct Customers: Browse services, place orders, make payments, track status, receive invoices. 4. Commission Agents: Refer clients (B2B or B2C), track their referred users, view earned commissions, request payouts. Commission logic must be automated and recorded. KEY FUNCTIONAL REQUIREMENTS: - Admin Dashboard: Full control over users, service catalog, pricing (multi-currency), approvals, announcements, inbox/messaging, media management, and new service addition. - Approval Workflow: All B2B license applications, agent commission payouts, and critical actions require admin approval. Email notifications must be sent automatically on registration, approval, rejection, and new announcements. - Financial Ledger: Complete accounting module to track all payments from B2B, B2C, and agent commission calculations. Every transaction must be recorded with user role, service, amount, currency, and status. - Multi-Currency Support: Primary operating currency AED. Also support USD and PKR for display and payment processing. Exchange logic must be configurable by admin. - Subscription & VIP Tier: Implement a paid subscription model. Certain premium/limited services must be locked behind subscription or VIP status for serious business clients. Admin can manually grant VIP access. - Service Catalog: Categorized services (Business Setup, Visa Services, Government Services, etc.). Each service has B2B price, B2C price, and agent commission rate. - Inbox & Notifications: Internal messaging between admin and users. Automated email system for approvals, announcements, and new service alerts. - Multi-Region Display: Services and pricing can be filtered by region (e.g., Dubai, Abu Dhabi, Sharjah, or international regions). DESIGN & TECH EXPECTATIONS: Build a clean, premium, trustworthy SaaS interface suitable for a government-licensed service provider. Must be fully responsive. Use modern SaaS design patterns (similar to Stripe Dashboard, Linear, or Notion). The admin panel must be powerful but intuitive, allowing one person to manage the entire platform efficiently. Generate: Complete database schema (users, roles, services, orders, transactions, commissions, subscriptions, announcements, messages), backend APIs, frontend pages (admin dashboard + B2B portal + B2C portal + agent portal), authentication with role-based access control, payment tracking, and email notification logic.

No preview

Comments (0)

No comments yet. Be the first!

System Requirements

System Requirements Document for UAE Business Setup

1. Introduction

UAE Business Setup is a production-ready, multi-role B2B/B2C service platform for a UAE-based, government-approved business setup and visa services company. The company is a service business offering business setup, visa services and other government-related services across multiple service categories and multiple regions globally. All services originate from UAE Freezone authorities under government-approved licenses, and the company officially issues UAE Freezone-approved licenses directly to B2B partners.

The platform is managed from a single admin dashboard by one Super Admin and serves three distinct user types: B2B Partners, B2C Direct Customers and Commission-Based Agents. It must feel official, orderly and warm — a clean, premium, trustworthy SaaS interface suitable for a government-licensed service provider, fully responsive, using modern SaaS design patterns (in the spirit of Stripe Dashboard, Linear or Notion), with an admin panel that is powerful but intuitive enough for one person to run the entire platform.

The platform delivers a complete database schema (users, roles, services, orders, transactions, commissions, subscriptions, announcements, messages), backend APIs, frontend pages for the admin dashboard plus the B2B, B2C and agent portals, authentication with role-based access control, payment tracking and email notification logic.

2. System Overview

Page 1 of 35

2a. Product Interpretation and Delivery Boundary

The platform is a first-party, application-owned web product. All four human roles — Super Admin, B2B Partner, B2C Direct Customer and Commission Agent — work inside the same application, separated by role-based access control. The Super Admin's entire control surface lives in one admin dashboard; the three customer-facing roles each have their own portal.

Identity is application-owned. Anonymous visitors arrive at the public Landing page, returning users verify identity at Login, and B2B Partners, B2C Customers and Commission Agents establish their own accounts at Sign Up. The Super Admin account is provisioned before platform management begins. Every protected destination requires an authenticated session with the matching role; a protected destination never owns the interaction that establishes access to itself.

Approval is a first-class, human decision. B2B license applications, agent commission payouts and other critical actions wait in Approvals until the Super Admin approves or rejects them, and the affected user sees the outcome and the resulting state change. Automated email is a supporting system process for registration, approval, rejection, announcements and new service alerts — it never replaces the in-product state the user can see.

Payments are tracked in-product and recorded in the Ledger; the platform records and tracks payments and commission calculations rather than acting as a card acquirer. Media management, announcements, inbox messaging, subscriptions and VIP grants are all admin-controlled. Everything described in this document is current scope; no future-horizon features are defined.

2b. Source Content Inventory

Not applicable — no reference directive supplies a content_source.

Page 2 of 35

2c. Page Content and Component Coverage

Landing

  • Information/state: Public, anonymous. Product identity, the government-approved Freezone positioning, the three served audiences (B2B partners, direct clients, agents), service categories and regions.
  • Primary actions: "Start an application" (routes to Sign Up); go to Login.
  • Supporting actions: Browse region tickets (Dubai, Abu Dhabi, Sharjah) as filters of what the platform covers.
  • Domain entities: Service category, region.
  • Component responsibilities: Hero band with headline, subline, red rule and CTA; stacked region tickets; category pictogram strip; role wayfinding tabs.
  • States: Loading (skeleton band), empty (no published categories → neutral message), success (content rendered), error (content fetch failure → retry), recovery (retry restores content).
Page 3 of 35

Login

  • Information/state: Anonymous. Email and password fields; role is resolved from the account, not chosen by the visitor.
  • Primary actions: Submit credentials; on success route to the role's home (Admin Dashboard, B2B Portal, B2C Portal or Agent Portal).
  • Supporting actions: Link to Sign Up.
  • Domain entities: User, role.
  • Component responsibilities: Credential form, inline validation, error banner.
  • States: Loading (submit disabled with progress), empty (blank form), success (redirect), error (invalid credentials message, form preserved), recovery (retry).

Admin Dashboard

  • Information/state: Role-restricted to Super Admin. Overview of partners, customers, agents, pending approvals, recent transactions, announcements and system health signals.
  • Primary actions: Navigate to every admin section (Services, Pricing, Approvals, Subscriptions, Announcements, Inbox, Media, Settings, Ledger); act on pending approvals surfaced here.
  • Supporting actions: Filter overview by region and currency; open a user record.
  • Domain entities: User, role, service, order, transaction, commission, subscription, announcement, message.
  • Component responsibilities: Left wayfinding rail with numbered role tabs; ruled filter bar; summary tiles; recent-activity table with role colour bars and tabular numerals.
  • States: Loading, empty (no activity yet), success, error (section fetch failure with retry), recovery.
Page 4 of 35

Sign Up

  • Information/state: Anonymous. Account type selection (B2B Partner, B2C Customer, Commission Agent), identity fields, credentials.
  • Primary actions: Create account; on success receive the automatic registration email and proceed to Login.
  • Supporting actions: Switch account type; link to Login.
  • Domain entities: User, role.
  • Component responsibilities: Role selector, form, validation, confirmation panel.
  • States: Loading, empty, success (confirmation + email sent notice), error (duplicate email or validation failure), recovery (correct and resubmit).

Services

  • Information/state: Role-restricted to Super Admin. Catalog list with category, region, B2B price, B2C price, agent commission rate and premium/VIP lock flag.
  • Primary actions: Add a new service; edit an existing service; set category, region, prices and commission rate; mark a service as premium/limited.
  • Supporting actions: Filter by category and region; search.
  • Domain entities: Service, category, region.
  • Component responsibilities: Catalog table with role colour bars and tabular numerals; create/edit form; lock toggle.
  • States: Loading, empty (no services), success (saved confirmation), error (validation or save failure), recovery.
Page 5 of 35

Pricing

  • Information/state: Role-restricted to Super Admin. Service prices per currency (AED primary, USD, PKR) and the configurable exchange logic.
  • Primary actions: Set or update service prices; configure exchange rates and exchange logic.
  • Supporting actions: Preview converted prices; filter by region.
  • Domain entities: Service, price, currency, exchange configuration.
  • Component responsibilities: Price grid, exchange-rate editor, conversion preview.
  • States: Loading, empty, success, error (invalid rate), recovery.

Approvals

  • Information/state: Role-restricted to Super Admin. Queue of B2B license applications, agent payout requests and other critical actions awaiting decision, each with requester, amount or licence detail, and status.
  • Primary actions: Approve; reject (with reason).
  • Supporting actions: Open the underlying record; filter by type and status.
  • Domain entities: License application, payout request, approval decision.
  • Component responsibilities: Queue table with amber pending stamps; decision panel; stamped outlined status label that snaps in.
  • States: Loading, empty (nothing pending), success (decision recorded and email triggered), error (decision save failure), recovery.
Page 6 of 35

Subscriptions

  • Information/state: Role-restricted to Super Admin. Subscription plans, subscriber list, VIP status per user.
  • Primary actions: Manage plans; grant VIP access manually; revoke VIP access.
  • Supporting actions: Filter by role and status.
  • Domain entities: Subscription, plan, VIP grant, user.
  • Component responsibilities: Plan list, subscriber table, VIP grant control.
  • States: Loading, empty, success, error, recovery.

Announcements

  • Information/state: Role-restricted to Super Admin. Draft and published announcements with audience and publish state.
  • Primary actions: Compose and publish an announcement; the system sends the automatic announcement email.
  • Supporting actions: Save draft; view publish history.
  • Domain entities: Announcement, audience, email dispatch record.
  • Component responsibilities: Composer, audience selector, publish history list.
  • States: Loading, empty, success (published + email queued), error (publish failure), recovery.
Page 7 of 35

Inbox

  • Information/state: Role-restricted. Super Admin sees all conversations with users; each user sees their own conversation with admin.
  • Primary actions: Super Admin sends an internal message to a user; user reads and replies.
  • Supporting actions: Search conversations; mark read.
  • Domain entities: Message, conversation, user.
  • Component responsibilities: Conversation list, thread view, composer.
  • States: Loading, empty (no messages), success (sent), error (send failure), recovery.

Media

  • Information/state: Role-restricted to Super Admin. Uploaded media assets with type, size and usage.
  • Primary actions: Upload media; delete media.
  • Supporting actions: Preview; search.
  • Domain entities: Media asset.
  • Component responsibilities: Upload dropzone, asset grid, preview panel.
  • States: Loading, empty, success (upload complete), error (unsupported file or upload failure), recovery.
Page 8 of 35

Settings

  • Information/state: Role-restricted to Super Admin. System settings including exchange logic for AED, USD and PKR and platform configuration.
  • Primary actions: Edit and save settings.
  • Supporting actions: Reset to last saved values.
  • Domain entities: System setting, exchange configuration.
  • Component responsibilities: Settings form grouped by area, save bar.
  • States: Loading, empty, success, error (validation), recovery.

Ledger

  • Information/state: Role-restricted to Super Admin. Every transaction with user role, service, amount, currency and status, plus automatic agent commission calculations.
  • Primary actions: Review and filter transactions; inspect a transaction's detail.
  • Supporting actions: Filter by role, service, currency and status; export view.
  • Domain entities: Transaction, commission record, user role, service, currency, status.
  • Component responsibilities: Ledger table with role colour bars and tabular numerals; detail drawer; totals strip.
  • States: Loading, empty, success, error (fetch failure), recovery.
Page 9 of 35

B2B Portal

  • Information/state: Role-restricted to B2B Partner. Partner home summarizing licence applications, sub-accounts, billing and official documents, with B2B-rate service access.
  • Primary actions: Start a licence application; open Sub-Accounts; open Billing; browse services at B2B rates.
  • Supporting actions: Filter services by region and currency.
  • Domain entities: Partner account, licence application, sub-account, invoice, document, service.
  • Component responsibilities: Partner summary band, section navigation, B2B-rate service list.
  • States: Loading, empty (new partner), success, error, recovery.

License Applications

  • Information/state: Role-restricted to B2B Partner. Application form and list of the partner's applications with status (pending, approved, rejected).
  • Primary actions: Submit a Freezone licence application; follow its approval status.
  • Supporting actions: View rejection reason; resubmit after rejection.
  • Domain entities: Licence application, approval decision.
  • Component responsibilities: Application form, status list with stamped labels.
  • States: Loading, empty, success (submitted, pending stamp), error (validation), recovery.
Page 10 of 35

Sub-Accounts

  • Information/state: Role-restricted to B2B Partner. Sub-accounts under the partner account with their details and status.
  • Primary actions: Create a sub-account; edit a sub-account.
  • Supporting actions: Deactivate a sub-account; search.
  • Domain entities: Sub-account, partner account.
  • Component responsibilities: Sub-account table, create/edit form.
  • States: Loading, empty, success, error, recovery.

Billing

  • Information/state: Role-restricted to B2B Partner. Billing history at B2B rates and official documents issued to the partner.
  • Primary actions: View billing entries; download official documents.
  • Supporting actions: Filter by currency and date.
  • Domain entities: Invoice, transaction, official document.
  • Component responsibilities: Billing table with tabular numerals, document list.
  • States: Loading, empty, success, error (document unavailable), recovery.
Page 11 of 35

B2C Portal

  • Information/state: Role-restricted to B2C Direct Customer. Service browsing by category and region at B2C prices, with premium/VIP-locked services marked.
  • Primary actions: Browse services; place an order; open Orders.
  • Supporting actions: Filter by region and currency; view locked-service notice.
  • Domain entities: Service, category, region, order.
  • Component responsibilities: Category pictogram strip, service cards with prices, region/currency ruled bar.
  • States: Loading, empty, success, error, recovery.

Orders

  • Information/state: Role-restricted to B2C Direct Customer. The customer's orders with status, payment state and invoice.
  • Primary actions: Place and pay for an order; track order status; receive and download the invoice.
  • Supporting actions: Filter by status; open order detail.
  • Domain entities: Order, payment, invoice, transaction.
  • Component responsibilities: Order list, checkout panel, status tracker, invoice view.
  • States: Loading, empty, success (paid, invoice issued), error (payment failure), recovery (retry payment).
Page 12 of 35

Agent Portal

  • Information/state: Role-restricted to Commission Agent. Agent home summarizing referrals, referred users, earned commissions and payout requests.
  • Primary actions: Open Referrals; open Commissions.
  • Supporting actions: View commission summary.
  • Domain entities: Referral, referred user, commission, payout request.
  • Component responsibilities: Agent summary band, section navigation.
  • States: Loading, empty (new agent), success, error, recovery.

Referrals

  • Information/state: Role-restricted to Commission Agent. Referral creation and the list of referred B2B or B2C users with their status.
  • Primary actions: Refer a B2B or B2C client; track referred users.
  • Supporting actions: Filter by client type and status.
  • Domain entities: Referral, referred user, client type.
  • Component responsibilities: Referral form, referred-user table with role colour bars.
  • States: Loading, empty, success (referral recorded), error, recovery.
Page 13 of 35

Commissions

  • Information/state: Role-restricted to Commission Agent. Earned commissions per referred client and service, with payout request status.
  • Primary actions: View earned commissions; submit a payout request for admin approval.
  • Supporting actions: Track payout request status.
  • Domain entities: Commission, payout request, approval decision.
  • Component responsibilities: Commission table with tabular numerals, payout request form, stamped status labels.
  • States: Loading, empty, success (request submitted, pending stamp), error (insufficient balance or save failure), recovery.
Page 14 of 35

3. Functional Requirements

FR-01 — Single admin control center (explicit) As a Super Admin, I should manage all B2B partners, B2C customers, agents, services, pricing, commissions, approvals, announcements, inbox, media and system settings from one admin dashboard, so that one person can run the entire platform.

  • Trigger: Super Admin signs in. Result: Admin Dashboard with navigation to every admin section. Access: role-restricted to Super Admin. Failure: section fetch error shows retry. Continuation: return to dashboard overview.

FR-02 — B2B partner enrollment (required_inference) As a prospective B2B Partner, I should create an account at Sign Up, so that I can apply for Freezone licences and access B2B rates.

  • Input: account type B2B Partner, identity fields, credentials. Result: account created, registration email sent automatically, routed to Login. Failure: duplicate email or validation error with preserved form. Continuation: sign in.

FR-03 — B2C customer enrollment (required_inference) As a prospective B2C Direct Customer, I should create an account at Sign Up, so that I can browse services and place orders.

  • Input: account type B2C Customer, identity fields, credentials. Result: account created, registration email sent, routed to Login. Failure: duplicate email or validation error. Continuation: sign in.

FR-04 — Commission agent enrollment (required_inference) As a prospective Commission Agent, I should create an account at Sign Up, so that I can refer clients and earn commissions.

  • Input: account type Commission Agent, identity fields, credentials. Result: account created, registration email sent, routed to Login. Failure: duplicate email or validation error. Continuation: sign in.
Page 15 of 35

FR-05 — Identity verification (required_inference) As a returning Super Admin, B2B Partner, B2C Customer or Commission Agent, I should sign in at Login, so that I reach my role's protected home.

  • Input: email and password. Result: session established and routed to Admin Dashboard, B2B Portal, B2C Portal or Agent Portal by role. Failure: invalid credentials message with form preserved. Continuation: retry or go to Sign Up.

FR-06 — Super Admin provisioning (required_inference) As the platform operator, I should have the Super Admin account provisioned before management begins, so that the single control center is reachable.

  • Result: Super Admin can sign in and reach Admin Dashboard. Access: role-restricted.

FR-07 — B2B licence application (explicit) As a B2B Partner, I should apply for a Freezone licence from License Applications, so that the company can issue me a UAE Freezone-approved licence.

  • Input: licence application details. Result: application recorded with pending status and visible in Approvals. Failure: validation error with preserved form. Continuation: follow status; resubmit after rejection.

FR-08 — B2B licence approval (explicit) As a Super Admin, I should approve or reject B2B licence applications in Approvals, so that only approved partners receive official licences.

  • Trigger: pending application. Result: decision recorded, status stamped on the partner's application, approval or rejection email sent automatically. Failure: decision save error with retry. Continuation: queue advances.
Page 16 of 35

FR-09 — Sub-account management (explicit) As a B2B Partner, I should manage sub-accounts under my partner account in Sub-Accounts, so that my organisation's users are organised under my licence.

  • Actions: create, edit, deactivate. Result: sub-account list updated. Failure: validation error. Continuation: return to list.

FR-10 — B2B billing and official documents (explicit) As a B2B Partner, I should view billing and receive official documents in Billing, so that I can reconcile what I owe and hold my issued documents.

  • Result: billing entries at B2B rates and downloadable official documents. Failure: document unavailable message. Continuation: retry download.

FR-11 — B2B-rate service access (explicit) As a B2B Partner, I should access services at B2B rates from the B2B Portal, so that I buy at partner pricing.

  • Result: services shown with B2B price. Access: role-restricted. Failure: fetch error with retry.

FR-12 — B2C service browsing (explicit) As a B2C Direct Customer, I should browse services by category and region in the B2C Portal, so that I find the service I need at B2C prices.

  • Result: filtered service list with B2C prices and premium/VIP locks marked. Failure: fetch error with retry.

FR-13 — B2C order placement and payment (explicit) As a B2C Direct Customer, I should place an order and make payment in Orders, so that the company delivers the service.

  • Input: selected service, currency. Result: order created with payment recorded in the Ledger. Failure: payment failure message with retry. Continuation: track status.
Page 17 of 35

FR-14 — B2C order tracking and invoices (explicit) As a B2C Direct Customer, I should track order status and receive invoices in Orders, so that I know progress and hold proof of purchase.

  • Result: status tracker and downloadable invoice. Failure: invoice unavailable message. Continuation: retry.

FR-15 — Agent referral of clients (explicit) As a Commission Agent, I should refer B2B or B2C clients in Referrals, so that my referrals are attributed to me.

  • Input: client type and client details. Result: referral recorded and linked to the agent. Failure: validation error. Continuation: track referred users.

FR-16 — Track referred users (explicit) As a Commission Agent, I should track my referred users in Referrals, so that I see who I brought in and their status.

  • Result: referred-user list with client type and status. Failure: fetch error with retry.

FR-17 — Automated commission calculation (explicit) As a Commission Agent, I should have commissions calculated automatically from each service's agent commission rate and recorded, so that my earnings are accurate without manual work.

  • Trigger: a referred client's transaction. Result: commission record created and visible in Commissions and in the Ledger. Failure: calculation failure surfaces as a missing record flagged for admin review. Continuation: record appears once resolved.

FR-18 — View earned commissions (explicit) As a Commission Agent, I should view earned commissions in Commissions, so that I know what I have earned.

  • Result: commission list with amounts and tabular numerals. Failure: fetch error with retry.
Page 18 of 35

FR-19 — Payout request (explicit) As a Commission Agent, I should request a payout in Commissions, so that I can be paid my earned commissions.

  • Input: payout amount within earned balance. Result: payout request recorded with pending status and visible in Approvals. Failure: insufficient balance or save error. Continuation: track request status.

FR-20 — Payout approval (explicit) As a Super Admin, I should approve or reject agent payout requests in Approvals, so that payouts are controlled.

  • Trigger: pending payout request. Result: decision recorded, status stamped for the agent, approval or rejection email sent. Failure: save error with retry. Continuation: queue advances.

FR-21 — Critical action approval (explicit) As a Super Admin, I should approve or reject other critical actions in Approvals, so that sensitive changes are gated.

  • Trigger: critical action awaiting decision. Result: decision recorded and reflected to the requester. Failure: save error with retry.

FR-22 — Service catalog management (explicit) As a Super Admin, I should add and edit services in Services with category, region, B2B price, B2C price and agent commission rate, so that the catalog stays current.

  • Result: catalog updated. Failure: validation error. Continuation: return to catalog.

FR-23 — New service addition and alert (explicit) As a Super Admin, I should add a new service and have the new service alert email sent automatically, so that users learn about it.

  • Result: service published and alert email dispatched. Failure: publish error with retry.
Page 19 of 35

FR-24 — Multi-currency pricing (explicit) As a Super Admin, I should set prices in AED (primary), USD and PKR in Pricing, so that services are priced for display and payment processing in all three currencies.

  • Result: prices stored per currency. Failure: invalid price error. Continuation: correct and save.

FR-25 — Configurable exchange logic (explicit) As a Super Admin, I should configure exchange logic in Pricing and Settings, so that currency conversion follows my rules.

  • Result: exchange configuration saved and applied to conversions. Failure: invalid rate error. Continuation: correct and save.

FR-26 — Subscription model (explicit) As a Super Admin, I should manage paid subscription plans in Subscriptions, so that serious business clients can subscribe.

  • Result: plans and subscribers managed. Failure: save error with retry.

FR-27 — Premium/VIP service locking (explicit) As the platform, I should lock certain premium or limited services behind subscription or VIP status, so that they are reserved for serious business clients.

  • Result: locked services marked and unavailable to non-entitled users with a clear notice. Failure: entitlement check error blocks access safely. Continuation: user subscribes or requests VIP.

FR-28 — Manual VIP grant (explicit) As a Super Admin, I should manually grant VIP access in Subscriptions, so that chosen clients unlock premium services.

  • Result: VIP status applied to the user. Failure: save error with retry.
Page 20 of 35

FR-29 — Announcements (explicit) As a Super Admin, I should publish announcements in Announcements, so that users receive official updates.

  • Result: announcement published and announcement email sent automatically. Failure: publish error with retry.

FR-30 — Internal messaging (explicit) As a Super Admin, I should send internal messages to users in Inbox, and as a B2B Partner, B2C Customer or Commission Agent I should read and reply in Inbox, so that admin and users communicate inside the platform.

  • Result: message thread updated for both sides. Failure: send error with retry.

FR-31 — Automated registration email (explicit) As a newly registered user, I should receive an automatic registration email, so that I have confirmation of my account.

  • Trigger: successful Sign Up. Result: email dispatched. Failure: dispatch failure logged and retried.

FR-32 — Automated approval and rejection emails (explicit) As a requester, I should receive an automatic email when my request is approved or rejected, so that I learn the outcome.

  • Trigger: approval decision. Result: email dispatched. Failure: dispatch failure logged and retried.

FR-33 — Financial ledger (explicit) As a Super Admin, I should review the Ledger, which records every payment from B2B and B2C and every agent commission calculation with user role, service, amount, currency and status, so that accounting is complete.

  • Result: complete transaction list with filters. Failure: fetch error with retry.
Page 21 of 35

FR-34 — Media management (explicit) As a Super Admin, I should manage platform media in Media, so that assets used across the platform are controlled.

  • Actions: upload, delete, preview. Failure: unsupported file or upload error. Continuation: retry.

FR-35 — System settings (explicit) As a Super Admin, I should manage system settings in Settings, so that platform configuration stays correct.

  • Result: settings saved. Failure: validation error. Continuation: correct and save.

FR-36 — Multi-region display (explicit) As a B2B Partner, B2C Customer or Super Admin, I should filter services and pricing by region (Dubai, Abu Dhabi, Sharjah or international regions), so that I see what applies to my region.

  • Result: filtered lists. Failure: fetch error with retry.

FR-37 — Role-based access control (explicit) As the platform, I should enforce role-based access so that each role reaches only its own destinations, so that partner, customer, agent and admin data stay separated.

  • Result: unauthorised access blocked and redirected to Login. Failure: session expiry returns to Login. Continuation: sign in again.

4. User Personas

Page 22 of 35

Super Admin

The single operator of the entire platform. The Super Admin's context is the Admin Dashboard, from which every other admin section is reached. The primary goal is to run a government-approved service business alone and efficiently: keep the catalog and prices current across AED, USD and PKR, decide every licence application and payout, publish announcements, hold conversations in the Inbox, manage media and settings, and read the Ledger. Distinct responsibilities: approving or rejecting B2B licence applications, agent payouts and other critical actions; configuring exchange logic; granting VIP access manually; adding new services. Inputs and decisions: approval decisions with reasons, price and rate values, VIP grants, announcement content. Interactions: with B2B Partners (licence decisions, billing), B2C Customers (orders, invoices), Commission Agents (payout decisions), and the automated email system. Observable success: every pending item decided, the Ledger complete, and users seeing accurate statuses.

B2B Partner

A business that holds or seeks a UAE Freezone-approved licence issued directly by the company. Context: the B2B Portal. Primary goal: obtain and operate under a Freezone licence while buying services at B2B rates. Distinct responsibilities: submitting licence applications and following their approval status, managing sub-accounts under the partner account, viewing billing, receiving official documents, and accessing services at B2B rates. Inputs and decisions: application details, sub-account details, currency and region filters. Interactions: with the Super Admin through Approvals outcomes and the Inbox; with the automated email system on registration and decisions. Observable success: an approved licence, an organised sub-account list, billing reconciled and official documents in hand.

Page 23 of 35

B2C Direct Customer

An individual or business buying services directly. Context: the B2C Portal. Primary goal: find the right service and get it delivered with clear payment and paperwork. Distinct responsibilities: browsing services by category and region at B2C prices, placing orders, making payments, tracking order status and receiving invoices. Inputs and decisions: service selection, currency, payment. Interactions: with the Super Admin through order fulfilment and the Inbox; with the automated email system. Observable success: a paid order with a tracked status and a downloadable invoice.

Commission Agent

A commission-based referrer of B2B or B2C clients. Context: the Agent Portal. Primary goal: bring in clients and be paid accurately for it. Distinct responsibilities: referring B2B or B2C clients, tracking referred users, viewing automatically calculated earned commissions, and requesting payouts that await admin approval. Inputs and decisions: client type and details, payout amount. Interactions: with the Super Admin through payout decisions and the Inbox; with referred clients whose transactions generate commissions; with the automated email system. Observable success: referrals attributed, commissions recorded automatically, and a payout request approved.

5. Core User Flows

Page 24 of 35

Flow A — Super Admin signs in and runs the control center

  1. Super Admin opens Login and submits credentials.
  2. The platform verifies identity and routes to Admin Dashboard.
  3. The Super Admin reviews pending approvals, recent transactions and activity, then navigates via the left wayfinding rail to any admin section.
  4. If a section fails to load, a retry restores it; the Super Admin continues from the dashboard.

Flow B — B2B Partner enrolls and applies for a Freezone licence

  1. Prospective partner opens Landing, reads the positioning and selects "Start an application".
  2. On Sign Up, the partner chooses B2B Partner, enters details and submits; the registration email is sent automatically and the partner is routed to Login.
  3. The partner signs in and lands on B2B Portal.
  4. The partner opens License Applications, completes the application and submits; the application shows a pending stamp.
  5. The application appears in the Super Admin's Approvals; the Super Admin approves or rejects it.
  6. The decision is stamped on the partner's application and an approval or rejection email is sent automatically.
  7. On rejection, the partner reads the reason and resubmits; on approval, the partner continues to Billing to receive official documents.
Page 25 of 35

Flow C — B2B Partner manages sub-accounts and buys at B2B rates

  1. From B2B Portal, the partner opens Sub-Accounts and creates or edits sub-accounts; the list updates.
  2. The partner browses services at B2B rates, filtering by region and currency.
  3. The partner opens Billing to view billing entries and download official documents; if a document is unavailable, the partner retries.

Flow D — B2C Customer orders and pays

  1. Customer enrolls at Sign Up (B2C Customer), receives the registration email and signs in at Login to reach B2C Portal.
  2. The customer browses services by category and region at B2C prices; premium services show a lock notice.
  3. The customer selects a service and opens Orders, places the order and makes payment in the chosen currency.
  4. The payment is recorded in the Ledger; the order shows its status and an invoice is issued.
  5. If payment fails, the customer retries; once paid, the customer tracks status and downloads the invoice.

Flow E — Commission Agent refers clients and earns commissions

  1. Agent enrolls at Sign Up (Commission Agent), receives the registration email and signs in at Login to reach Agent Portal.
  2. The agent opens Referrals, records a B2B or B2C client and submits; the referral is linked to the agent.
  3. The agent tracks referred users and their status in Referrals.
  4. When a referred client transacts, the commission is calculated automatically from the service's agent commission rate and recorded; the agent sees it in Commissions and the Super Admin sees it in the Ledger.
Page 26 of 35

Flow F — Commission Agent requests a payout

  1. From Commissions, the agent reviews earned commissions and submits a payout request within the earned balance; the request shows a pending stamp.
  2. The request appears in the Super Admin's Approvals; the Super Admin approves or rejects it.
  3. The decision is stamped on the agent's request and an approval or rejection email is sent automatically.
  4. On rejection, the agent reviews and resubmits; on approval, the agent continues referring clients.

Flow G — Super Admin configures catalog, pricing and exchange logic

  1. In Services, the Super Admin adds or edits a service with category, region, B2B price, B2C price and agent commission rate, and marks premium/limited services.
  2. In Pricing, the Super Admin sets prices in AED, USD and PKR and configures exchange logic; invalid rates are rejected until corrected.
  3. In Settings, the Super Admin saves system settings including exchange configuration.
  4. New services trigger the automatic new service alert email.

Flow H — Super Admin manages subscriptions and VIP access

  1. In Subscriptions, the Super Admin manages paid plans and reviews subscribers.
  2. The Super Admin manually grants VIP access to a chosen client; the client's premium services unlock.
  3. Locked services remain unavailable to non-entitled users with a clear notice until they subscribe or are granted VIP.
Page 27 of 35

Flow I — Super Admin publishes an announcement

  1. In Announcements, the Super Admin composes an announcement, selects the audience and publishes.
  2. The announcement is published and the announcement email is sent automatically; the publish history records it.

Flow J — Admin and users exchange internal messages

  1. The Super Admin opens Inbox, selects a user's conversation and sends a message.
  2. The user opens Inbox in their portal, reads the message and replies.
  3. The thread updates for both sides; a send failure offers retry.

Flow K — Super Admin reviews the financial ledger

  1. The Super Admin opens Ledger and filters by role, service, currency and status.
  2. Each transaction shows user role, service, amount, currency and status, with agent commission calculations alongside.
  3. The Super Admin opens a transaction detail to inspect it and returns to the ledger.

Flow L — Super Admin manages media

  1. In Media, the Super Admin uploads an asset; unsupported files are rejected with a message.
  2. The Super Admin previews or deletes assets; the asset grid updates.
Page 28 of 35

6. Visuals Colors and Theme

The muse is Erik Spiekermann: typographic infrastructure that builds trust with humanist type inside a clear system, with signal colours coding regions and roles like transit lines.

Headline: Typographic infrastructure for UAE business setup.

Colour tokens (light mode):

  • Background: #F4F0E8 (warm paper ground, most area)
  • Surface: #FFFDF8
  • Text: #1E1C19 (ink)
  • Primary: #B02418 (signal red — primary actions, licence lines)
  • Accent: #E0A700 (amber — pending approvals)
  • Muted: #6F6A60
  • B2B: #0F6E63 (teal)
  • Agent: #2F6B3A (green)
  • Hairlines: 1px ink rules at low opacity divide every row.

Typography: Headings and body Fira Sans. Headings Bold 700 with tight tracking; small-caps 600 labels with wide tracking for roles, regions and currency codes. Modular scale 1.25: 64/48/36/28/20/16/14; mobile headline 36px to 64px desktop, using clamp().

Shape language: Squared corners with 4px radius on controls; no pills, no soft drop shadows. Colour bars and numbered tabs act as wayfinding marks.

Layout: 12-column grid with a fixed left wayfinding rail; role tabs at the top; region and currency filters in a ruled bar; tables align labels and values in tabular numerals.

Page 29 of 35

Imagery: Schematic maps of the Emirates, pictograms for service categories, documentary photos of desks and documents. No abstract blobs, no gradients, no glass panels, no indigo/blue-on-white.

7. Signature Design Concept

The public entry is a full-width warm paper band. A 9-column Fira Sans headline in ink sits left, with a red 6px rule above it. At right, a stacked column of three region tickets — Dubai, Abu Dhabi, Sharjah — in signal colours acts as the visual subject, each ticket carrying the city name and licence count. The CTA is a squared red button pinned under the headline.

Hero copy: headline "Your UAE licence, issued with authority"; subline "Freezone licences, visas and government services for partners, clients and agents in one platform."; call to action "Start an application".

The signature moves carry through the product: a left wayfinding rail with numbered role tabs (01 Admin, 02 B2B, 03 Client, 04 Agent) in signal colours; region tickets reused as filters; every table row carrying a 4px role colour bar at its left edge with tabular-numeral prices; approval states rendered as a stamped outlined label that snaps in with no easing. All readable text and controls stay whole at 375px, 768px and 1280px.

Page 30 of 35

8. Interaction Model & Motion Direction

Interaction Model: Static Motion Tempo: restrained Hero Dimensionality: flat

Landing Hero Motion Brief

  • Focal subject: the stacked column of three region tickets (Dubai, Abu Dhabi, Sharjah) in signal colours.
  • Thesis: on load, the region tickets settle into their stack and their licence counts count up once; the headline and red rule hold still; the squared red CTA remains pinned under the headline. Input is page load only — no scroll-linked depth.
  • Motion vocabulary: short 150ms state changes with no bounce; numbers count up once on load; approval status stamps in with one quick frame.
  • Composed first frame: warm paper band, red 6px rule, ink headline left, three region tickets right, red CTA beneath the headline.
  • Reduced-motion state: tickets and counts render in their final positions immediately; no count-up, no settling.
Page 31 of 35

9. Non-Functional Requirements

  • Responsive: The interface must be fully responsive; headlines, labels, numbers, cards' text and controls stay entirely inside the viewport and their container at 375px, 768px and 1280px. (explicit)
  • Trustworthy presentation: Clean, premium, trustworthy SaaS interface suitable for a government-licensed service provider, using modern SaaS design patterns. (explicit)
  • Admin efficiency: The admin panel must be powerful but intuitive for one person to manage the entire platform. (explicit)
  • Access control: Authentication with role-based access control separates Super Admin, B2B Partner, B2C Customer and Commission Agent destinations. (explicit)
  • Financial integrity: Every payment and commission calculation is recorded with user role, service, amount, currency and status; records are not silently dropped. (explicit)
  • Currency: AED is the primary operating currency; USD and PKR are supported for display and payment processing; exchange logic is admin-configurable. (explicit)
  • Approval gating: B2B licence applications, agent payouts and critical actions cannot complete without an admin decision. (explicit)
  • Email reliability: Registration, approval, rejection, announcement and new-service emails are dispatched automatically; dispatch failures are logged and retried. (explicit, with required_inference for retry)
  • Reduced motion: With prefers-reduced-motion, a usable static arrangement is provided. (required_inference)
Page 32 of 35

10. Tech Stack

  • frontend: React application UI (single responsive app serving Landing, Login, Sign Up, Admin Dashboard, B2B Portal, B2C Portal and Agent Portal).
  • backend: Shared FastAPI process for application APIs and domain modules (authentication and RBAC, services, pricing and exchange, approvals, subscriptions and VIP, announcements, inbox, media, settings, ledger, commissions, email dispatch).
  • database: MariaDB for application-owned persistent data (users, roles, services, orders, transactions, commissions, subscriptions, announcements, messages, media, settings).
  • Email delivery: Outbound email dispatch from the backend for registration, approval, rejection, announcement and new-service alerts.
  • Deployment: Docker/docker-compose for the frontend, backend and database services.
Page 33 of 35

11. Assumptions and Constraints

  • The Super Admin account is provisioned before platform management; there is exactly one Super Admin control center. (required_inference)
  • B2B Partners, B2C Customers and Commission Agents self-enroll at Sign Up; the Super Admin does not create their accounts. (required_inference)
  • Payment tracking records and tracks payments and commission calculations; card acquiring is outside the described scope. (required_inference)
  • Email is a supporting notification channel; the authoritative state is always visible in-product. (required_inference)
  • All services originate from UAE Freezone authorities with government-approved licences. (explicit)
  • The platform is managed from a single admin dashboard. (explicit)
  • Premium or limited services are locked behind subscription or VIP status. (explicit)
Page 34 of 35

12. Glossary

  • Super Admin: The single operator managing the entire platform from the Admin Dashboard.
  • B2B Partner: A business that applies for and holds a UAE Freezone-approved licence issued by the company and buys at B2B rates.
  • B2C Direct Customer: An individual or business buying services directly at B2C prices.
  • Commission Agent: A commission-based referrer of B2B or B2C clients who earns automatically calculated commissions and requests payouts.
  • Freezone licence: A UAE Freezone-authority-approved licence issued directly to B2B partners.
  • Approvals: The admin queue where licence applications, payout requests and critical actions await decision.
  • Ledger: The financial record of every payment and commission calculation with user role, service, amount, currency and status.
  • VIP access: A status granting access to premium or limited services, grantable manually by the Super Admin.
  • Region ticket: The stacked coloured card showing a city name and licence count, used as hero subject and filter.
  • Role colour bar: The 4px coloured left edge on every table row coding the user's role.
Page 35 of 35

No completed page designs yet.

Completed design pages will appear here when they are ready to preview.

Landing: Start an application

Sign Up: 1. Select B2B Partner account type

Sign Up: 2. Correct duplicate email error

Login: Sign in with credentials

B2B Portal: Review partner summary

License Applications: Submit Freezone licence application

License Applications: 1. Follow pending approval status

License Applications: 2. Read rejection reason and resubmit

Sub-Accounts: Create sub-account

Sub-Accounts: Edit or deactivate sub-account

B2B Portal: Browse services at B2B rates

Billing: View billing entries

Billing: 1. Download official document

Billing: 2. Retry unavailable document

Inbox: Read and reply to admin message

No completed page designs yet.

Completed design pages will appear here when they are ready to preview.

Landing: Start an application

Sign Up: 1. Select B2B Partner account type

Sign Up: 2. Correct duplicate email error

Login: Sign in with credentials

B2B Portal: Review partner summary

License Applications: Submit Freezone licence application

License Applications: 1. Follow pending approval status

License Applications: 2. Read rejection reason and resubmit

Sub-Accounts: Create sub-account

Sub-Accounts: Edit or deactivate sub-account

B2B Portal: Browse services at B2B rates

Billing: View billing entries

Billing: 1. Download official document

Billing: 2. Retry unavailable document

Inbox: Read and reply to admin message