Shared Fraud Database (working title: Fraud Registry)

Multi-tenant web application for authorized member organizations to contribute confirmed/suspected commercial fraud records and screen new applications and vendors against a shared pool. Built to the requirements in Fraud-DB-Web-Application-Requirements-v2.md.

• Owner: Beacon Funding Corporation
• Stack: Python 3.10+ · Django 5 · PostgreSQL 15+ · Gunicorn
• Hosting: internal application on Debian; Gunicorn on an open port over the internal network. Network ingress/egress and TLS are a deferred, separate decision.
• See ARCHITECTURE.md for decisions and open items, DEPLOYMENT.md to deploy, MATCHING.md for the matching algorithm.

Hard rule: individual names are permitted; SSNs are prohibited and rejected at capture in every field, form, and batch row. Bank account numbers are stored hashed and never rendered.

---

What's implemented (maps to the spec)

Spec	Implemented in
§3 Roles, entitlements, give-to-get	apps/accounts, apps/governance
§4 All 11 screens	templates/, per-app views
§5.1 Submit Fraud Record	apps/records (form + inline formsets, SSN reject, evidence)
Admin-configurable extra fields (beyond spec)	apps/records/custom_fields.py — Platform Admin only, see ARCHITECTURE.md D9
§5.2 Single Lookup	apps/screening/views.single_lookup
§5.3 Batch (CSV, async)	apps/screening + run_batch_worker command
§5.4 Disputes	apps/disputes
§5.5 User provisioning	apps/accounts
§6 Schema	apps/*/models.py
§7 Matching engine	apps/screening/engine.py
§8 Audit, security, export	apps/audit, export_all command, deploy/

Out of scope per the spec: real-time screening API and automated partner batch ingestion (separate interface spec). The manual file-upload batch screen is built.

---

Local development quickstart

Requires Python 3.10+ (3.11 is what Debian 12 ships; any 3.10+ works) and a local PostgreSQL 15+.

python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env                                # edit DB creds + secrets
# For local dev set DJANGO_DEBUG=true in .env (serves static via finders and
# skips the collectstatic/HSTS/secure-cookie behavior meant for production).

# Create the database (example). This assumes your local Postgres role has
# superuser/CREATEDB rights, which is the common case for a local dev install — if
# yours doesn't, see DEPLOYMENT.md §1 for the ownership + extensions handling.
createdb fraud_registry

# Extensions FIRST (creates pg_trgm, fuzzystrmatch, unaccent, pgcrypto), then the rest.
# Every app except core currently ships with an empty migrations/ — makemigrations
# generates the real migration files for the first time here. If none exist yet in
# your checkout, COMMIT the files it writes under apps/*/migrations/ right after
# this succeeds (`git add apps/*/migrations/*.py && git commit`) — from that point
# on, migrations arrive via git like any normal Django project, and this step
# becomes a no-op (nothing to generate) unless you've just changed a model yourself.
python manage.py makemigrations
python manage.py migrate core
python manage.py migrate

# Reference data (+ optional demo tenant)
python manage.py seed_data --demo
python manage.py createsuperuser        # Platform Admin

python manage.py runserver

Then sign in at /auth/login/. First sign-in forces MFA (TOTP) enrollment. Run the batch worker in a second terminal to process CSV uploads:

python manage.py run_batch_worker --loop

Note: this repository was authored on a Windows workstation without a local Python/Postgres runtime, so migrations were never generated or verified here — the first makemigrations run (above, or in DEPLOYMENT.md) is genuinely the first time they're created. Commit them once they exist rather than regenerating them on every deploy — see the callout in DEPLOYMENT.md §2 for why that matters for upgrades. See DEPLOYMENT.md §Verification for the exact commands to validate the build on Debian.

---

Project layout

config/            Django project (settings, urls, wsgi/asgi)
apps/
  core/            validators (SSN reject), normalization, extensions migration, dashboard
  accounts/        members, custom user, roles, channel entitlements, MFA, RBAC, middleware
  records/         fraud records + normalized identifier tables, submit/edit
  screening/       matching engine, single lookup, batch jobs + worker
  disputes/        dispute submission, review queue, SLA
  governance/      reciprocity rollup, query-access controls
  audit/           immutable audit log
templates/         server-rendered UI (WCAG 2.1 AA, status coloring)
static/css/        design system
deploy/            guardrailed deploy scripts + systemd units + backup script:
                     gen-secrets.sh   fill the 3 secret fields in .env
                     check-env.sh     report any .env field still a placeholder
                     setup-db.sh      create DB + role + extensions (idempotent)
                     install.sh       venv, migrate, seed, first superuser
                     upgrade.sh       apply a code update + restart services
                     *.service        systemd units (app + batch worker)
                     backup.sh        encrypted DB backup

For a production deploy, follow DEPLOYMENT.md — the scripts above make it largely copy-paste and are safe to re-run. Placeholder fields in .env are all marked REPLACE_ME; deploy/check-env.sh lists any that remain.