Unmurce Technical Documentation

02. Neo-Brutalism Visual Design System

The visual identity of Unmurce is anchored in modern Neo-Brutalism: unapologetic high-contrast black outlines, hard directional shadows with zero blur, deliberate asymmetry, and a signature pastel color palette.

Color Token Palette (Click any card to copy HEX)

Micro-Animations: The NeoBouncy Spring Controller

Every clickable element is wrapped with the custom Flutter widget NeoBouncy. When pressed, an AnimationController with Curves.easeInOutCubic scales the widget down to 0.94 while shifting the shadow offset, providing tactile spring-loaded feedback.

Design Token Specifications

Production UI Gallery

Home Dashboard with Expense List & Real-Time Balance

Multimodal AI Receipt Scanner with Line-Item Breakdown

Settings Panel, Notification Listener & Currency Selector

03. Architecture & Data Flow

The app combines an offline-first Flutter client, an Express API hosted on Vercel, and MongoDB Atlas. Cloudflare provides edge routing for the production domain.

┌─────────────────────────────────────────────────────────────────────────────────┐
│                        ANDROID MOBILE ENVIRONMENT (DEVICE)                       │
│                                                                                 │
│   ┌────────────────────────┐                   ┌────────────────────────────┐  │
│   │  Android OS Statusbar  │                   │   Flutter UI Layer         │  │
│   │  Banking Notifications │                   │   (hp2.dart, NeoBouncy)    │  │
│   └───────────┬────────────┘                   └─────────────┬──────────────┘  │
│               │ Broadcast                                    │                 │
│               ▼                                              │ Local SQLite write │
│   ┌────────────────────────┐    EventChannel / FIFO          │                   │
│   │ Kotlin NotificationSvc ├─────────────────────────────────┤                 │
│   └────────────────────────┘                                 ▼                 │
│                                                ┌────────────────────────────┐  │
│                                                │ SQLite Database (sqflite)  │  │
│                                                │ my_table (synced=0/1)      │  │
│                                                └─────────────┬──────────────┘  │
└──────────────────────────────────────────────────────────────┼─────────────────┘
                                                               │ Background Sync
                                                               │ (Bearer JWT)
                                                               ▼
                                                 ┌────────────────────────────┐
                                                 │ Cloudflare Edge DNS / SSL  │
                                                 └─────────────┬──────────────┘
                                                               │
                                                               ▼
                                                 ┌────────────────────────────┐
                                                 │ Vercel Serverless Express  │
                                                 │ requireAuth Firebase Admin │
                                                 └───────┬─────────────┬──────┘
                                                         │             │
                                        Mongoose Cluster │             │ AI Vision OCR
                                                         ▼             ▼
                                             ┌───────────────┐ ┌───────────────────────┐
                                             │ MongoDB Atlas │ │ Groq model             │
                                             │ Expense Schema│ │ (Azure receipt fallback)│
                                             └───────────────┘ └───────────────────────┘

04. Automated Notification Parser

After notification access is enabled, Unmurce processes Android payment alerts through a six-stage pipeline. Cloud parsing is attempted first, with on-device parsing available as a fallback.

The 6-Stage Hybrid Processing Pipeline

Apps with App-Specific Notification Parsers

Other notification formats may be handled by the general parser when their transaction details are recognizable.

05. Smart Receipt Scanner & Proportional Tax Allocation

When users upload or photograph a paper receipt (Indomaret, Alfamart, Starbucks, restaurants, groceries), the backend processes the image through an automated AI vision extraction pipeline.

Receipt Parser: Groq with Azure Fallback

Proportional Tax (PPN) & Service Charge Algorithm

Receipts typically list items without tax, appending PPN (11%) and Service Charges (5-10%) at the bottom. Unmurce applies proportional allocation across all line items so every recorded item includes its exact share of tax:

LineTotal = Σ (Item.Amount)
Adjustment = ReceiptTotal - LineTotal

For each Item_i (from 1 to N-1):
    ItemShare_i = Round((Adjustment * Item_i.Amount) / LineTotal)
    AllocatedTotal += ItemShare_i
    FinalAmount_i = Item_i.Amount + ItemShare_i

For the final Item_N:
    FinalAmount_N = Item_N.Amount + (Adjustment - AllocatedTotal)

Cancellable Operation & Dynamic Quantity Multiplier

