📜 Iqrarnama (اِقرار نامہ) — Secure Digital Trust & B2B/B2C Credit Ledger

Iqrarnama (اِقرار نامہ) is a secure, mobile-first digital ledger system designed for micro, small, and medium enterprises (MSMEs) to record trust-based credit transactions ("Udhar" / "Parchi"), prevent commercial disputes, and streamline settlements.

The project features a Go Backend Ledger Engine (Go/REST API/PostgreSQL) and a multi-platform Flutter Client App (Web & Android Mobile), implementing key fintech functionalities like CNIC OCR scanning, biometric security locks, custom hand-drawn signature boards, and offline-first data reconciliation.

---

🏗️ System Architecture

graph TD
    %% Clients
    subgraph Client Applications
        Creditor[Creditor Web/Mobile Client]
        Debtor[Debtor Mobile Client]
    end

    %% API Gateway
    subgraph REST API Engine (Go)
        Router[Router & CORS Middleware]
        Limiter[Per-IP Rate Limiter]
        Auth[Auth Handler]
        Ledger[Ledger Handler]
    end

    %% Database
    subgraph Persistence Layer
        DB[(PostgreSQL Database)]
    end

    %% Flow
    Creditor -->|HTTPS / REST API| Router
    Debtor -->|HTTPS / REST API| Router
    Router --> Limiter
    Limiter --> Auth
    Limiter --> Ledger
    Auth --> DB
    Ledger --> DB

Loading

---

✨ Core Features

🔒 Conventional Fintech Onboarding & Verification

• Unique 13-digit CNIC Enforcement: The Go backend and Flutter frontend enforce strict Pak-DB standard validation constraints to block duplicate business registrations.
• ML Kit OCR Scanner: Uses an automated camera-based OCR parser to recognize CNIC patterns (\b[0-9]{5}-[0-9]{7}-[0-9]\b or 13 digits) from physical identity cards, pre-filling registration fields instantly.
• Hand-Drawn Signature Canvas: Replaces plain digital confirmations with a zero-dependency custom-paint signature canvas. Debtors must draw their physical signature to seal and authorize a credit ledger entry.

🔑 Biometric Lock & Fingerprint Login

• Persistent Preferences Framework: Local credentials and biometric settings are stored in an encrypted JSON file framework on device storage.
• Fintech Toggle Security: Enabling Biometric Lock in settings requires PIN/Password authentication (verified against the backend login API) and a fingerprint scan before saving credentials.
• Sign-in & Sign-up Quick-Enrollment: Seamlessly prompts new users to register their fingerprints immediately after successful manual login or business sign-up.

📅 Smart Visibility & Settlement Controls

• Date-Restricted Actions:
  • Flag as Overdue: Creditors can only mark a contract overdue if the due date has strictly passed.
  • Request Extension: Debtors can only request payment extensions on or after the exact due date.
• Notification Hub Notifications: Dynamic push/polling center displaying new deeds, extensions, and settlement requests ("Pending Review" alerts for debtors, "Approve/Reject" action panels for creditors).

🌐 Web & Mobile Offline-First Stability

• In-Memory Web Cache Fallback: Seamlessly switches to local in-memory storage on web browsers where native mobile directories (path_provider) or native biometrics (local_auth) are unsupported.
• Outbox Queue Pattern: Holds transactions in an offline outbox and auto-reconciles them with the backend when connection is restored.

---

🛠️ Technical Stack

Frontend (Flutter App)

• State Management: Provider (ChangeNotifier)
• Local Database/Preferences: Custom File-based JSON Persistence + Memory-Safe Fallback
• OCR Text Recognition: Google ML Kit Text Recognition
• Biometric Integration: local_auth (Fingerprint/FaceID)
• Design System: Harmonies-tailored HSL colors, responsive layouts, support for Dark/Light theme modes.

Backend (Go Engine)

• Language: Go (Golang) 1.21+
• Database: PostgreSQL
• Security: Argon2id password hashing, JWT-signed tokens, structural rate limiting.
• Design Patterns: Dependency Injection, Repository pattern, Database migrations integration.

---

🚀 Getting Started

Prerequisites

• Flutter SDK: Install Flutter
• Go SDK: Install Go
• PostgreSQL: (Optional, Go backend automatically falls back to in-memory mock storage if postgres is not active).

1. Running the Go Backend

cd backend-ledger
go run main.go

The server will start listening on port :8080.

2. Running the Flutter App (Web/Desktop)

cd frontend_app
puro flutter run -d chrome  # For Web Browser
puro flutter run -d windows # For Windows Desktop

3. Deploying to a Physical Android Device

1. Connect your phone via USB and verify USB Debugging is active:

   adb devices

2. Build and compile the release APK:

   puro flutter build apk --release

3. Install the APK on your device:

   adb install build/app/outputs/flutter-apk/app-release.apk

---

📂 Project Structure

iqrarnama-core/
├── backend-ledger/          # Go API Engine
│   ├── internal/            # Core server logic (auth, ledger, db, config)
│   ├── schema/              # SQL Migration files
│   └── main.go              # Main Entrypoint
└── frontend_app/            # Flutter Multiplatform Client
    ├── lib/
    │   ├── models/          # Data schemas (CreditContract, UserRole)
    │   ├── providers/       # State management (AppStateProvider)
    │   ├── screens/         # UI Screen components (Dashboard, Welcome, Preferences)
    │   ├── services/        # Local Cache, Preferences, Network Sync
    │   └── widgets/         # Custom UI overlays (Notification Center, Sign Pad)
    └── pubspec.yaml         # Dependencies configuration

---

🤝 How to Push to Your GitHub Portfolio

To showcase this project on your personal GitHub profile:

1. Create a new repository on GitHub (do NOT initialize with a README, .gitignore, or license).
2. Initialize git and add remote in your local root directory:

   git init
   git add .
   git commit -m "Initialize Iqrarnama - secure digital ledger and fintech app"

3. Link to your GitHub repo and push:

   git branch -M main
   git remote add origin https://github.com/YOUR_GITHUB_USERNAME/YOUR_REPO_NAME.git
   git push -u origin main