PRD V1 consolidated and enriched¶

Assisted renewal platform for brokers and insurers¶

Version 1.3 - Functional, business, compliance, security and field scoping¶

Change Log¶

Version	Date	Change
1.1	2026-05-20	Initial consolidated V1 PRD (frozen as reference for V0 re-scoping).
1.2	2026-05-28	Added V1 Sub-Version Contract (§10bis, 8 sub-versions v1.0.0 → v1.1.0 on a 2-week release cadence layered on top of v0.1.0), per-module scope-change tables vs V0 end-state (§10ter), V1 cross-cutting deltas (§10quater), Sub-Version → Module → Story mapping, V1-specific Open Questions + Temporarily Validated (§10quinquies). Sequencing locks correction workshop + anomalies first; BILL slides to v1.0.2/v1.0.3. Updated §6 (explicit non-objectives) and §28 (indicative business priority order superseded by §10bis).
1.3	2026-05-29	Post-merge rework of §10bis–§10quater. N1: renumbered V1 story IDs from `<PREFIX>-V1-NNN` to `<PREFIX>-NNN` continuing V0 numbering (version carried by the `[V1.0.x]` tag). B1: AUDIT compliance-reports delta now extends the existing V0 `AUDIT-003` stubs instead of introducing them fresh. B2: FNE applicability derived from `country_code`/country-profile lookup — removed the settable per-tenant `fne_enabled` field. N2: removed the incorrect claim that the v1.0.3 Platform Admin Console replaces V0 §5.8's cabinet-admin delegation UI. N3: softened the ING validation-rules delta to reflect V0's incremental restoration. N4: reconciled the story-count estimate to 31.

1 Purpose of the document¶

This document defines the consolidated and enhanced scope of Papillon Collection Software V1: an assisted renewal platform for brokers, structured networks and, eventually, insurance companies. V1 is aimed primarily at small and some medium-sized firms, with :
- a simple integration mode based on the import of standardized files, - strong operator supervision, - a light customer experience, - official merchant payment - and realistic operation in contexts of imperfect connectivity

The paper covers: - the business problem ; - the value proposition ; - target users; - functional scope of V1 ; - business rules ; - compliance and security requirements ; - technical constraints ; - success indicators; - explicit V1 dependencies and exclusions.

2. Context¶

In many brokerage firms and insurance agencies, contract renewal remains largely manual: - telephone calls, - whatsApp messages, - transmission of documents by courier, - payment to an agent's personal mobile money number, - or even by bringing the customer to the agency.

The result is poor traceability, limited productivity, a mediocre customer experience and risks in terms of data, proof and collection.

The regulatory context has become more structured with CIMA Regulation 01-24 on the distribution and management of insurance contracts by digital means,
which provides a framework for the digital activities of insurers and intermediaries, and with Ivorian law n°2013-450 on the protection of personal data, which imposes strong obligations on processing, formalities and security.

3. Problem to be solved¶

V1 must address this central problem:

How to enable a firm or agency to detect contracts close to expiry, contact customers remotely, enable them to renew and pay simply, and then track status without depending on an advanced ERP or dispersed manual processes?

This problem can be broken down into six sub-problems: - lack of reliable automatic detection of contracts to be renewed ; - lack of a unified dunning process ; - no secure link between notification and customer action; - lack of integrated merchant payment; - lack of visibility for the operator on payments and failures; - lack of traceability and compliance framework.

4. Product vision¶

The product is an assisted renewal platform that plugs on top of existing systems. It is not a full ERP, but a business orchestration layer between the practice data, the communication channels, the customer portal and the payment module. cite:50]

The core flow is as follows: 1. ingestion of customer and contract data; 2. selection of expiring contracts ; 3. operator validation ; 4. sending of notifications ; 5. light customer-side authentication ; 6. consultation of contracts up for renewal; 7. payment via an official merchant channel; 8. follow-up, reminder and exception handling [cite:46]

5. V1 objectives¶

Business objectives¶

Significantly reduce manual reminders by phone and free WhatsApp.
Reduce customer trips for simple renewals.
Provide operational visibility on due dates, shipments, payments and failures.
Enable structured collection via an official merchant channel.[cite:46]

Product objectives¶

Offer a payment path that can be used by a small practice without an ERP API.
Enable pilot implementation in just a few days.
Create a technical foundation that can be extended to a multi-agency and API V2.

Compliance objectives¶

Position the platform as a technical service provider for brokers and insurers, and not as an independent insurance distributor. ### Compliance objectives
Supervise the processing of personal data in accordance with applicable Ivorian law.
Provide sufficient traces for proof, audit and reconciliation of payments.

6. Non-objectives V1¶

V1 is NOT intended to : - replace the insurer's or broker's ERP ; - manage the entire contract life cycle; - support all types of complex insurance products from the outset; - provide advanced or qualified electronic signatures; - manage complex underwriting workflows; - offer multiple customized ERP connectors from V1 onwards; - support a complete offline transactional mode; - immediately serve all companies as an enterprise solution; - consolidate multiple tenants under a group / holding for cross-tenant reporting and admin — this is a V2 concept; - offer SCHEMA-per-tenant or DATABASE-per-tenant DB profiles — deferred to V3; - migrate tenants between DB profiles (A→D migration) — deferred to V2; - ship a native mobile application — V1 ships a mobile-first responsive web client only; - offer USSD or alternative payment routes outside the standard merchant channels.

7. Target users¶

Admin cabinet¶

