🇦🇪 UAE Real-Time Tax Engine

A lightweight, bilingual (Arabic/English) PWA that turns any phone into a live "tax dashboard" for UAE micro-businesses, freelancers and e-commerce sellers.

🎯 What Makes This Different

Unlike generic calculators and spreadsheets, the UAE Tax Engine provides three unique capabilities:

1. 📊 Live Tax Meter

Real-time tracking of your tax position with 0% and 9% bracket visualization
Automatic sync with banks, Stripe, PayPal, Talabat, and Amazon via Open Banking
No manual entry required after initial setup
See exactly how much of today's profit is in the AED 375k tax-free bucket

2. 🧠 AI-Powered Chart of Accounts

Learns from your business - auto-categorizes transactions with >90% accuracy after 30 days
Remembers patterns like "Instagram ads", "Salik", "Dubai Chamber fees"
Understands UAE tax rules (e.g., meals 50% deductible, capital allowances)
Claude AI powered classification engine

3. 🎚️ Instant What-If Scenario Planner

Single slider: "Close the year with AED X profit"
AI suggests legal tactics under UAE CT law:
- Pre-pay next quarter's rent
- Bring forward asset purchases under AED 1m
- Time invoice deliveries strategically
See tax impact in real-time

🚀 Quick Start

Prerequisites

Node.js 18+
Firebase account
Anthropic API key (for AI features)
Lean Technologies sandbox account (UAE Open Banking)
Stripe account (for payments & subscriptions)

Installation

# Clone the repository
git clone https://github.com/maidulcu/UAE-Tax-Engine.git
cd UAE-Tax-Engine

# Install dependencies
npm install

# Copy environment variables
cp .env.example .env

# Configure your environment variables in .env
# - Firebase credentials
# - Anthropic API key
# - Lean Technologies credentials
# - Stripe keys

# Run development server
npm run dev

Visit http://localhost:3000 to see the app.

Environment Setup

Edit .env with your credentials:

# Firebase
NEXT_PUBLIC_FIREBASE_API_KEY=your_key
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your_project_id

# AI Services
ANTHROPIC_API_KEY=sk-ant-your_key

# Open Banking (Lean Technologies)
LEAN_APP_TOKEN=your_lean_token
LEAN_API_SECRET=your_lean_secret
LEAN_ENVIRONMENT=sandbox

# Stripe
STRIPE_SECRET_KEY=sk_test_your_key
STRIPE_PUBLISHABLE_KEY=pk_test_your_key

📁 Project Structure

UAE-Tax-Engine/
├── src/
│   ├── app/                      # Next.js 14 App Router
│   │   ├── page.tsx              # Main dashboard
│   │   ├── layout.tsx            # Root layout
│   │   └── globals.css           # Global styles
│   ├── components/               # React components
│   │   ├── LiveTaxMeter.tsx      # Real-time tax visualization
│   │   └── WhatIfSlider.tsx      # Scenario planning slider
│   ├── lib/                      # Core business logic
│   │   ├── tax-engine/           # UAE tax calculation rules
│   │   │   └── uae-rules.ts      # CT & VAT rules (375k threshold)
│   │   ├── ai/                   # AI-powered features
│   │   │   ├── transaction-classifier.ts  # Auto-categorization
│   │   │   └── tax-optimizer.ts           # Optimization suggestions
│   │   ├── firebase/             # Firebase configuration
│   │   │   ├── config.ts         # Firebase setup
│   │   │   └── database.ts       # Realtime DB operations
│   │   ├── integrations/         # External service integrations
│   │   │   ├── lean-banking.ts   # Lean Technologies (UAE banks)
│   │   │   └── stripe-integration.ts  # Stripe payments
│   │   ├── fta/                  # FTA compliance
│   │   │   └── xml-export.ts     # emaraTax XML export
│   │   └── i18n/                 # Internationalization
│   │       └── config.ts         # Arabic/English config
│   └── types/                    # TypeScript definitions
│       ├── tax.ts                # Tax-related types
│       └── user.ts               # User & subscription types
├── public/
│   ├── locales/                  # Translation files
│   │   ├── en/common.json        # English translations
│   │   └── ar/common.json        # Arabic translations
│   └── manifest.json             # PWA manifest
├── next.config.js                # Next.js + PWA config
├── tailwind.config.ts            # Tailwind CSS config
└── tsconfig.json                 # TypeScript config

💡 Core Features

UAE Tax Compliance

✅ Corporate Tax (Federal Decree-Law No. 47 of 2022)
- 0% rate for profits ≤ AED 375,000
- 9% rate for profits > AED 375,000
- Small business relief calculations
✅ VAT (5% standard rate)
- Automatic VAT calculation
- Input/Output VAT tracking
✅ FTA Export
- emaraTax XML generation
- Corporate Tax return format
- VAT return format

Integrations

Open Banking (Lean Technologies)

// Automatically sync transactions from UAE banks
const leanClient = createLeanClient();
const transactions = await leanClient.syncTransactions(accessToken, accountId, fromDate);

AI Transaction Classification

// AI learns your business patterns
const classifier = new AITransactionClassifier(apiKey);
const result = await classifier.classifyTransaction(
  "Instagram ads campaign",
  1500,
  "Meta Platforms"
);
// Result: { category: 'marketing', confidence: 0.95, taxDeductible: true }