On the Flutter client, requests are managed via ReceiptScanOperation wrapping http.Client. If the user taps Cancel during upload, the connection is instantly aborted (client.close()), freeing memory. Each item in the draft list maintains an interactive quantity multiplier:

int totalItemAmount = unitPrice * selectedQuantity;

06. Multi-Currency System & Real-Time Rates

Unmurce supports displaying amounts in three currencies: IDR, USD, and EUR. To prevent cumulative rounding errors, the system implements a strict Single Base Currency Model:

Supported Currencies

Offline Rate Caching in SQLite

Exchange rates fetched from GET /api/exchange-rates are immediately persisted to the SQLite app_settings table under the key rate_<CURRENCY>. If internet connectivity is unavailable in subsequent sessions, the app seamlessly reads from this local cache.

07. Financial Analytics & Dashboard Computations

The analytics screen (ExpenseSumarry.dart) processes transactional history into structured financial metrics with zero external analytics SDK overhead:

1. Category Spending Breakdown

Aggregates spending per category and computes proportional percentages:

double categoryTotal = expenses
    .where((e) => e.category == targetCategory)
    .fold(0, (sum, e) => sum + e.amount);

double percentage = (categoryTotal / totalAllExpenses) * 100.0;

2. Expected vs Unexpected Expense Ratio

Categorizes spending into expected (planned essentials: meals, rent, fuel) vs unexpected (impulse purchases, emergency healthcare, spontaneous dining) to calculate financial discipline index.

3. 7-Day Spending Histogram Normalization

Groups expenses by day over the past 7 days and normalizes bar heights based on peak daily spending:

final maxDailySpending = dailyTotals.reduce((a, b) => a > b ? a : b);

double computeBarHeight(double dayTotal, double maxContainerHeight) {
  if (maxDailySpending == 0) return 0.0;
  return (dayTotal / maxDailySpending) * maxContainerHeight;
}

08. PDF Report Engine & Android Scoped Storage Compliance

Users can export their complete transactional ledger into formatted, formal PDF reports. The generator is built entirely with Flutter vector drawing libraries (pdf and printing).

Scoped Storage Compliance (Android 10 to 14+)

Traditional Android apps trigger dangerous storage permission prompts (WRITE_EXTERNAL_STORAGE) which are rejected on modern Android versions. Unmurce implements a modern storage pipeline:

• MediaStore API Integration: Utilizes media_store_plus to save generated PDFs directly into the public Download/ExpenseApp directory without requiring runtime storage permissions.
• FileSaver Fallback: Automatically invokes file_saver on devices where MediaStore direct access is restricted.
• Instant Document Launch: Invokes open_filex to trigger the user's native PDF reader immediately upon file save.

09. Authentication & Multi-Tenant Data Isolation

User identification is secured end-to-end via Firebase Authentication and enforced through stateless cryptographic JWT Bearer verification:

async function requireAuth(req, res, next) {
  try {
    const header = req.headers.authorization || "";
    if (!header.startsWith("Bearer ")) {
      return res.status(401).json({ error: "Authentication required" });
    }
    const idToken = header.substring(7);
    req.user = await admin.auth().verifyIdToken(idToken);
    next();
  } catch (err) {
    res.status(401).json({ error: "Invalid or expired token" });
  }
}

Local SQLite Data Isolation (Multi-User Device Support)

If multiple users share the same Android device, records remain isolated. Every row in my_table stores an ownerId column corresponding to AuthService.currentUser?.uid. All queries strictly include WHERE ownerId = ? to prevent data bleed.

Single-Run Notification Onboarding Gate

To prevent user fatigue while complying with Android notification listener requirements, the permission screen is governed by a persistent SQLite flag:

final shown = await DatabaseHelp.getSetting('notification_permission_onboarding_shown');
if (shown == null && !isPermissionGranted) {
  await DatabaseHelp.saveSetting('notification_permission_onboarding_shown', 'true');
  Navigator.push(context, SmoothPageRoute(page: const NotificationPermissionPage()));
}

10. Offline-First Synchronization & Cloud Reconciliation

Unmurce adheres strictly to the Offline-First Paradigm. The mobile app never awaits network responses before confirming user actions.

The Synced State Protocol

Cloud Pull Deduplication Algorithm

When a user reinstalls the app or links a second device, the "Load Online Expenses" feature pulls all cloud records and merges them into SQLite without duplicating transactions:

final localRows = await db.query('my_table', where: 'ownerId = ?', whereArgs: [uid]);
final localMongoIds = localRows.map((r) => r['mongoId']).whereType<String>().toSet();