Responsible for settings, general supervision, imports, rules and users.

Agency operator¶

Daily business user. Checks lists, corrects anomalies, validates shipments, monitors payments and failures.

Supervisor / Management¶

Consults dashboards, status and campaign results.

Assured end customer¶

Receive notification, confirm identity, view contracts, choose what to renew and pay.

External partners¶

Payment providers, possibly messaging providers, and later data or ERP providers[cite:46]

8. Segment and priority use cases V1¶

Priority segment¶

Small brokerage firms, then intermediate firms.

Priority use cases¶

Remote renewal of recurring, relatively standard contracts, with few structural changes between two periods.

Why this choice¶

This segment has a high level of pain, few tools and accepts more easily a simple Excel/CSV integration mode. This makes it possible to quickly validate the value of the product before moving on to structured networks and companies

9. Value proposition V1¶

For the firm : - more files renewed ; - fewer manual reminders; - better visibility of due dates and payments; - less dependence on informal practices.

For the end customer : - less travel ; - simple route; - ability to pay remotely via an official channel

For partners: - scalable architecture and concrete vertical market, in a framework compatible with the increasing digitization of insurance and payment flows.[cite:46]

10. Design principles V1¶

Small broker first: V1 must work with a simple file export.
Human-in-the-loop: no automatic sending without human validation.
Compliance by design: compliance and security are not added at the end.
Data quality first: data quality is a core product issue.
Official payment only: no cashing out on agent's personal account[cite:46]
Traceability first: all important actions must be logged.
Mobile-first client side: the client portal is designed primarily for entry-level Android smartphones.
Low-bandwidth and resumable by design: the customer journey must remain usable over a degraded network, with session and payment resumption within the link validity window (72h at V1 end-state; no expiration during V0 sub-versions v0.0.0 to v0.0.5, then 72h locked at v0.1.0 per V0 PRD §5.4). Resumability is preserved by signed-link reuse on the same token, not by extending TTL.

10bis. V1 Sub-Version Contract¶

V1 layers additively on top of V0 (which closes at v0.1.0 per V0 PRD §3). V1 is itself sliced into 8 demonstrable, independently-shippable sub-versions on a 2-week release cadence:

v1.0.0 → v1.0.6 (7 feature increments);
v1.1.0 (V1 GA hardening gate).

Every V1 story is tagged [V1.0.x] or [V1.1.0]. Each sub-version:

ships a feature set that can be demoed to a prospect or pilot customer in its own right;
is non-breaking for the previous sub-version (additive only);
preserves the locked stack (Java 26 / Spring Boot 4 / React 19 / PostgreSQL / Keycloak 26.6+);
carries the V0 day-1 architectural anchors forward without rewrite (see V0 PRD §5).

Calendar baseline: week 0 = v0.1.0 GA. Each row's "Weeks" column is offset from that baseline.

V1 sub-version contract¶

Sub-version	Goal	Key feature	Approx. timeline
v1.0.0	Correction workshop + anomaly management v1: operators fix field-level errors before campaign send; anomalies are typed, classified and resolved through a defined workflow.	Pre-campaign data-quality lever (§12.3 + §19).	Weeks 1–2
v1.0.1	Reminders + cascading SMS fallback: scheduled follow-up sequences with frequency caps and opt-out enforcement; WhatsApp failure cascades to SMS instead of V0's parallel double-send.	§11.7 follow-ups + NOTIF cost reduction.	Weeks 3–4
v1.0.2	BILL foundation: platform → tenant invoicing data model, manual invoice creation + payment recording, monthly cycle for Starter tier, FNE e-invoicing for CI tenants (legally mandatory).	Revenue gate: company can legally invoice tenants.	Weeks 5–6
v1.0.3	BILL automation + Platform Admin Console v1: auto-invoicing per pricing tier (Starter / Growth metric), tenant directory UI, audit-log query UI.	Platform-ops self-service; scales beyond founder-managed tenants.	Weeks 7–8
v1.0.4	Customer auth Niveau 1 (DOB challenge) + form draft persistence: V1 §15.3 Niveau 1 (signed link + date of birth); customer-portal form state survives reload + multi-day outages server-side.	Compliance posture upgrade (closes V0 TV-02 Niveau 1 gap).	Weeks 9–10
v1.0.5	Supervisor persona + cabinet admin delegation: KPI dashboards (§22), SUPERVISOR + READ_ONLY roles activated, multi-admin per tenant.	Unlocks Growth-tier sales (structured networks).	Weeks 11–12
v1.0.6	Operator minimum offline + Email channel + tenant privacy URL: §20 cached list + local notes + corrections preparation; NOTIF Email channel; per-tenant privacy URL override.	Field-resilience, multi-channel, per-controller ARTCI hygiene.	Weeks 13–14
v1.1.0	V1 GA hardening: advanced payment retry + manual reconciliation UI, ARTCI flag operationalization (if grants landed), observability hardening, perf budgets, security review, UAT, pricing-tier enforcement.	V1 GA gate. V2 vision starts after this gate.	Weeks 15–16

Sub-version → Module → Story mapping (indicative)¶

This table is indicative only; the authoritative per-story breakdown is produced by the ANALYST → ARCHITECT → PRODUCT_OWNER pipeline (AI_Development_Workflow.md) per module. Empty cells mean the module has no new V1 work in that sub-version.

