A bank that witnesses, seals, settles, and nets interest-free interpersonal loans (قرض حسن / qard hasan) — and never lends its own money, never judges disputes, never charges interest or penalty, and never scores credit.
Basis: Qur'an 2:282 (write the debt) + 2:280 (grace for the struggling). Soul: «كلمتك محفوظة، وعلاقتك محميّة» — Your word is kept, your relationship is protected.
🏆 Mission — AMAD Hackathon 2026: this repo exists to take 1st place (250,000 SAR) on 18 July 2026 against ~1000 projects. Every change is reviewed through the five published judging criteria — docs/JUDGE-LENS.md — before it counts as done. Good is the entry fee; the bar is unforgettable.
A fully offline, deterministic, Arabic-first (RTL) web app. 12 screens over a single parity-proven engine.
| Screen | What it is | Spine highlight |
|---|---|---|
| 🏠 الرئيسية | Front door: brand, live standing strip (net balance, witness count, trust word), feature cards | Bank witnesses, never lends/judges/charges/scores |
| ➕ أنشئ عهدًا | Create a عهد with the live riba linter | Blocks penalty/interest, offers halal fix, gates the seal |
| 📔 دفتري | Creditor home (لي/عليّ) + bank-sent gentle reminder | Overdue is amber, never red; no shaming counter; merciful ladder |
| 📜 سِجلّ الشهادة | Witness timeline — per-عهد story view + flat feed | Bank witnesses; late=amber, dispute=neutral, no score |
| ♾️ القرض المفتوح | Open-term qard hasan + إبراء (forgiveness) | No due ⇒ never overdue; conservation exact |
| 👥 الدائرة | Treasurer dashboard: progress + dignified member states | Group reminder never names the late |
| 🔁 الدائرة+ | By-item split, recurring auto-post, graduation قَيْد→عهد | Mode-B pledge |
| 🔗 المقاصّة | Tangle → fewest transfers (9→2) + conservation proof | Preserves every member's net position exactly |
Contextual screens (reached in-flow, no nav pill): حافظة الإثبات (proof-pack with live tamper-verify) · محلّ خلاف (dispute pause — «يشهد ولا يحكم») · الإعدادات (Arabic-Indic digits + privacy mask + manifesto) · اطلب عهدًا (borrower-initiated request).
# Run the app (one command, fully offline)
node app/_serve-app.cjs # → http://localhost:8124
# Or just open the file
# Double-click app/index.html in your file browserOne engine, two surfaces:
| app/ | demo/ | |
|---|---|---|
| Entry | app/index.html |
demo/index.html |
| Status | Active — the publishable product | Frozen — byte-pinned presenter reference |
| Structure | Multi-file: engine.js + features/*.js + screens/*.js + app.js |
Single HTML file |
| Engine | engine.js — generated by app/build-engine.cjs |
Inline AHD-LOGIC region (lines 167–692) |
The engine is the same code in both. build-engine.cjs reads the demo's logic region verbatim and wraps it for dual module export (Node + browser). Faithfulness is enforced by tests/app/engine-parity.cjs — the drift guard.
Key properties:
- Fully offline — zero network calls, no build step, no dependencies
- Deterministic — fixed
AS_OF, integer halalas (1 SAR = 100), civil-days math; noDate.now/Math.random/Intl/toLocaleStringin live code - Pure DI — feature modules receive the engine by injection, testable in plain Node
- RTL-first — Arabic is the source language, layout is right-to-left by design
- Dignity-first — late is amber, never red. No shaming, no countdowns, no scores.
- Trust is a word, never a number — «وفّى بعهوده», «جديد», «متأخّر». No percentages, no ratings.
- Riba-free by construction — the linter catches disguised interest clauses before sealing.
- Shariah-aligned visual language — no alarm icons, no penalty symbols, no credit metaphors.
See DESIGN.md for the full design system (colors, typography, layout, components).
# Demo core (184 assertions)
cd tests
node run-tests.cjs && node offline-check.cjs && node dom-smoke.cjs
# App suites (29 suites, 1008+ assertions)
node app/run-app-tests.cjs
# Tripwire — the demo is NEVER modified
# Requires sha256sum (Git for Windows / WSL / Linux)
sha256sum -c _overnight/backup/demo.sha256
# Or full gate in one line:
cd tests && node run-tests.cjs && node offline-check.cjs && node dom-smoke.cjs && node app/run-app-tests.cjsTotal: 1192+ assertions, all green. The gate is the hard boundary — never weaken an assertion, never merge red.
Three MCP servers in project/mcp/ (17 tools total) give AI coding agents structured, read-only access to this project — codebase navigation, decisions/handoffs/spec lookup, and git/filesystem helpers. See project/mcp/README.md for wiring instructions.
ahd/
├── app/ # The publishable app
│ ├── index.html # Entry point
│ ├── app.js # Screen registry + router
│ ├── app.css # RTL-first styles
│ ├── engine.js # Generated: byte-faithful engine copy
│ ├── build-engine.cjs # Generator: reads demo → writes engine.js
│ ├── features/ # Pure DI feature modules (12)
│ └── screens/ # Screen renderers (12)
│
├── demo/ # Frozen presenter demo (NEVER edit)
│ └── index.html # Tripwire-pinned SHA-256
│
├── tests/ # Test harness — the quality gate
│ ├── run-tests.cjs # Core demo logic tests (135)
│ ├── offline-check.cjs # Zero network seams (9)
│ ├── dom-smoke.cjs # Headless render + robustness (40)
│ ├── load-logic.cjs # Engine slicer
│ └── app/ # App test suites (29 files)
│
├── promo/ # Remotion motion promos
│ └── out/ # Rendered MP4s
│
├── docs/ # Product & technical documentation
│ ├── ARCHITECTURE.md
│ ├── PRESENTER-GUIDE.md
│ ├── DECK-DRAFT-AR.md
│ ├── DECISIONS-FOR-MARWAN.md
│ ├── PUBLISHABLE-PRODUCT-SPEC.md
│ ├── DESIGN.md
│ ├── specs/ # Feature design specs
│ ├── evidence/ # Graded evidence, rebuttals, survey kit
│ └── research/ # Source materials, AMAD dossier, prompts
│
├── _meta/ # Process artifacts (not core product)
│ ├── deep-work/ # Backend specs, hardening reports, ledger
│ ├── handoffs/ # Agent handoff logs
│ ├── agent-presence/
│ ├── archive/ # Retired files, old prototypes
│ ├── overnight-log.md
│ └── STATUS.md
│
├── project/ # Dev/agent tooling, not core product
│ └── mcp/ # 3 MCP servers (17 tools) for AI-agent access
│
├── _overnight/ # Demo backup + tripwire
├── README.md
├── docs/DESIGN.md
└── CLAUDE.md
| Verse | Application |
|---|---|
| البقرة 2:282 | «يا أيها الذين آمنوا إذا تداينتم بدين إلى أجل مسمى فاكتبوه» — Write the debt. Ahd's foundational mandate: the bank witnesses and records. |
| البقرة 2:280 | «وإن كان ذو عسرة فنظرة إلى ميسرة» — If the debtor is in hardship, grant them respite. Ahd never charges late penalty, never counts days to the debtor, enables إبراء. |
The two-contract model: The loan (قرض حسن, no increase) and the service fee (أجرة الخدمة, fixed, not a percentage of principal) are separate contracts — never conditional on each other. This is the structural guard against riba.
No fatwa from AI. Shariah questions are flagged in DECISIONS-FOR-MARWAN.md and deferred to scholars. This codebase documents the model; it does not issue rulings.
- Bank witnesses/seals/settles/nets; does not lend, judge, charge on the loan, or score.
- No riba / penalty / maysir / gharar. Integer halalas, never float money.
- Trust signal is a qualitative own-history word — never a number, never exported, never underwrites.
- AI issues no fatwa — cite scholars/standards/verses; flag, don't rule.
- "Late" is amber, never red. Dignity over everything.
- The demo (
demo/index.html) is frozen — never edited, pinned by tripwire.