User guide

1. About this platform

This is the officer portal for the ECOWAS Brown Card Scheme — the digital system that member countries, National Bureaux and insurers use to underwrite motor policies, issue and validate Brown Cards, capture evidence, handle claims, and give regulators oversight of the whole scheme. This deployment is operated by Sierra Leone Insurance Commission.

The platform is role-based: what you can see and do depends on your role and your institution. This guide covers the roles and operations available on this deployment — your own workspace only ever shows the parts your role is permitted to use. Where a screen below is missing for you, your role does not carry that permission, or the feature is not enabled here.

2. Getting started

• Sign in with your work email and password at the portal login page. Your session is held in a secure, http-only cookie. If your account requires two-factor authentication, you enter a one-time code after your password.
• Accounts are created for you by an administrator at your institution, who emails you an invitation or set-password link — you do not self-register.
• Forgotten password — use the “Forgot your password?” link on the login page; a reset link is emailed to you. A locked-out account is re-enabled by your institution admin.
• Security & language — from the avatar menu → Profile you can change your password, enable two-factor authentication, and set your interface language (English, French, Portuguese).

1. Go to the portal login page (your administrator sends you the link).
2. Enter your work email and password.
3. If two-factor is enabled, enter the one-time code from your authenticator app or SMS.
4. You arrive at your dashboard — the home workspace for your role.

3. Finding your way around

• Left sidebar — your navigation, grouped into pillars, plus — for admins — an Administration & Integrations area. It only lists the screens your role can open, so your pillars match your job.
• Workspace — every role lands on a home workspace suited to its job. Users who wear more than one hat get a workspace switcher in the top bar.
• Top bar — page title and breadcrumb on the left; the notifications bell and your avatar on the right. The avatar menu holds Profile, this guide, and Sign out.
• Registers open search-first: set filters (date, country, institution, status), press Find/Load, then page through the results.

4. Institutions & how they fit together

The scheme is a hierarchy of institutions, each isolated from its peers:

• ECOWAS Secretariat — the scheme apex. Oversees every institution, sets the Brown Card fee and scheme settings, and reads the whole scheme’s data. Does not underwrite, claim or capture itself.
• National Commission (regulator, where present) — supervises the insurers in its country and publishes the premium tariff and the certificate/sticker design.
• National Bureau — the border / Brown Card authority for a country. Records border crossings, issues and validates Brown Cards, and oversees its member insurers.
• Insurance company — underwrites policies, handles claims, onboards customers and captures vehicle evidence. Insurers never see each other’s data.

Visibility follows the tree, and data flows upward. You read your own institution and everything beneath it, never institutions beside you. An insurance company runs in its own deployment; its policy and claim data reaches the ECOWAS Secretariat only by being relayed up through the national commission — the secretariat sees scheme-wide oversight data without operating the commissions or insurers itself. Writing is always own-institution only — an administrator creates the institutions directly below them and their first admin, who then manages their own staff.

5. Every role at a glance

Roles are scheme-neutral and grouped by institution. Each carries a fixed ceiling of permissions; an administrator can narrow a person further with a role profile.

Commission (national regulator & border authority)

• Commission Admin commission — licenses and provisions member insurers, authors and publishes the premium tariff, designs the certificate and sticker, allocates Brown Card stock and configures payments.
• Commission Analyst / Auditor commission — oversight and audit across the commission’s member insurers: reads their relayed policy/claim data, reviews AI results, runs reports and places legal holds.
• Border Officer border — records border crossings (entry/exit) with photo evidence and verifies a vehicle’s cover at the border (mobile-first).
• Guarantee Card Officer border — issues, validates and revokes Brown Cards, and routes cross-border claims.

6. Administration & user management

Who: Platform Admin, and every institution’s Admin role.

• Create institutions — the Platform Admin creates the top-level institutions; each institution admin then registers the institutions directly beneath them and assigns each its first admin.
• Manage your team (Administration → Team) — invite staff, assign roles, reset passwords and deactivate leavers. You only ever manage your own institution’s users.
• Role profiles — define a narrowed set of permissions and apply it to a person, so you can grant less than a role’s full ceiling.
• Institution settings — your name, logo, branding, contact details, default language, two-factor (SMS) provider and AI/detection settings.

1. Open Administration → Team in the left sidebar.
2. Click Add user (top right).
3. Enter the person’s name, work email and role, then save.
4. They receive an email invitation with a link to set their password.
5. To revoke access later, open their card and choose Remove.

7. Scheme & Brown Card configuration

Who: Commission Admin.

• Card fee & branding — set your country’s Brown Card / scheme fee and override the certificate and portal branding.
• Cover schedules / tariff — author and publish the versioned premium tariff that underwriters rate against.
• Certificate design & Sticker Studio — design the Brown Card certificate and the windscreen sticker; issued certificates pin the published version.