Sub-version	ING	CP	OP	PAY	TENANT	AUTH	NOTIF	AUDIT	BILL
v1.0.0	ING-009 (anomaly tagging on import)	(none)	OP-024 (correction workshop UI), OP-025 (anomaly typology + workflow)	(none)	(none)	(none)	(none)	AUDIT-010 (anomaly events)	(none)
v1.0.1	(none)	(none)	OP-026 (reminder scheduling UI)	(none)	(none)	(none)	NOTIF-011 (cascade fallback), NOTIF-012 (reminder cadence + caps)	AUDIT-011 (reminder events)	(none)
v1.0.2	(none)	(none)	(none)	(none)	TENANT-010 (billing profile fields)	(none)	(none)	AUDIT-012 (billing events)	BILL-002 (data model + manual invoicing), BILL-003 (FNE adapter for CI)
v1.0.3	(none)	(none)	OP-027 (platform admin console v1, audit query)	(none)	TENANT-011 (tenant directory UI)	(none)	(none)	(none)	BILL-004 (auto-invoice per tier)
v1.0.4	(none)	CP-038 (DOB challenge), CP-039 (form draft persistence)	(none)	(none)	(none)	AUTH-013 (Niveau 1 challenge wiring)	(none)	(none)	(none)
v1.0.5	(none)	(none)	OP-028 (supervisor dashboards + KPIs)	(none)	TENANT-012 (multi-admin delegation)	AUTH-014 (SUPERVISOR + READ_ONLY enum)	(none)	(none)	(none)
v1.0.6	(none)	(none)	OP-029 (minimum offline cache + notes)	(none)	TENANT-013 (privacy URL override)	(none)	NOTIF-013 (Email channel)	(none)	(none)
v1.1.0	(none)	(none)	OP-030 (manual reconciliation UI), OP-031 (observability)	PAY-004 (advanced retry policy)	(none)	AUTH-015 (ARTCI flag flip)	NOTIF-014 (rate-limit + observability)	AUDIT-013 (compliance reports)	BILL-005 (pricing-tier enforcement)

Story-count estimate: ~31 V1 stories across 9 modules (per the mapping table above). Smaller per sub-version than V0 (V0 averaged ~3 stories per sub-version because every module needed bootstrap; V1 layers on a finished V0 platform).

10ter. Per-Module Scope Changes vs V0 End-State (v0.1.0)¶

Each table describes what V1 adds on top of v0.1.0. Aspects not listed are unchanged from V0.

ING (ingestion)¶

Aspect	V0 end-state (v0.1.0)	V1 scope	Status	Notes
Anomaly tagging	File-level validation only (pass/fail)	v1.0.0: row-level + field-level anomaly tagging on import, feeds OP workshop	New	Implements V1 §19 typology at ingestion boundary.
Validation rules	V0 restores rules incrementally from v0.0.1 (V0 §4)	v1.0.0+: re-enable any V1 §13 + §15 rules still simplified at v0.1.0	Restored	V0 dropped optional fields only at v0.0.0 and added them back incrementally (V0 §4); V1 covers only the residual gap, not the full ruleset from scratch.

CP (customer-portal)¶

Aspect	V0 end-state (v0.1.0)	V1 scope	Status	Notes
Customer authentication	Signed link + phone last-4 (v0.0.2)	v1.0.4: signed link + DOB challenge (V1 Niveau 1)	Upgraded	Closes V0 TV-02 PRÉLIMINAIRE flag on Niveau 1.
Form draft persistence	Server holds draft within session	v1.0.4: drafts persist server-side across multi-day outages	Upgraded	Slow-3G resumability over 72h link lifetime.
Tenant privacy URL	Platform-hosted default page	v1.0.6: per-tenant override (broker-hosted privacy URL allowed)	New	Per-controller ARTCI hygiene for brokers acting as data controllers.
Link validity	72h (v0.1.0 lock)	Unchanged	Carried	§30 acceptance signals already validated at V0 GA.

OP (operator-console)¶

Aspect	V0 end-state (v0.1.0)	V1 scope	Status	Notes
Correction workshop	Inline edit of single rows pre-send (v0.0.2)	v1.0.0: dedicated workshop UI for batch correction with anomaly context (V1 §12.3)	New	The "mini-workshop for assisted manual correction" called out in V1 §12.3.
Anomaly management	None (anomalies surface as ingestion errors only)	v1.0.0: typology, classification, assignment, resolution workflow (V1 §19)	New	First-class entity (`anomaly`) with state machine.
Reminder scheduling	None (single send per campaign)	v1.0.1: scheduled follow-up sequences with frequency caps + opt-out enforcement	New	V1 §11.7. Schedules persisted; cron-driven; respects NOTIF opt-out registry.
Supervisor dashboards	None	v1.0.5: KPI views (§22) — paid renewals, conversion, deliverability, opt-out rate	New	Read-only persona; aggregations over audit + payment + notification tables.
Operator minimum offline	Online-first polling only	v1.0.6: cached list of last push, local notes, prepared corrections (V1 §20)	New	No service worker; lightweight client-side persistence (IndexedDB read-only cache).
Platform admin console v1	None (V0 deferred entirely)	v1.0.3: tenant directory UI + audit-log query UI	New	Platform-ops surface (platform-admin only). Distinct from — and does NOT replace — V0 §5.8's cabinet-admin delegation UI, which stays a tenant-level concern delivered at v1.0.5.

PAY (payment)¶

