# I Learn — Compliance, Security & Investor Readiness

This document is the single source of truth for diligence questions. Keep it in
sync with `src/lib/compliance.ts`, which drives the public `/compliance` page.

## 1. Legal registration & licensing

The company only offers a regulated activity in a market once the relevant
authorisation has been granted. Statuses:

| Status | Meaning |
| --- | --- |
| `preparing` | Filing being prepared; regulated service not offered publicly in that market. |
| `in_review` | Application filed with the regulator; awaiting decision. |
| `registered` | Authorisation granted; licence number recorded in `reference`. |

Update procedure:

1. Obtain the licence/registration number and regulator decision letter.
2. Edit the matching entry in `src/lib/compliance.ts` — set `status` and `reference`.
3. Store the decision letter in the company data room (never in the repo).

**Rule: never set a status to `registered` without a licence number on file.**
No certification, audit outcome or compliance framework (SOC 2, ISO, PCI, GDPR
adequacy, etc.) may be claimed anywhere in the app or marketing copy unless the
company holds the corresponding evidence.

Corporate items to maintain alongside the register: certificate of
incorporation, UBO register, AML/CFT policy, sanctions screening policy, data
protection notice, terms of service, complaints procedure.

## 2. AI & security verification (implemented today)

**Identity verification (KYC)**
- In-app live document scanner: edge detection, auto-crop, blur/partial-capture rejection.
- AI vision model reads the document and extracts type, number, holder name, issuing country, expiry.
- Automatic rejection for: not an identity document, visible tampering, expired, illegible, or document number mismatching the member's entry.
- Low-confidence or inconclusive scans fall back to the human review queue in the admin panel — never auto-approved.
- Accepted documents: passports, national IDs, driving licences, residence permits and voter cards across 54 African countries and 19 European corridors.
- Code: `src/lib/kyc-verify.server.ts`, `src/lib/kyc-verify.functions.ts`, `src/lib/kyc-rules.ts`, `src/components/DocumentScanner.tsx`.

**Authentication & access control**
- Email/password auth with server-verified sessions on every server function.
- Row-level security on all user tables; helper role functions live in a private schema with direct execution revoked.
- Roles stored in a dedicated `user_roles` table (never on profiles).
- Admin panel behind a secret PIN gate with a signed HTTP-only cookie.
- Identity documents in a private storage bucket with scoped read policies.

**Anti-fraud & transaction monitoring**
- KYC-approved and non-suspended status enforced server-side before exchange, transfer or trade.
- Wallet movements are atomic and row-locked (`apply_wallet_movement`), writing balance + ledger together.
- Post-write reconciliation: posted balance compared against the newest ledger row; mismatches logged.
- High-value tickets run compliance checks against recent activity and write an audit event.
- Exchange rates are admin-approved and applied server-side; client-supplied prices are ignored.
- Code: `src/lib/wallet.server.ts`, `src/lib/enterprise.server.ts`, `src/lib/corridor.server.ts`.

## 3. Investor-ready infrastructure

- **Multi-country routing:** PAPSS local-to-local settlement, XOF (UEMOA) and ZAR fixed-rate zones, bank/mobile-money/IBAN/agent-cash rails.
- **Ledger:** every credit and debit stores amount, kind, reference, funding source and resulting balance — any balance is reconstructable.
- **Admin monitoring:** real-time feed of signups, KYC decisions, transfers, exchanges, marketplace and ledger activity, plus aggregate volumes.
- **Trade tracking:** marketplace orders, cross-border payments and cash-pickup requests each carry a status trail and recorded settlement route.
- **Platform:** TanStack Start on an edge runtime with a managed Postgres backend, automated migrations and per-request auth.

## 4. Reporting a vulnerability

Security issues can be reported through the in-app Support screen. Include
reproduction steps; do not include third-party personal data.

## 5. Business & enterprise registration (KYB)

Corporate members trade under a verified legal entity, never an informal
profile. Structured fields are stored in `public.business_entities`:

| Field | Purpose |
| --- | --- |
| `legal_name`, `trading_name` | Registered name and the name used commercially. |
| `entity_type` | Sole trader, Ltd/SARL, PLC/SA, partnership, cooperative, NGO, licensed financial institution. |
| `registration_number` | National companies-registry reference (CAC, RGD, BRS, CIPC, RCCM, Companies House, EU registers). |
| `tax_id` | TIN / VAT / NIF issued by the revenue authority. |
| `incorporation_country`, `incorporation_date` | Jurisdiction and date of formation. |
| `registered_address`, `business_activity` | Registered seat and the activity carried out. |
| `directors` | Register of directors (name, role, nationality). |
| `beneficial_owners` | Every natural person holding 25% or more, with percentage. |
| `document_paths` | Corporate documents held in the private storage bucket. |
| `status`, `risk_rating`, `review_note`, `reviewed_by`, `reviewed_at`, `verified_at` | Verification workflow and decision record. |

Workflow: `draft` → `submitted` → `under_review` → `verified` / `rejected`.
Structural screening (`src/lib/kyb.server.ts`) checks registry-number format,
UBO declaration, register of directors and attached documents before a file can
enter the queue. Decisions are made by a compliance officer in the Super Admin
Panel (Business tab) and are always written to the audit trail.

Member surface: `/business`. Admin surface: `/admin` → Business.
Code: `src/lib/kyb.ts`, `src/lib/kyb.server.ts`, `src/lib/kyb.functions.ts`,
`src/routes/_authenticated/business.tsx`.

### Corporate documentation template

Required for every entity: certificate of incorporation/registration;
memorandum & articles (statuts); tax identification certificate; register of
directors; UBO declaration with identity documents; proof of registered address
dated within three months; corporate bank statement or mandate. A sector licence
is required only where the business activity itself is regulated.

### Licensing register template

Every market entry in `src/lib/compliance.ts` is published with: market,
regulator, regulated activity, filing status, registration/licence number once
granted, evidence held in the data room, and the date the entry was last
reconciled with the regulator's public list. **A status is never advanced
without the underlying evidence on file.**

## 6. KYC/AML audit trail

`public.compliance_audit_events` is append-only: the table grants no update or
delete privilege to any role, and there are no update/delete policies. Members
may read events about themselves; administrators may read all.

Recorded: identity decisions, corporate filings and status changes, compliance
officer decisions with note and identity, high-value ticket tiering with risk
score and per-check outcomes, and every wallet posting with resulting balance.

Institutional investors and high-net-worth members can request an export of the
trail covering their own account and entity for their diligence file.

## 7. Regional trust architecture (Africa)

- **Cross-border trade security** — counterparties trade under a verified registry number, with directors and beneficial owners on file.
- **Local regulatory alignment** — one register entry per market naming the regulator and the exact regulated activity; where a filing is not granted, the regulated service is not offered there.
- **Transparent fund protection** — atomic, row-locked balance + ledger writes with post-write reconciliation; any balance is reconstructable.
- **Local-currency settlement** — PAPSS local-to-local routing plus the XOF (UEMOA) and ZAR fixed-rate zones, avoiding USD conversion exposure.

## 8. Corporate identity record (published)

| Field | Value |
| --- | --- |
| Legal name | Haven Global Exchange Ltd. |
| Trading name | I Learn (Haven Global Exchange) |
| Registration number | HE-984210 |
| Country of incorporation | United Kingdom |
| Date of incorporation | 14 October 2024 |
| Registered office | 71-75 Shelton Street, Covent Garden, London, WC2H 9JQ |
| Tax identification number | GB984210332 |

No regulator licence has been granted to date. Every market in the licensing
register therefore remains at `preparing` or `in_review`, and no regulated
activity is offered publicly in those markets until authorisation is granted.

## 9. Public data room

The portal at `/compliance` publishes: the data-room index (`DATA_ROOM_INDEX`),
the corporate identity record (`COMPANY_RECORD`), the licensing register, the
KYB verification layers, the corporate documentation template and the
audit-trail scope. This file is served for download at `/COMPLIANCE.md`.
Update `public/COMPLIANCE.md` whenever this file changes.