8. Certificate stock

Who: Commission Admin.

• Allocate & price stock — issue Brown Card stock to your member insurers, and configure the payment gateway and pricing for their purchases.

9. Border crossings & Brown Cards

Who: Border Officer, Guarantee Card Officer; the Commission Admin rosters shifts.

• Record a crossing — a border officer logs an entry or exit for their posted direction, with the Brown Card and vehicle photographed.
• Verify cover — scan a Brown Card QR to confirm a vehicle’s policy is in force at the border.
• Brown Cards — the guarantee-card officer issues, validates and revokes cards and routes cross-border claims between bureaux.
• Border shifts — a supervisor/admin rosters officers onto posts, directions and time windows.

1. On the mobile app, start a border crossing for your posted direction (entry or exit).
2. Scan or photograph the Brown Card and the vehicle.
3. Verify the vehicle’s cover is in force — the crossing is recorded as evidence and rolls up to the secretariat.

10. Vehicle intelligence & AI

Who: analysts, supervisors, officers and inspection staff.

• AI plate reads — automatic licence-plate recognition you can confirm or correct.
• Identity matching — vehicles are matched on multiple signals (never the plate alone); you review and record the match decision as a separate record.
• AI insights — damage and base-vs-incident comparisons that support, but never replace, a human decision.

1. Open a vehicle or capture from the Vehicles register.
2. Review the AI plate read; if it is wrong, correct it.
3. Review the identity match (multi-signal), then confirm or adjust and record the decision.
4. Your correction is saved as a new, append-only record — the original AI output is kept.

11. Oversight, reports, audit & legal holds

Who: analysts, supervisors, auditors and regulator viewers.

• Dashboards / Oversight — KPIs and trends across your subtree (policies, claims, crossings, Brown Cards, premiums), scoped to a date range.
• Reports — filter by period, country and institution and export for board packs, regulators and reconciliation.
• Audit ledger — the hash-chained custody trail; auditors verify the chain and place legal holds to preserve evidence beyond normal retention.
• Audit log — the record of inbound integration (CMIS) requests and platform actions.

1. On the Dashboard, set the date range to scope every figure to a period.
2. Open Oversight → Reports, pick a report (claim, underwriting or border) and export it (EN/FR/PT).
3. To preserve evidence for an investigation, open the Audit ledger, find the capture and place a legal hold.

12. Integrations & data relay

Who: institution Admins.

• Integration keys — issue API keys so a partner’s core system can push policies/claims in (CMIS ingest).
• Commission / Secretariat relay — insurers and bureaux relay their policies and claims up the tree so regulators keep complete registers.
• Police, payments & registry — connect the police/traffic evidence platform, the payment gateway, and national ID / business registries. Tenant isolation holds end-to-end.

1. Open Integrations → Integration keys and click Issue a new key.
2. Name the key and choose the institution it is for (one of your member insurers / bureaux).
3. Tick only the modules it may use — for policy/claim relay, Policy & claim ingest (`ingest:write`).
4. Save and copy the key now — it is shown only once, then give it to that institution so it can push its data up to you.

1. The commission relays its member insurers’ policies and claims up to the General Secretariat (a standalone insurer can relay its own here too).
2. Ask the Secretariat for a Secretariat ingest API key — it issues a per-country key from its Integration keys page.
3. Open Integrations → Secretariat integration, enter the secretariat base URL and paste the Secretariat ingest API key.
4. Turn on Relay policies & claims to the secretariat and Save changes — new records relay automatically.
5. Use Push existing policies and Push existing claims to backfill older records.

1. Open Integrations → Integration keys and click API documentation (top of the page).
2. The machine-readable CMIS API reference opens — it documents the ingest endpoints (policies, claims, evidence), authentication and webhooks.
3. Your developers integrate a standalone core system against it, authenticating with the CMIS ingest API key above.

13. Evidence integrity & data isolation

The platform enforces evidence-grade guarantees you can rely on in disputes:

• Append-only / immutable — photos, metadata, AI output and decisions are never overwritten; corrections are new records and the original always survives.
• WORM storage — originals are written once and cannot be changed or deleted, with separate cryptographic and perceptual hashes.
• Hash-chained custody — each custody event links to the last, so any tampering is detectable.
• Tenant isolation — row-level security walls off each institution’s data; you see beneath you in the tree, never beside you.

14. Getting help

Start with the relevant section above. If a screen behaves unexpectedly, note the page and what you did, then contact your institution’s administrator or the platform operator. Account problems (locked out, lost two-factor device) are resolved by your own institution’s admin from Administration → Team.