Aspect	V0 end-state (v0.1.0)	V1 scope	Status	Notes
Retry policy	Minimal auto-retry + observability hooks (v0.1.0)	v1.1.0: advanced retry with backoff + max attempts + manual override UI	Upgraded	V1 PRD §11.6 full retry semantics.
Manual reconciliation UI	None (reconciliation via SOP doc + DB ops)	v1.1.0: operator-facing manual reconciliation UI for stuck payments	New	Closes the "manual fault resolution" requirement in V1 PRD §11.6.

TENANT (tenant-admin)¶

Aspect	V0 end-state (v0.1.0)	V1 scope	Status	Notes
Billing profile fields	None	v1.0.2: `billing_tier`, `billing_cycle`, `invoice_email`, `tax_id`	New	Drives BILL behavior per tenant. FNE applicability is NOT a per-tenant field: it is derived from `country_code` via the country-profile lookup (CI ⇒ FNE mandatory, non-overridable). See §10quater.4 + V0 OQ-X2.
Tenant directory UI	None (platform admin uses Keycloak admin + DB tools)	v1.0.3: platform-admin web UI for tenant listing + status + lifecycle	New	Platform-admin tenant directory only. Does NOT replace V0 §5.8's cabinet-admin delegation UI (a separate tenant-level surface, delivered at v1.0.5).
Cabinet admin delegation	One cabinet admin per tenant (platform admin invites)	v1.0.5: multi-admin per tenant; cabinet admin can invite other admins	New	Self-service onboarding for brokers' internal teams.
Tenant privacy URL	Platform-hosted default	v1.0.6: per-tenant override	New	See CP §10ter row above.

AUTH (identity)¶

Aspect	V0 end-state (v0.1.0)	V1 scope	Status	Notes
Customer auth (challenge)	Phone last-4 (v0.0.2)	v1.0.4: Niveau 1 = signed link + DOB challenge	Upgraded	V1 §15.3 row "Niveau 1". Niveau 2 (OTP) remains out of standard V1 scope.
Role enum	`PLATFORM_ADMIN`, `CABINET_ADMIN`, `OPERATOR` (V0 lived with 3)	v1.0.5: full 5-role enum activated (adds `SUPERVISOR`, `READ_ONLY`)	Extended	`multi-tenant-model.md` 5-role taxonomy fully realized.
ARTCI flag operationalization	Real WA/SMS gated by founder risk acceptance	v1.1.0: flip `feature.artci.phone-auth.granted` if grants landed; otherwise GA without flip and update legal memo accordingly.	Conditional	If grants not landed by v1.1.0, V1 GA proceeds with V0 mitigation set documented as PRÉLIMINAIRE-acknowledged.

NOTIF (notifications)¶

Aspect	V0 end-state (v0.1.0)	V1 scope	Status	Notes
Delivery fallback	Parallel WA + SMS (double-send)	v1.0.1: cascading — try WA first, SMS only on failure	Changed	Cost optimization. Audit log records cascade decision per send.
Reminder cadence	None (single send)	v1.0.1: scheduled reminders with frequency caps (V1 §11.7)	New	Caps configurable per tenant; honors opt-out from any previous send.
Email channel	Out of scope (V0 §12)	v1.0.6: Email channel added (provider per country profile)	New	Activated by tenant flag; opt-out semantics symmetric with SMS/WA.
Rate-limit + observability	Baseline tuning (v0.1.0)	v1.1.0: production-grade rate limiting per provider + delivery analytics	Upgraded	Feeds Supervisor dashboards (v1.0.5) and §22 KPIs.

AUDIT (audit-log)¶

Aspect	V0 end-state (v0.1.0)	V1 scope	Status	Notes
Event catalog	V0 events emitted (full list, no UI)	v1.0.0+: incremental catalog additions for anomalies, reminders, billing, supervisor reads	Extended	Each new event added at the sub-version where its emitting feature ships.
Query UI	None	v1.0.3: platform-admin audit query UI (filter by tenant / actor / event / date)	New	Tenant-scoped + platform-admin views.
Retention policy	No purge	v1.1.0: 7-year retention policy + soft-archival	New	CIMA + ARTCI requirement. Storage tiering may move cold rows to S3-compatible store.
Compliance reports	v0.1.0: stubs already shipped (`AUDIT-003`)	v1.1.0: extend the V0 `AUDIT-003` stubs into ARTCI / CIMA-shaped extracts (`AUDIT-013`)	Extended	Builds on the existing V0 `AUDIT-003` compliance-report stubs; final format TBD per regulator template.

BILL (billing) — new in V1¶

Aspect	V0 end-state (v0.1.0)	V1 scope	Status	Notes
Module presence	Out of scope	v1.0.2: module activated	New	Control-plane module; platform-tenant boundary, NOT customer-tenant.
Invoicing flow	None	v1.0.2: manual invoice + payment recording; v1.0.3: auto-invoice per pricing tier	New	Pricing tiers from V1 §29 (Starter fixed sub + Growth volume metric).
FNE e-invoicing (CI)	None	v1.0.2: mandatory FNE integration for CI tenants	New	DGI requirement. Equivalent regimes in SN/BJ deferred until first tenant in those countries.
Pricing-tier enforcement	None	v1.1.0: usage thresholds enforced (cap warnings, overage tracking)	New	Reads from `tenant.billing_tier` + monthly usage aggregates.

10quater. V1 Cross-Cutting Deltas¶

Only architectural patterns that change vs V0 are listed. V0 day-1 anchors (tenant-aware datasource resolver, Liquibase multi-profile, async tenant-context propagation, signed-link signing, payment idempotency, audit-log outbox, Keycloak Organizations) carry forward unchanged — see V0 PRD §5.

