User journeys (story format)

Stories are user-facing: goals, what people see, and what “done” feels like. See UX overview — domain vocabulary for standard terms.

1. First time the organisation uses the product

Who: Org admin (sometimes with IT).

Story: The team wants to reconcile in a live environment, not only in test.

• They create or select a tenant, add or confirm an environment (test vs live), and land in the right context so all lists and jobs use the same scope.
• They complete tenant settings: locale and formats, matching behaviour (auto vs manual, thresholds), job schedules, and any LedgerMatch-related preferences exposed in the UI.
• Done: The tenant feels ready; people know where to add expected rows, incoming data, and colleagues.

Design notes: Onboarding wizard, persistent environment indicator, settings grouped (matching, scheduling, regional, integrations).

2. Signing in and switching context

Who: Anyone.

Story: A user opens the app and must act in the correct tenant and environment.

• They authenticate (your IdP), then pick or confirm tenant + environment (or the app derives them with a clear way to switch).
• Done: Every screen and action is scoped correctly; switching context refreshes data and prevents wrong-environment mistakes.

Design notes: Obvious scope in the header; warn before destructive actions across environments.

3. Bringing people in

Who: Org admin.

Story: Add colleagues with different access levels.

• They invite or register users and assign tenant membership per environment with a role (e.g. can configure vs read-only).
• Done: Each person sees only permitted tenants/environments and the right actions.

Design notes: Short role descriptions; read-only users never hit dead-end primary buttons.

4. Connecting data sources (incoming feed)

Who: Org admin (with credentials from finance or IT).

Story: Incoming transactions must flow in from real systems.

Paths (one or several):

• Stripe (card): Create a data source, store credentials, optional webhook secret, define field mappings, run or schedule sync, read sync logs (counts, errors, partial runs).
• EBICS (bank): Start init, bank letter step (offline), complete when the bank activates keys, run import/sync, map EBICS fields.
• CSV: Upload file (size limits clear); field mappings for csv source; see rows become incoming with pending status.

Done: New incoming rows appear in queues with correct merchant, amount, currency, transaction date, reference, description (and direction when relevant).

Design notes: Connection health, last sync time, plain-language errors, resume for long bank onboarding.

5. Maintaining field mappings

Who: Org admin.

Story: Raw Stripe/CSV/EBICS shapes must map cleanly to the standard incoming shape.

• They open field mappings per source, add or edit rules (merchant, amount, currency, date, reference, description, direction where supported).
• They validate with a sample row or a small test import when the UI allows.
• Done: New syncs and uploads produce trustworthy incoming rows without silent wrong fields.

Design notes: Show target field names (merchant, not “counterparty”); version or “last changed” if multiple admins edit.

6. Defining and maintaining expected transactions

Who: Reconciliation user (often with admin rights).

Story: The expected side must stay accurate for matching.

• Create rows (merchant, amount, currency, expected date, reference, description) or import in bulk if you support it.
• List / filter / search (by reference, date range, merchant).
• Edit when invoices change; delete or void when expectations are withdrawn (align with backend rules).
• Done: The candidate pool for LedgerMatch reflects reality; duplicates and stale rows are visible.

Design notes: Duplicate warnings; empty state: “Add expected transactions before matching.”

7. Entering or correcting incoming manually

Who: Reconciliation user.

Story: A payment arrived but did not come through a feed.

• They create an incoming transaction with manual source and full fields, or edit an existing incoming when policy allows (e.g. fix reference or merchant before re-matching).
• Done: Row is pending and eligible for matching.

Design notes: Clear source badge; show when edits affect existing matches.

8. Daily reconciliation: review matches

Who: Reconciliation user.

Story: Work through incoming that need a decision.

• Open a queue (e.g. pending / unmatched / “needs review”).
• Open incoming detail; see ranked matches to expected rows with confidence and explanations (amount, date, text, reference).
• Accept the correct match or reject with an optional reason; optionally trigger matching if it did not run automatically.
• Done: Incoming moves to matched when accepted; stays pending/unmatched when nothing fits or all candidates rejected.

Design notes: Side-by-side incoming vs expected; “top suggestion” vs alternatives; link to create expected or fix mapping from empty states.

9. Working from the expected side

Who: Reconciliation user.

Story: Finance starts from an invoice they know is unpaid.

• They open an expected transaction and see related matches or incoming candidates (if the UI exposes reverse navigation).
• Done: They can complete reconciliation without only scanning the incoming queue.

