🪙 Fakka - فكّة
_{By Tantaropic}

The Middle East's first zero-effort micro-investment and spending & habits tracker Platform.
Turn your spare change into a growing portfolio, automatically, the moment you spend.
Track every transaction, understand your spending habits, get AI-powered advice, and replace bad habits with wealth-building ones.

---

📑 Table of Contents

• 💡 What is Fakka?
• ✨ Features
• 🏗️ Architecture Overview
• ⚙️ Technical Design Notes
• 🛠️ Tech Stack
• 🚀 Getting Started
• 📁 Project Structure
• 🌐 Environment Variables
• 💰 Monetization Model
• 🧪 Running Tests
• 📜 Available Scripts
• 🔒 Security & Compliance
• 🗺️ Roadmap

---

💡 What is Fakka?

Fakka (فكة) is a Sharia-compliant micro-investment and tracker for Spending & Habits that automatically rounds up every purchase you make to the nearest pound and invests the difference, the spare change you never notice, into a diversified portfolio of Gold, Index Funds, and High-Risk assets.

You buy a coffee for EGP 47. Fakka rounds it up to EGP 50, sweeps the EGP 3 in spare change, deducts a tiny platform fee, and immediately allocates it into your portfolio. No decision required. No minutes wasted. Your wealth builds itself.

🌍 Why Fakka? Why Now? Why the Middle East?

The Middle East and North Africa (MENA) region has one of the highest unbanked and under-invested populations in the world. Millions of people lack access to wealth-building tools that are taken for granted in the West.

• No similar product exists in the Middle East. Fakka is the first of its kind in the region.
• Sharia-compliant by design, no interest (Riba), no speculation, following Mudarabah (profit-sharing) principles.
• No financial literacy required. Zero minutes needed to start building wealth, just spend as you normally do.
• Designed for families and communities, not just individuals.

---

✨ Features

🔁 Zero-Effort Wealth Building

• Register once. Link your bank account once and Fakka handles the rest, forever.
• Automatic Round-Up Engine: Every transaction is rounded up to the nearest step. Spare change is swept and invested automatically without any user interaction.
• No time investment required. Your portfolio grows in the background while you live your life.

📊 Track Your Spending & Habits

• Full transaction history with merchant-level breakdown.
• Spending pattern analysis: Fakka identifies your recurring habits (coffee, cigarettes, dining out) and shows you their true long-term cost.
• AI-powered emotional nudges: Personalized insights generated by Azure OpenAI that reveal the opportunity cost of bad habits and celebrate your progress.

🛑 Stop Bad Habits, Build Good Ones

• The AI Emotional Engine monitors your merchant tags and surfaces patterns you didn't know you had.
• Every time you spend on a tracked habit, you see exactly how much wealth you could have built instead.
• Positive reinforcement mechanics to keep you motivated and invested (literally).

🎯 Set a Goal, Reach It Automatically

• Define a personal financial goal (e.g., EGP 50,000 for a car down payment).
• Fakka tracks your progress and automatically routes your round-ups toward it.
• Visual goal progress dashboard with real-time updates.

👨‍👩‍👧 Shared Family & Friends Accounts

• Shared Profiles: Create a group with family or friends under one unified digital wallet.
• Every member's transactions contribute to the shared portfolio, multiplying the compounding power.
• Mutual Goals: Set a collective target, a family vacation, an emergency fund, a property, and work toward it together automatically.
• One wallet, many contributors, unlimited potential.

📈 Invest Your Spare Change into a Real Portfolio

• Sharia-compliant asset allocation (24/75/1 rule):
  • 24% Gold, Inflation hedge, stable store of value.
  • 75% Index Funds, Broad market exposure, long-term compounding.
  • 1% High-Risk, High upside for the fearless portion of your portfolio.
• Risk profiles (Conservative, Default, Aggressive) let power users customize their allocation.
• Real-time portfolio valuation via live price feeds.

💸 Transparent, Fair Monetization (Mudarabah Model)

• No hidden fees. Fakka charges:
  • A small Fund Fee (0.5% → 0.01%) on deposits, decreasing as your AUM grows.
  • A Profit Fee (1.5% → 1%) only on gains, never on your capital.