10quater.1 NOTIF cascade vs parallel send¶

V0 sends WhatsApp + SMS in parallel for resilience; V1 (v1.0.1) cascades: WhatsApp first, SMS only on WA failure or unknown delivery status after a timeout. The cascade decision is audit-logged. Implementation: NOTIF orchestrator wraps both providers behind a cascade policy; opt-out registry consulted before each attempt.

10quater.2 AUTH role enum expansion¶

V0 lives on three operator roles (PLATFORM_ADMIN, CABINET_ADMIN, OPERATOR). V1 (v1.0.5) activates SUPERVISOR (read-only on operational data + KPI dashboards) and READ_ONLY (audit/compliance read-only). Keycloak Organizations group mappers updated; the D-2 enum in AUTH PRD is the source of truth.

10quater.3 Customer-portal Niveau 1 challenge¶

V0 uses phone last-4 as the only identity capture (v0.0.2). V1 (v1.0.4) wires the V1 §15.3 Niveau 1 challenge: signed link + DOB. DOB stored hashed in the customer record at ingestion (ING-009 contract enrichment). Failure budget per link aligned with the V0 attempt-limit (v0.1.0 lock).

10quater.4 BILL outbox + FNE adapter¶

BILL invoices are persisted with a FNE-submission outbox; FNE submission is idempotent + retryable. FNE response (signed receipt) is attached to the invoice record. On failure: alert ops + retry queue. CI tenant invoices CANNOT be considered "issued" until FNE acceptance. FNE applicability is derived from the tenant's country_code via the country-profile lookup, never stored as a settable per-tenant flag — a tenant whose country_code = CI is FNE-mandatory and this cannot be disabled. The country-profile FNE endpoint shape is tracked by V0 OQ-X2.

10quater.5 Operator offline cache (V1 §20)¶

A lightweight IndexedDB cache stores the last fetched campaign list + operator-local notes + prepared correction drafts. The cache is read-only with respect to backend state (no conflict resolution). Sync resumes on reconnect. NOT a service worker; no offline-first claim.

10quater.6 Audit retention + archival¶

V0 has no purge. V1 (v1.1.0) introduces a 7-year retention policy. Implementation pattern: hot table (audit_entry, indexed) + cold archive (compressed Parquet or equivalent on S3). Read paths: hot-only for operational queries; hot+cold for compliance extracts. Cold archive is append-only and tenant-scoped.

10quinquies. V1 Sub-Version Open Questions & Temporarily Validated¶

Open questions¶

ID	Question	Module	Owner	Resolution gate
V1-OQ-01	Pricing-tier numbers (Starter monthly fee, Growth per-contract metric pricing, Email/SMS overage rates)?	BILL	Founder + Sales	Required before v1.0.2.
V1-OQ-02	FNE integration partner (direct DGI API vs intermediary like Sage / Smart-DGI)?	BILL	Founder + Legal	Required before v1.0.2.
V1-OQ-03	Email provider per country (SendGrid / SES / local provider)?	NOTIF	ARCHITECT (NOTIF)	Required before v1.0.6.
V1-OQ-04	Exact permission matrix for SUPERVISOR vs READ_ONLY (what KPIs can SUPERVISOR drill into; can SUPERVISOR export?)	AUTH + OP	ARCHITECT (AUTH)	Required before v1.0.5.
V1-OQ-05	ARTCI grant timing — does v1.1.0 flip the flag or proceed without?	Compliance	Founder + Legal	Decision at v1.1.0 cut.
V1-OQ-06	Reminder cadence default (3 reminders at D+3 / D+7 / D+14? configurable per tenant?)	NOTIF + OP	Founder + Pilots	Required before v1.0.1.
V1-OQ-07	Anomaly resolution SLAs (do anomalies have an aging policy that escalates?)	OP	Founder	Required before v1.0.0.
V1-OQ-08	Audit cold-archive storage target (S3 + Parquet vs simple compressed dump)?	AUDIT	ARCHITECT (AUDIT)	Required before v1.1.0.

Temporarily validated¶

Item	Status	Notes	Confirmation gate
FNE adapter behavior under DGI outage (idempotent retry SOP)	PRÉLIMINAIRE	Assumed FNE provides retry semantics; needs pilot validation with a real CI tenant.	Pilot v1.0.2 with first CI tenant.
7-year retention storage cost model	PRÉLIMINAIRE	Cost estimate based on assumed audit-event volume; revisit after v1.0.5 with real production volumes.	Cost review pre-v1.1.0.
Cascade fallback timing (how long to wait for WA before SMS)	PRÉLIMINAIRE	Initial: 60s WA delivery receipt timeout. Revisit after pilot deliverability data.	v1.0.1 pilot retro.

11. Functional scope V1¶

11.1 Data management and ingestion¶

Manual Excel/CSV import.
Imposed file model.
Format and consistency checks.
Import log.
Detection of blocking and non-blocking anomalies.
File deduplication.

11.2. Renewal detection¶

Set to X days before expiration.
Scheduling of selection at least 2 times per week.
Generates a list of candidate files.
Deduplication in case of multiple imports.

11.3 Operator console¶

Task list view.
Filters by agency, date, product, status.
Check and correct certain fields.
Batch or individual shipment validation.
Action history.

11.4. Notifications¶

Send WhatsApp or SMS according to availability.
Customizable templates.
Secure signed links with limited duration.
Sending history.
Failure status.

11.5. Customer portal¶