AI Tax Optimization

// Get personalized tax-saving suggestions
const optimizer = new TaxOptimizationEngine(apiKey);
const scenario = await optimizer.generateWhatIfScenario(
  currentProfit,
  projectedProfit,
  transactions
);
// Returns legal optimization strategies with potential savings

🌐 Bilingual Support

The app fully supports Arabic and English:

// Switch languages
import { useTranslation } from 'react-i18next';

const { t, i18n } = useTranslation();

// Use translations
<h1>{t('liveTaxMeter.title')}</h1>  // "Live Tax Meter" or "مقياس الضريبة المباشر"

// Change language
i18n.changeLanguage('ar');  // Switch to Arabic

💰 Monetization Model

Freemium Tiers

Free Plan

Live tax meter
Basic transaction tracking
Manual transaction entry
1 bank connection

Premium Plan - AED 49/month

✅ Multi-bank feeds (unlimited)
✅ VAT & CT return auto-population
✅ FTA emaraTax XML export
✅ AI tax optimization suggestions
✅ Priority support

White-Label API

AED 0.05 per transaction
Custom branding for accounting firms
Webhook integrations
Batch processing

🏗️ Architecture

Tech Stack

Frontend: Next.js 14 (App Router) + React 18
Styling: Tailwind CSS + Framer Motion
State: Zustand + React Query
Database: Firebase Realtime Database
Auth: Firebase Authentication
AI: Anthropic Claude 3.5 Sonnet
Payments: Stripe
Open Banking: Lean Technologies (UAE)
Hosting: Azure UAE North (edge-cached, <150ms)

Performance

⚡ < 150ms load time (Azure UAE North edge caching)
📱 PWA - Installable, offline-capable
🔄 Real-time sync via Firebase
🎨 Optimized animations with Framer Motion

🔐 Security & Compliance

🔒 Encrypted at rest (Firebase + Azure)
🔐 OAuth 2.0 for bank connections
🛡️ UAE data residency (Azure UAE North)
✅ FTA compliant XML exports
🔑 Secure token storage

📊 UAE Tax Rules Implementation

Corporate Tax Calculation

import { calculateCorporateTax, UAE_TAX_CONSTANTS } from '@/lib/tax-engine/uae-rules';

const result = calculateCorporateTax(500000);
/*
{
  grossIncome: 500000,
  adjustedTaxableIncome: 500000,
  corporateTax: 11250,          // (500000 - 375000) × 0.09
  effectiveRate: 0.0225,        // 2.25%
  breakdown: {
    freeBracket: 375000,        // 0% rate
    taxableBracket: 125000      // 9% rate
  }
}
*/

Deduction Rules

import { isDeductibleExpense } from '@/lib/tax-engine/uae-rules';

const result = isDeductibleExpense('meals_entertainment', 'Client lunch - Dubai');
/*
{
  deductible: true,
  percentage: 50,               // Only 50% deductible per UAE CT law
  reason: 'Meals & Entertainment - 50% deductible per UAE CT law'
}
*/

🧪 Testing

# Run type checking
npm run type-check

# Build for production
npm run build

# Start production server
npm start

🚢 Deployment

Azure (Recommended for UAE)

# Install Azure CLI
az login

# Deploy to Azure UAE North
az webapp up --name uae-tax-engine --location uaenorth --sku B1

Vercel (Alternative)

# Install Vercel CLI
npm i -g vercel

# Deploy
vercel --prod

🤝 Contributing

We welcome contributions! Please see our Contributing Guide.

Development Workflow

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

UAE Federal Tax Authority for tax regulations and guidelines
Lean Technologies for Open Banking infrastructure
Anthropic for Claude AI capabilities
Firebase for real-time database and authentication

📞 Support

📧 Email: support@uae-tax-engine.com
💬 Discord: Join our community
📖 Documentation: docs.uae-tax-engine.com

🗺️ Roadmap

Q1 2025: Multi-currency support (USD, EUR, AED)
Q2 2025: Mobile apps (iOS & Android)
Q3 2025: Advanced analytics dashboard
Q4 2025: Integration with accounting software (QuickBooks, Xero)

Built with ❤️ for UAE entrepreneurs and freelancers

Disclaimer: This software provides tax calculations based on UAE Federal Tax Authority regulations. Always consult with a qualified tax professional for official tax advice.

Name		Name	Last commit message	Last commit date
Latest commit History 6 Commits
public		public
src		src
.env.example		.env.example
.gitignore		.gitignore
COMPLETE-DOCUMENTATION.md		COMPLETE-DOCUMENTATION.md
CRITICAL-FIXES.md		CRITICAL-FIXES.md
README.md		README.md
SETUP.md		SETUP.md
STATUS.md		STATUS.md
firebase.rules.json		firebase.rules.json
next.config.js		next.config.js
package.json		package.json
postcss.config.js		postcss.config.js
tailwind.config.ts		tailwind.config.ts
tsconfig.json		tsconfig.json

Dynamic-Web-Lab/UAE-Tax-Engine

Folders and files

Latest commit

History

Repository files navigation