• You only pay more when you earn more. We win when you win.
• Full ledger visibility, every fee is shown as a separate, auditable line item.

⚡ Real-Time Dashboard via SSE

• Live balance updates pushed instantly via Server-Sent Events (SSE).
• Watch your portfolio grow in real time with every sweep.
• Price feed updates reflect current market valuations of your holdings.

---

🏗️ Architecture Overview

Fakka's backend is a NestJS monolith with a clean, domain-driven architecture designed for financial precision.

┌──────────────────────────────────────────────────────────────────────────┐
│                             Fakka Backend                                │
│                                                                          │
│  ┌────────────────┐   ┌──────────────┐   ┌────────────────┐             │
│  │  Bank Webhook  │──▶│  Round-Up    │──▶│  Fee Engine    │             │
│  │  Gateway       │   │  Engine      │   │  (0.5% Fund)   │             │
│  │  [MockBankAPI] │   └──────────────┘   └────────────────┘             │
│  └────────────────┘                               │                      │
│                                                   ▼                      │
│  ┌────────────────┐   ┌──────────────┐   ┌────────────────┐             │
│  │  AI Emotional  │   │   Ledger     │◀──│ Asset Allocator│             │
│  │  Engine        │   │  (Audit)     │   │  24/75/1 Rule  │             │
│  └────────────────┘   └──────────────┘   └────────────────┘             │
│         │                                         │                      │
│         ▼                                         ▼                      │
│  ┌────────────────┐                      ┌────────────────┐             │
│  │  SSE Service   │                      │ Digital Wallet │             │
│  │  (Live Push)   │                      │ (BigInt / OCC) │             │
│  └────────────────┘                      └───────┬────────┘             │
│                                                  │                       │
│                                                  ▼                       │
│                                         ┌────────────────┐              │
│                                         │ Investment      │              │
│                                         │ Engine          │              │
│                                         │ [MockExchangeAPI│              │
│                                         │  for pricing]  │              │
│                                         └────────────────┘              │
│                                                                          │
└──────────────────────────────────────────────────────────────────────────┘

Note on Mocked APIs: For development and demo purposes, both the Bank and Exchange integrations are mocked:

• MockBankAPI — simulates open banking webhooks (transaction events) and fund collection requests.
• MockExchangeAPI — simulates live market prices for Gold, Index Funds, and High-Risk assets using a compound growth model (~40% APY). These will be replaced with real open banking and exchange connections in production.

Key Architecture Decisions

Principle	Implementation
Financial Precision	All monetary values stored as BigInt (Piasters), never floats
Sharia Compliance	Mudarabah model: profit-sharing fees, no interest
Audit Trail	Double-entry ledger for every financial movement
Concurrency Safety	Optimistic Concurrency Control (OCC) on DigitalWallet
Anti-Corruption Layer	Ports & Adapters pattern isolating domain from bank/exchange APIs
Event-Driven	@nestjs/event-emitter decouples modules, no circular dependencies
Domain Safety	Money Value Object for all arithmetic, no raw math allowed

---

⚙️ Technical Design Notes

💰 Money as a Value Object

All monetary values in Fakka are stored in the database as BigInt (smallest currency unit — Piasters for EGP, i.e. 1 EGP = 100 Piasters). This completely eliminates floating-point rounding errors.

Inside the application domain, money is never treated as a raw number. Instead, it is always wrapped in a Money Value Object with the following shape:

class Money {
  amount: bigint; // e.g. 4700n = EGP 47.00
  currency: Currency; // e.g. Currency.EGP
  denomination: major | minor; // e.g. 100 (100 piasters = 1 EGP)

  // Dedicated, safe arithmetic methods
  add(other: Money): Money;
  subtract(other: Money): Money;
  multiply(bps: bigint): Money; // uses Basis Points for rate math
  isGreaterThan(other: Money): boolean;
  toHuman(): string; // "47.00 EGP"
}

Raw arithmetic directly on BigInt or number is strictly forbidden in the domain layer. All financial math goes through these dedicated Money methods, enforced by code review and linting.

🔒 Race Condition Prevention

High-frequency events (multiple simultaneous round-ups, concurrent deposits, parallel price feed updates) can cause wallet balances to become inconsistent if not handled carefully. Fakka prevents this with Optimistic Concurrency Control (OCC):