Access without permanent password.
Light identification: link + date of birth.
View contracts up for renewal.
Partial or total selection, according to rules.
Summary before payment.
Mobile-first layout from 360px width.
Lightweight pages tolerant of slow networks.
Resumable session after loss of connection.

11.6 Payment¶

Payment via official merchant account or web/mobile money API[cite:46]
Generate transaction reference.
Status feedback.
Payment ↔ contract(s) reconciliation.

11.7 Follow-up and reminders¶

View paid, unpaid and failed files.
Automatic weekly reminders, configurable.
Highlighting of files less than 7 days old.
File of failures to be reprocessed.

12. Data sources V1¶

Primary source V1¶

Standardized Excel/CSV import.

Complementary source V1¶

Assisted manual correction within a limited perimeter.

Third operational source: pre-campaign correction workshop¶

Even with a structured import, some files will be incomplete or imperfect: - invalid telephone number, - missing date of birth, - inconsistent amount, - duplicates, - contract already processed, - incorrect agency details. V1 must therefore incorporate a mini-workshop for assisted manual correction enabling the operator to complete or correct a subset of fields before validating the campaign, without transforming the product into a general data entry ERP - correct a subset of fields before campaign validation, without transforming the product into a general data entry ERP.

This flow is essential for the reality in the field: it enables value to be recovered despite imperfect data, while imposing a barrier of human control before dispatch.

Justification¶

ERP APIs sometimes exist, but their availability is not guaranteed. The file mode enables a faster commercial start-up and is better suited to the priority segment; the correction workshop limits the impact of poor-quality exports.[cite:46]

13. Expected import data¶

Minimum mandatory data¶

source customer identifier ;
surname/first name or company name ;
main telephone number ;
date of birth or selected authentication data;
contract identifier ;
type of contract / branch ;
expiry date ;
amount to be paid ;
agency / office.

Desired data¶

email ;
policy number ;
registration / trade reference ;
currency ;
source contractual status ;
additional information required for the message.

Fields calculated by the platform¶

eligibility status ;
notification status ;
customer session status ;
payment status ;
anomaly score ;
operational urgency.

14. Business path V1¶

14.1 Operator path¶

Import a file.
Correct format errors.
Start or wait for the selection of files close to expiry.
Open task list.
Examine anomalies.
Process pre-campaign correction workshop if necessary.
Validate shipment.
Monitor dispatch status.
View payments.
Process failures and reminders.
Report unresolved or critical files.

14.2. Customer journey¶

Receive a message.
Click on the link.
Verify your identity.
View relevant contracts.
Choose what to renew.
See total to pay.
Make payment.
Receive confirmation.

15. Business rules V1¶

15.1 Contract selection¶

A contract enters the queue if its due date is within X days.
X can be configured at cabinet level.
A contract that has already been paid for or marked as processed must not return to the same campaign, unless explicitly authorized.

15.2. Campaigns¶

Campaigns can be generated automatically, but must be validated manually before dispatch.
A campaign keeps track of its date, operator, batch and parameters.

15.3. Customer authentication - gradation of security levels¶

V1 must formalize a progressive security logic, in order to enable a simple process without losing the ability to increase the level of trust according to risk.

Niveau	Mécanisme	Usage recommandé	Statut V1
Niveau 1	Lien signé + date de naissance	Cas standard, faible friction	Inclus en V1
Niveau 2	Lien signé + date de naissance + OTP SMS/WhatsApp	Cas sensibles, montants plus élevés, clients à risque	Prévu pour extension proche
Niveau 3	Question/réponse secrète ou mécanisme complémentaire de secours	Cas exceptionnels, secours si OTP indisponible	Hors périmètre standard V1

Level 1 is the minimum V1 scheme. The number of attempts must be limited, the link must have a limited validity period, and any repeated failure must result in the file being switched to exception status.

15.4. Payment¶

The customer may pay for all or part of a transaction only if the product settings allow this.
A transaction must always bear a unique reference.
A confirmed payment must update the file status.
An uncertain payment must remain in intermediate status until resolved.

15.5. Reminders¶

Weekly reminders can be activated.
Files close to their due date should be highlighted.
A file with a critical anomaly must not be automatically re-run without validation.

16. Compliance requirements¶

16.1. Regulatory position¶

The platform must be presented and documented as a technical service provider acting on behalf of insurers and intermediaries, in accordance with the logic of CIMA regulation 01-24, and not as a stand-alone insurance distributor

16.2. Digital contract and information¶

CIMA regulation 01-24 requires that insurance contracts distributed or managed by digital means comply with the CIMA Code code, and must include specific information on usage, limits, responsibilities, risks, and procedures for contesting and objecting to the contract

V1 must therefore : - provide screens or documents to display the necessary information; - provide for the archiving of proof of consultation or acceptance, wherever possible; - allow insurers/brokers to customize the required texts

16.3. Personal data¶

V1 must be compatible with Ivorian law n°2013-450, which governs personal data processing, formalities and protection measures.

Consequences: - data processing mapping ; - subcontracting contracts with B2B customers; - data minimization ; - management of retention periods ; - logging mechanism; - documentation for formalities and ARTCI compliance

16.4. Payment¶

Payments must be made via official merchant accounts and APIs or services provided for businesses. V1 excludes any payment mechanism based on an employee's personal number[cite:46]

16.5. Proof¶

The product must keep sufficient traces to : - prove the sending of a message ; - prove access to the portal ; - prove payment; - reconstruct the chronology of events of a renewal cycle (notification → authentication → payment) from the audit log.