Design notes: If the API is incoming-centric only, surface “linked incoming” on expected detail from match data.

10. Browsing all matches

Who: Reconciliation user, read-only user.

Story: Audit or support needs to see decisions already taken or still open.

• List matches with filters (pending / accepted / rejected, by incoming or expected id).
• Open a match record for scores, timestamps, auto vs manual flags.
• Done: Questions like “who accepted this?” or “why was this rejected?” are answerable from the UI.

Design notes: Stable URLs for sharing; export optional.

11. Tuning automation (matching and jobs)

Who: Org admin.

Story: Balance automation vs risk.

• Adjust tenant settings: when matching runs (realtime / batch / hybrid), auto-match, auto-accept thresholds, “only when single candidate”, etc.
• Configure job schedules (matching batch, Stripe sync, webhook retry, cleanup retention) as your product exposes them.
• Done: Behaviour matches policy; ops can predict when work appears in queues.

Design notes: Plain-language presets (strict / balanced / manual-first); show impact preview where possible.

12. Operating jobs

Who: Org admin, sometimes reconciliation user.

Story: Background work fails or must be run ad hoc.

• List jobs by type (matching, Stripe sync, webhook retry, cleanup, …) and status.
• Open a job for error message, duration, last run.
• Trigger, cancel, or retry where supported.
• Done: Failed runs are actionable; stuck runs can be stopped.

Design notes: Link errors to data source, file, or settings.

13. Webhooks to downstream systems

Who: Org admin (with engineering).

Story: Other systems need events when matches or statuses change.

• Create / update / delete webhook definitions; set URL and secrets as required.
• Send test delivery; open delivery history (success/failure, response snippets if safe).
• Done: Integrations stay reliable; failures are visible.

Design notes: Test button prominent; last success / last failure at a glance.

14. API keys for automation

Who: Org admin, engineering.

Story: Scripts upload CSV, trigger sync, or query lists without human login.

• Create an API key (JWT required) scoped to tenant + environment; the response includes a single string pr_<public>.<secret> — store it once; only a hash is kept server-side.
• List keys (metadata, publicId only) and revoke (DELETE) with a JWT when access must end.
• Call business APIs with X-Api-Key (or opaque Bearer) plus matching X-Tenant-Id / X-Environment; use read / write permissions for least privilege.
• Done: Automation is auditable and least-privilege.

Design notes: Copy-once pattern; never show the full secret again after creation.

15. Managing data sources over time

Who: Org admin.

Story: Credentials rotate, connections break, or an integration is retired.

• Edit connection settings, rotate keys, disable sync without deleting history if supported.
• Delete or archive a data source when offboarding.
• Review sync logs for trends (errors creeping up).
• Done: No silent stop of feeds; admins see degradation early.

16. Exception handling and investigation

Who: Reconciliation user, read-only user.

Story: Something looks wrong—duplicate amount, wrong merchant string, missing reference.

• Filter incoming and expected lists; search by reference or amount band.
• Compare suggested match scores; reject and leave notes; add missing expected row or fix field mapping and re-run matching.
• Done: Root cause is visible (data vs rules vs mapping), not “black box.”

Design notes: Tie reject reasons to reporting or future model feedback if product supports it.

17. Read-only access

Who: Read-only user.

Story: Audit views the same truth without mutating it.

• Same lists, detail, logs, match history; create / accept / sync / settings hidden or disabled with explanation.
• Done: No accidental changes; no confusing empty permissions states.

18. Super-admin: cross-tenant operations

Who: Platform or internal support staff with the super-admin role (not tied to a single customer tenant the way org admin is).

Story: Diagnose or fix issues for any tenant without confusing one customer’s data with another’s.

• They sign in with super-admin; the UI makes them choose the active tenant and environment before opening lists or settings (their token is not “stuck” on one tenant).
• They can perform user management across tenants (e.g. assign people to a tenant/environment) where product policy allows—broader than a tenant-scoped org admin, who only manages their own organisation.
• Other screens (incoming, expected, matches, data sources, jobs, etc.) follow the same pattern: always scoped to the selected tenant + environment, with a clear indicator of which customer context is active.
• Done: Support and platform ops can act in the right tenant every time; audit and permissions still enforce who may change what.

Design notes: Persistent “acting as: [tenant] · [environment]” banner; warn before switching context with unsaved work; optional read-only support mode is a product policy choice, not an absence of super-admin.

Next step for design

Use Interaction flows for screen-level flows and Figma handoff for workshop layout.