• Every DigitalWallet row carries a version integer.
• Any update to a wallet must include a WHERE version = :currentVersion clause.
• If two concurrent operations try to update the same wallet simultaneously, only one will succeed — the other will detect the version mismatch and retry.
• This guarantees no double-credits, no double-debits, and no silent data corruption under load, without the performance penalty of pessimistic row-level locks.

---

🛠️ Tech Stack

Layer	Technology
Runtime	Node.js 20
Framework	NestJS 11
Database	PostgreSQL (via Prisma 7)
ORM	Prisma Client (BigInt-safe)
AI Engine	Azure OpenAI (GPT)
Real-Time	Server-Sent Events (SSE)
Validation	class-validator + class-transformer
Scheduling	@nestjs/schedule (cron jobs)
Deployment	Docker → Azure Container Apps

---

🚀 Getting Started

Prerequisites

Make sure you have the following installed:

• Node.js v20+
• npm v10+
• PostgreSQL v15+ (running locally or via Docker)
• Docker (optional, for containerized setup)

---

1. Clone the Repository

git clone <repo-url>
cd backend

2. Install Dependencies

npm install

3. Configure Environment Variables

Copy the example environment file and fill in your values:

cp .env.example .env

See the Environment Variables section for the full reference.

4. Set Up the Database

Run Prisma migrations to create all tables:

npm run db:migrate:dev

This will:

• Apply all schema migrations to your PostgreSQL database.
• Generate the Prisma client with full TypeScript types.

If you just want to push the schema without creating a migration file (e.g., for rapid prototyping):

npm run prisma:push

5. (Optional) Open Prisma Studio

Browse your database visually:

npm run prisma:studio

---

6. Run the Application

Development mode (with hot reload):

npm run start:dev

Production mode (after build):

npm run build
npm run start:prod

The API will be available at:

http://localhost:8000/api/v1

---

🐳 Run with Docker

Build and run the container:

docker build -t fakka-backend .
docker run -p 8000:3000 --env-file .env fakka-backend

---

📁 Project Structure

backend/
├── src/
│   ├── app/                    # App module & bootstrapping
│   ├── common/                 # Shared infrastructure
│   │   ├── constants/          # BPS rates, allocation rules
│   │   ├── domain/             # Money Value Object, Currency Registry
│   │   ├── events/             # Typed event payloads
│   │   ├── filters/            # GlobalExceptionFilter
│   │   ├── helpers/            # Response envelope (ok())
│   │   ├── interfaces/         # I_BANK_PROVIDER, I_EXCHANGE_PROVIDER ports
│   │   └── repositories/       # BaseRepository (ACL)
│   ├── database/               # Prisma service & configuration
│   ├── external-api/           # Mock Bank & Exchange API adapters
│   └── modules/
│       ├── ai-insights/        # AI emotional engine (Azure OpenAI)
│       ├── bank-integration/   # Webhook gateway + funds collection
│       ├── exchange-integration/# MockExchangeAPI adapter
│       ├── fee/                # Fee Engine (fund fee + profit fee)
│       ├── investment/         # Asset allocation + redemption
│       ├── ledger/             # Double-entry ledger service
│       ├── price-feed/         # Market price scheduler & broadcaster
│       ├── profiles/           # Profile + User aggregate root
│       ├── realtime/           # SSE service
│       ├── roundup-engine/     # Round-up calculator + sweep orchestrator
│       ├── transaction/        # Transaction event ingestion
│       ├── users/              # User settings & risk profiles
│       └── wallet/             # Digital wallet + positions
├── prisma/
│   ├── schema.prisma           # Full DB schema (BigInt-safe)
│   └── migrations/             # Versioned SQL migrations
├── docs/                       # Architecture & feature documentation
│   ├── DEVELOPER_GUIDELINES.md
│   ├── architecture-decisions/
│   ├── entities.md
│   ├── fees.md
│   ├── user-stories.md
│   └── ...
├── infra/                      # Azure / deployment infrastructure
├── .env.example                # Environment template
├── Dockerfile                  # Multi-stage production build
└── package.json

---

🌐 Environment Variables

All configuration is driven by environment variables. Copy .env.example to get started:

cp .env.example .env