17. Security requirements¶

Operator authentication (insurance agency or broker)¶

Nominative account required.
Strong passwords.
Connection logging.
Automatic logout after inactivity.

Access control¶

Separate roles: admin, operator, read.
Partitioning by office/agency.
Access restricted to strictly necessary.

Data security¶

Encryption in transit.
Encrypt sensitive data at rest if possible.
Limitation of visible data in the interface.
No unnecessary exposure of full dates of birth if partial masking possible in certain views.

Customer portal security¶

Signed link.
Limited lifetime.
Attempt limitation.
Anti-replay.
Access logs.

Payment security¶

Status check via API/webhook.
Unique transactional references.
Returns integrity verification.

Operational security¶

Backups.
Centralized logging.
Minimal alerts on critical errors.
Incident procedure.

18. Logging and auditing requirements¶

Each of the following events must be logged: - file import ; - import error detection ; - campaign validation ; - notification sending ; - notification failure ; - link opening ; - authentication attempt ; - authentication success or failure ; - payment initiation ; - payment confirmation or failure; - manual modification of a file; - parameter change.

Logs must include at least : - event identifier ; - timestamp ; - initiating user or system ; - file concerned ; - result.

19. Anomaly management¶

Minimum typology¶

missing or invalid phone ;
date of birth missing ;
contract without amount ;
contract already expired ;
duplicate ;
payment status inconsistent ;
payment return impossible to reconcile;
too many authentication failures.

Operational classification of anomalies¶

Type d’anomalie	Effet	Exemple
Anomalie bloquante	Empêche l’envoi ou la poursuite du flux	Téléphone absent, montant absent, identité insuffisante
Anomalie non bloquante	Permet l’envoi avec avertissement opérateur	Email absent, donnée secondaire manquante
Anomalie de surveillance	N’empêche pas l’action mais déclenche suivi	Paiement en attente prolongée, échec de callback

Rules¶

A blocking anomaly blocks shipment;
A non-blocking anomaly can be sent with a warning;
A monitoring anomaly must go up in a specific control queue (= a back-office screen - Anomaly view).
All anomalies must be visible in a dedicated queue.

20. Offline functionalities V1¶

V1 should not promise complete offline operation, but it can provide a minimum base: - consultation of the last synchronized list ; - local note-taking ; - preparation of comments or corrections to be resynchronized; - consultation of call scripts and static information.

The following should NOT be supported offline: - the actual sending of messages, - final validation of a campaign, - final confirmation of a payment - irreversible change of contract status.

21. Interfaces and screens V1¶

Back-office¶

Login.
Dashboard.
Import file.
Import result.
List of due tasks / contracts.
Client file details.
Pre-campaign correction workshop.
Sending validation.
Notification history.
Payment view.
Anomaly view.
Practice parameters.
User management.

Customer portal¶

Secure access page.
Identity verification.
List of eligible contracts.
Payment summary.
Return success / failure / pending.

22. Success KPI V1¶

Business KPI¶

rate of files contacted ;
rate of files consulted ;
payment conversion rate ;
average time between dispatch and payment;
number of files avoiding a trip to the branch.

Quality KPI¶

import error rate ;
invalid number rate;
payment failure rate ;
authentication failure rate;
rate of unreconciled files.

Product KPI¶

onboarding time for a practice ;
average campaign processing time;
pilot operator satisfaction.

23. Hypotheses to be validated in pilot¶

Firms know how to export a usable file with minimal adaptation.
Customers accept a password-free path, based on a secure link + simple personal data.
Payment via an official merchant account really does reduce informal collections.
Operators prefer human validation before dispatch to full automation.
Target industries are sufficiently homogeneous for a simple V1.[cite:46]

24. External dependencies¶

Payment provider / merchant API [cite:46]
SMS channel.
WhatsApp channel or equivalent.
Pilot partners willing to provide real exports.
Legal support for final validation of regulatory package.

25. Risks V1¶

Product risks¶

insufficient data quality ;
too many special cases;
low customer transformation rate if the process is too cumbersome.

Compliance risks¶

data processing not sufficiently framed ;
insufficient regulatory documentation;
ambiguity as to the probative value of the digital trail.

Technical risks¶

payment integration more complex than expected;
variable export quality ;
dependence on messaging service providers.

Go-to-market risks¶

small firms very interested but with low budgets;
strong need for support during initial rollouts.

26. Product decisions to be fixed before build¶

Before launching development, the following points need to be decided: - which branches or products are included in the pilot ; - the exact level of customer authentication in V1 ; - notification channels included in V1; - the payment provider(s) selected; - the official format of the import file; - the portal's minimum legal texts and notices; - log and data retention policy [cite:46]

27. Functional architecture recommendation¶

V1 is built around the following business objects. Every tenant-scoped row carries tenant_id (and agency_id where applicable). tenant.country_code resolves country-specific behavior through country_profile.

Tenant (a single brokerage cabinet; in V2+ each foreign subsidiary is its own tenant). Holds country_code, db_profile, lifecycle status, settings.
Country profile (lookup keyed by country_code): payment providers, notification providers, regulatory authority, currency, fiscal e-invoicing endpoint.
Agency (sub-unit within a tenant, from v0.0.2 onwards).
User (operator: CABINET_ADMIN / OPERATOR / SUPERVISOR / READ_ONLY; PLATFORM_ADMIN cross-tenant. See AUTH PRD D-2 for the locked enum).
Customer (assuré).
Contract (insurance contract).
Échéance (renewal due-date row).
Campaign (cohort + send descriptor; campaign engine is folded into the OP module for V1).
Notification (one SMS or WhatsApp send attempt).
Customer session (signed-link state for a given customer + contract set).
Payment.
Anomaly (data-quality issue surfaced by ING or operator).
Audit entry (immutable, per AUDIT PRD §B.1 catalog).