for (final online in onlineExpenses) {
  final remoteId = online['_id'] as String;
  if (!localMongoIds.contains(remoteId)) {
    await db.insert('my_table', {
      'mongoId': remoteId,
      'ownerId': uid,
      'name': online['name'],
      'amount': online['amount'],
      'category': online['category'],
      'type': online['type'],
      'date': online['date'],
      'synced': 1,
    });
  }
}

11. Primary Data Models (SQLite & MongoDB)

1. Local SQLite Schema (my_db.db — Version 6)

2. Cloud MongoDB Atlas Mongoose Schema

const ExpenseSchema = new mongoose.Schema(
  {
    ownerId: { type: String, required: true, index: true },
    localId: { type: String, required: true },
    name: { type: String, required: true },
    amount: { type: Number, required: true },
    category: { type: String, required: true },
    type: { type: String, required: true }, // 'expected' | 'unexpected' | 'others'
    date: { type: String, required: true }, // 'YYYY-MM-DD'
  },
  { timestamps: true }
);

// Compound unique index guarantees upsert idempotency per local ID
ExpenseSchema.index({ ownerId: 1, localId: 1 }, { unique: true });

12. Core REST API Reference (10 Endpoints)

This section covers ten core transaction, parsing, and exchange-rate endpoints. The Flutter client defaults to https://expense-app-personal.vercel.app/api; override it with EXPENSE_API_BASE_URL when needed. Private endpoints require a Firebase ID token in the Authorization header.

[
  {
    "_id": "6643a7b9f1d2c3e4a5b6c7d8",
    "ownerId": "firebase_uid_12345",
    "localId": "42",
    "name": "Kopi Kenangan QRIS",
    "amount": 24000,
    "category": "makanan",
    "type": "expected",
    "date": "2026-09-21",
    "createdAt": "2026-09-21T08:30:00.000Z"
  }
]

{
  "localId": "42",
  "name": "Bensin Pertamax",
  "amount": 50000,
  "category": "transportasi",
  "type": "expected",
  "date": "2026-09-21"
}

{
  "message": "Deleted",
  "deletedCount": 184
}

{"type":"progress","stage":"groq","status":"processing","progress":0.4,"message":"Processing with Groq"}
{"type":"result","date":"2026-09-21","provider":"groq","items":[{"name":"Iced Caffe Latte","quantity":2,"amount":62000,"category":"makanan","type":"expected"},{"name":"Croissant Butter","quantity":1,"amount":31000,"category":"makanan","type":"expected"}]}

{
  "title": "Transaksi Sukses",
  "packageName": "com.bca",
  "message": "Pembayaran QRIS Rp 45.000 ke RM Padang Sederhana berhasil pada 21/09"
}

{
  "name": "RM Padang Sederhana",
  "amount": 45000,
  "category": "makanan",
  "type": "expected"
}

{
  "base": "IDR",
  "rates": {
    "IDR": 1,
    "USD": 0.000064,
    "EUR": 0.000059
  }
}

13. Setup & Build Guide

1. Backend Setup (Vercel & Express)

Use these names when configuring Vercel environment variables or the local environment used by Vercel CLI. Replace the placeholders and keep real credentials out of source control.

# Required; replace the placeholder values
MONGODB_URI=YOUR_MONGODB_URI
FIREBASE_SERVICE_ACCOUNT_JSON=YOUR_SERVICE_ACCOUNT_JSON
GROQ_API_KEY=YOUR_GROQ_API_KEY
GROQ_MODEL=YOUR_GROQ_MODEL_ID
# Optional: defaults to GROQ_MODEL
GROQ_NOTIFICATION_MODEL=YOUR_NOTIFICATION_MODEL_ID
AZURE_DOCUMENT_INTELLIGENCE_ENDPOINT="https://your-resource.cognitiveservices.azure.com/"
AZURE_DOCUMENT_INTELLIGENCE_KEY="YOUR_AZURE_KEY"

# From repository root
cd backend

npm install

# Run the API locally with Vercel CLI
npx vercel dev

2. Mobile Application Build (Flutter & Android Gradle)

# Navigate to mobile Flutter project
cd frontend/expenseapp

# Pull pub packages
flutter pub get

# Run on connected Android device / emulator
flutter run

# Compile production split-per-abi release APKs
flutter build apk --split-per-abi --release