.env.example:

# ─── Server ────────────────────────────────────────────────
# Enviroment
NODE_ENV=development

# App
HOST=http://localhost
PORT=5001
API_VERSION=api/v1
BASE_URL=http://localhost:5001/api/v1

DB_URI=postgresql://postgres:postgres@host:port/DataBase

# System API URLs
SYSTEM_TRANSACTION_WEBHOOK_ROUTE=bank-integrations/transaction-webhook

# External Bank API URLs
MOCK_BANK_ROUTE=mock-bank
MOCK_BANK_SIMULATE_TRANSACTION=mock-bank/simulate-transaction
MOCK_BANK_DEBIT_ROUTE=mock-bank/debits
MOCK_BANK_DEPOSIT_ROUTE=mock-bank/deposits

# External Exchange API URLs
MOCK_EXCHANGE_ROUTE=mock-exchange
MOCK_EXCHANGE_PRICES=mock-exchange/prices
MOCK_EXCHANGE_BUY=mock-exchange/buy
MOCK_EXCHANGE_SELL=mock-exchange/sell
MOCK_EXCHANGE_SET_PRICES=mock-exchange/set-prices

# Default values - Major unit
DEFAULT_ROUND_UP_STEP=10

# GitHub Models
GITHUB_TOKEN=ghp_Fakka-your-token-here
AI_MODEL=gpt-4.1

---

💰 Monetization Model

Fakka operates on a Mudarabah (profit-sharing) model, fully Sharia-compliant:

Fund Fee (on every deposit & round-up)

Portfolio Size	Fee
Up to EGP 1,000	0.5%
Up to EGP 10,000	0.4%
Up to EGP 100,000	0.3%
Up to EGP 1,000,000	0.2%
Up to EGP 10,000,000	0.1%
Up to EGP 100,000,000	0.05%
Beyond	0.01%

Profit Fee (on gains only, never on capital)

Profit Level	Fee
Up to EGP 10,000	1.5%
Up to EGP 100,000	1.4%
Up to EGP 1,000,000	1.3%
Up to EGP 10,000,000	1.2%
Up to EGP 100,000,000	1.1%
Beyond	1.0%

We only win when you win. No profit for Fakka unless your portfolio grows.

---

🧪 Running Tests

# Unit tests
npm run test

# Watch mode
npm run test:watch

# Coverage report
npm run test:cov

# End-to-end tests
npm run test:e2e

---

📜 Available Scripts

Script	Description
npm run start:dev	Start with hot reload (development)
npm run start:prod	Start production build
npm run build	Compile TypeScript to dist/
npm run lint	Lint and auto-fix with ESLint
npm run format	Format with Prettier
npm run db:migrate:dev	Run Prisma migrations (dev)
npm run db:migrate:prod	Deploy migrations (prod)
npm run prisma:generate	Regenerate Prisma client
npm run prisma:push	Push schema without migration
npm run prisma:studio	Open Prisma Studio GUI
npm run test	Run unit tests
npm run test:cov	Run tests with coverage report

---

🔒 Security & Compliance

• BigInt-only arithmetic, no floating-point errors in financial calculations.
• Optimistic Concurrency Control (OCC), prevents race conditions on wallet updates.
• Double-entry ledger, every piastre is accounted for; balances are always reconcilable.
• Idempotency keys on all financial operations, safe retries, no double-charges.
• Anti-Corruption Layer, domain logic is completely isolated from external bank/exchange APIs.
• Sharia Compliance, Mudarabah profit-sharing; no Riba (interest).

---

🗺️ Roadmap

• Live Open Banking integration (beyond MockBankAPI)
• Mobile app (iOS & Android)
• Expanded asset classes (Sukuk, REITs)
• Goal-based savings plans with automatic rebalancing
• Multi-currency support (SAR, AED, KWD)
• MENA regional expansion (Saudi Arabia, UAE, Kuwait)
• Regulatory licensing (Egyptian Financial Regulatory Authority)

---

👥 Team

Tantaropic, Building the future of wealth in the Middle East.

---

📄 License

Proprietary. All rights reserved © 2026 Tantaropic.

---

Built with ❤️ for the people of the Middle East.
فكّة صغيرة، ثروة كبيرة, Small change, big wealth.