This modeling is sufficient to launch a V1 without freezing unnecessary enterprise abstractions too early. Note: the previous entity-list ordering in this section was an unranked enumeration; delivery order is decided by the ANALYST + ARCHITECT per §28.

28. Recommended delivery plan¶

V1 is delivered in successive *vertical slices, each providing complete, end-to-end functionality.
There are no isolated "infrastructure" or "data model" sprints. Each table, endpoint and screen is delivered with the story that needs it first.

The detailed breakdown is delegated to the assisted development workflow (AI_Development_Workflow.md):

the ANALYST session produces a PRD per module (docs/prd/<module>-prd.md), consistent with the present V1 document;
the ARCHITECT session breaks down each module into vertical slices and specifies inter-module dependencies;
the PRODUCT_OWNER session produces self-supporting story files, ordered by business value and technical dependencies. This §28 does not specify a delivery schedule - this is decided by the ANALYST session.

Indicative business priority order¶

The V1 sub-version contract (§10bis) is the authoritative delivery plan. The functional-priority order below is preserved for historical reference.

(Historical — pre-V0-rescoping)

Data management - import, validation, correction workshop
Renewal detection + operator console (task list)
Notifications - WhatsApp/SMS sending + signed link generation
Customer portal - authentication + contract view
Payment + reconciliation
Follow-up, reminders, anomaly management

Current V1 delivery order: see §10bis.

29. Appendix - pricing strategy V1/V2/V3¶

The recommended pricing logic should remain simple in V1, easy to understand for small firms and extendable to more structured segments. For new B2B products, a tiered logic by segment and usage metric is more robust than a single price or opaque commission.[cite:46]

Pricing principles¶

Align the price with the value created, i.e. primarily with the number of renewal contracts processed, rather than just with the number of users.
Keep it simple for small firms.
Charge explicitly for integration, multi-agency and more advanced governance in higher versions.
In V1, avoid a direct percentage on the premium, which could blur the perception of the service and complicate positioning.

Recommended structure¶

Offre	Cible	Modèle tarifaire recommandé
Starter	Petits cabinets	Abonnement fixe + plafond d’usage raisonnable
Growth	Réseaux structurés	Abonnement + variable d’usage par volume traité
Enterprise	Compagnies	Minimum annuel + contrat sur mesure + options

Proposed mechanics¶

Primary metric: number of renewal contracts processed per month.
Secondary metric: notification threshold to protect variable costs.
Onboarding fees: recommended as soon as the project includes parameterization, training, data cleansing or specific integration.

This appendix doesn't yet set the amounts, but it does lock in the monetization logic and ensures that this area isn't overlooked later on in the project. cite:46]

30. Connectivity, mobile-first and low-bandwidth strategy¶

30.1. Field context¶

The platform is deployed in Côte d'Ivoire and, potentially, in the CIMA region, where a large proportion of policyholders access the Internet mainly via entry-level Android smartphones, where mobile data can be costly, where 3G remains dominant outside major centers, and where branches regularly experience connection outages or instabilities.

V1 must be designed with these constraints as first-order requirements, not as late optimization details.

30.2. Client side - low bandwidth and session resumption¶

Mobile-first: every client screen is designed for 360-414 px portrait first.
Lightweight payload: target < 200 KB gzip at initial client portal rendering; non-critical resources are deferred.
Aggressive caching on static resources: long TTLs and versioned file names.
Tolerance of slow networks: explicit timeouts and retries on idempotent reads.
Resumable signed links: the validity window is 72h at V1 end-state (V0 PRD §5.4 lock). Resumability is achieved by signed-link reuse on the same token across multi-day outages, not by extending TTL.
Resumable payment: a payment started but whose return is not known must be reconcilable by webhook and status check, without double debit.[cite:46]
Graceful degradation: the portal must clearly signal offline status and never silently lose customer selection.
SMS as backup channel: if WhatsApp or mobile data fails, the same signed link must be able to be delivered by SMS.

30.3. Operator side - minimal offline¶

The back-office is desktop-first and online-first. The minimum offline allowed remains: consultation of the last synchronized list, local notes, preparation of corrections. Campaign validation, payment confirmation and irreversible actions remain outside the offline perimeter in V1.

30.4. Explicit non-objectives for V1 connectivity¶

No native mobile application.
No full offline-first engine with IndexedDB and conflict resolution.
No USSD or alternative payment mechanism outside standard V1 routes.

30.5. Acceptance signals¶

The connectivity strategy is considered satisfactory in V1 if : - the customer portal remains usable on a slow network profile ; - a customer who loses his connection can resume his journey via the same link without having to re-enter everything; - a payment with an uncertain return can be reconciled without double debiting; - operators can prepare or reread their work during a short break without local loss of notes.

31. Operational conclusion¶

V1 must be designed as a product that is simple to deploy, but rigorous in its execution. Its success will depend less on a stack of functionalities than on six foundations: data ingestion quality, pre-campaign correction workshop, operator console clarity, integration of an official merchant payment, robustness of the mobile path in degraded networks, and a serious foundation of compliance, security, logging and proof.[cite:46]