Try   HackMD

v1.1 (version 1)

See here for version 3 of this BRD.

See here for version 2 of this BRD.

See Vision statement for context around release purpose.

  1. Client user features

    1. Data visibility

      Intention: allow client user to quickly and easily verify that any given piece of Xero invoice data or file has been collected/uploaded as expected.

      1. Table of Xero invoices

        1. Separate from 'Home (Landing?)' (currently referred to as 'Dashboard') screen:
          • E.g. located on its own screen or full-screen modal.
        2. List all retrieved Xero invoices for this user, with the following fields:
          • Customer
          • Total amount due
            • Need to confirm that this is the same as the 'Amount' field in Xero - cross-reference with ticket #978.
          • Due date
        3. On initial connection to Xero, first data visible within 5 seconds (it's fine if this is a very minimal amount).
        4. Communicate at a glance when to expect data to update (both after initial connection and on return in subsequent sessions):
          • E.g. page could have a note of:
            • when invoice data was last collected
            • when invoice data will next be collected
        5. Condition users to think in month-long time blocks:
          • E.g. invoices could be grouped by month, with the ability to select month to view.

      2. Table of uploaded files

        1. Separate from 'Home' screen:
          • E.g. located on its own screen or full-screen modal.
        2. List all uploaded files for this user, with the following information:
          • File name
          • File type
          • Upload date
        3. Option to delete files.
        4. Instant update on successful new file upload or deletion.

    2. Statistics

      Intention: allow client user to quickly and easily view basic statistics on their Xero invoice data and uploaded files.

      1. Integrated into 'Home' screen.
      2. Contains:
        1. Total count of invoices collected from Xero
        2. Total value of invoices collected from Xero
        3. Total number of unique customers listed in Xero
        4. Total count of files currently associated with user
      3. Continuous and automatic update on new invoice data collection and/or file upload and deletion.
      4. Design to accommodate continuous enrichment towards a full dashboard/landing screen (displacing some or all of current 'Home' screen content):
      5. Design to accommodate future presence of network-level dashboard.

  2. Admin user features

    1. Accounts

      Intention: simplify existing admin account arrangements. Allow admin-created organisations to become client users.

      1. Single admin user login.
      2. Clean-up of existing admin users.
      3. Ensure that organisations created by the admin user can be 'claimed' by a corresponding client user, and subsequently function identically to a client user-created account:
        • E.g. the new client user could enter their email address (associated with the admin-created organisation) into the password reset workflow.
          • Attempted this as best-guess during testing, and doesn't currently work - need to ask Yani whether any other form of this functionality has been built.

    2. Data visibility

      Intention: allow admin user to quickly and easily verify that any given piece of client user's Xero invoice data or files have been collected/uploaded as expected. Allow admin user to view client user's Xero connection status.

      1. On first connection by a client user to their Xero, first data visible to admin user within 5 seconds (it's fine if this is a very minimal amount).
      2. Refresh the view of client user in a manner that also triggers display of all new data and files.
      3. Make client user's Xero connection status visible:
        1. Not connected
        2. Connected
        3. Disconnected (if possible to distinguish from 'Not connected')
        4. Reconnected (if possible to distinguish from 'Connected')

    3. Data management

      Intention: allow admin user to handle invoice data more quickly and reliably.

      1. Download all Xero invoice data and files for a single client user.
      2. Delete all client user Xero invoice data and files at time of account deletion.
      3. Automated daily email to admin and ops accounts with new information from last 24 hours:
        • All new client users (org name and email)
        • All new Xero connections or reconnections (client user org name and email, Xero org name and email)
        • All new disconnections from Xero (client user org name and email, Xero org name and email)
        • All new Xero invoice data and uploaded files
        • Structured data to enable development of automated responses (possibly outside of app)

  3. General UI/UX

    1. Across whole app (auth and pre-auth): mailto message and link should be replaced with an improved Contact form:
      1. Should always be easily accessible:
        • E.g. placed in footer note and/or menu item.
      2. Change 'Name' field placeholder text to 'Your Name' (for consistency with other fields).
      3. Authenticated users: 'Your Email Address' field pre-populated with user's email address.

  4. Xero integration

    1. Connect

      Intention: make connecting to Xero the most obvious and desirable client user action. Minimise the possibility of confusion or mixed-up data streams. Collect necessary invoice data for initial analysis.

      1. Should be a highly prominent CTA (if no connection active).
      2. Ensure 1-2-1 mapping of client users to Xero organisations:
        1. Prevent any given client user from connecting to more than one Xero organisation
        2. Prevent any given Xero organisation from being connected to multiple client users
      3. Do not prevent an organisation in a Xero account which contains another organisation that is already linked to a client user from connecting to a different (unconnected) client user.
      4. Review and amend data collection spec in tickets #978, #993, and #977 with reference to Promis API (rather than Xero API).

    2. Disconnect

      Intention: allow (but do not encourage) disconnecting from Xero. Communicate outcomes of doing so. Reduce likelihood of accidental disconnect. Do not unnecessarily discard data. Do not prevent or discourage reconnection.

      1. Should not be an encouraged CTA.
      2. Should not delete previously collected data.
      3. Should not prevent or discourage reconnection.
      4. Should not require the user to confirm in Xero, or otherwise leave the app.
      5. Modal:
        1. Confirmation of disconnect
        2. Inform of what LLM will do:
          • Cease data collection
          • Not erase previously collected data
          • Inform that can reconnect at any time (i.e. this is not permanent)
          • Inform of how to request account & data deletion
      6. Reference ticket #961 (including comments) for deliberate client disconnection from Xero side.

    3. Reconnect

      Intention: ensure reconnection is as close to the initial connection experience as possible. Collect any data created during period of disconnection.

      1. Should be a highly prominent CTA.
      2. Workflow should be identical (or as close as possible) to that of initial connection.
      3. Collect Xero invoice data subsequent to most recent entry we already hold, or from 1st Jan 2024 (whichever is earlier).
        • Need to confirm this with reference to ticket #978.
      4. Resume behaviour as if connection had never been interrupted.

  5. Promis

    1. QuickBooks integration that meets same (or as close as possible) business requirements specified for Xero.
      • NB: may need to 'backfill' Xero specifications in order to be confident about these.
      • NB: introduction may involve second-order considerations e.g. around interface design and field names/terminology (particularly in admin view).

  6. Continuous improvements

    1. Populate Registration drop-down with existing Companies House org name list, plus existing client user org names.
    2. Spike on populating Registration drop-down with IDM canonical org name list, plus existing client user org names.
    3. Change 'Invoice date' to 'Issue date' in admin view of client user's Xero data.
    4. Change 'Total Due' to 'Amount' in admin view of client user's Xero data.
      • Need to confirm this choice with reference to ticket #978.
    5. Rename 'Pilot dashboard' screen in accordance with Sales/Marketing input.
    6. Update 'Home' screen text in accordance with Sales/Marketing input.
    7. Update 'About' screen text in accordance with Sales/Marketing input.

  7. NFRs

    1. Google Analytics.

Implied non-tech requirements

Sales/Marketing

  • Decide use of words 'Pilot' and 'Dashboard'.
  • Review text in 'Home' screen.
  • Review 'About' screen text.
  • Progress new client journey in order to support knowledge management for future releases (e.g. HubSpot integration).

Ops

  • Specify address to receive daily users/data update.
  • Implement email confirmation to client user of account and data deletion.
  • Spike on org identity and reconciliation, canonical identity & 'single source of truth', taking into account all data sources (present and likely future):
    • Existing Companies House data
    • IDM data
    • Xero account data
    • Invoice counterparty data
    • HubSpot data
    • Partner directories
  • Progress new client journey in order to support knowledge management for future releases (e.g. HubSpot integration).

Finance

  • No new requirements on Finance.
  • No new requirements on Legal.

Resolved comments

tfwoodroof Given that we are collecting, processing, and sharing results from 2024 data, should we display this as well?

dil Yes! We should display by month initially, then later move to 'clearing run period'

tfwoodroof: referring to the Figma designs, the screens in the 'Pilot Dashboard' section don't go beyond the initial release. Is this meant to refer to the tables in the 'Invoice partner acknowledgement' section?

dil A simpler version of the table /screen found there makes sense to me, yes

tfwoodroof Suggest a terminology clarification would be useful here: the pilot app admin view uses 'Debtor', which for a Xero user issuing an invoice corresponds to 'Contact' (this mapping is noted in the pilot admin view as per ticket #932). Clearest choice for me would be 'Debtor', but friendlier option for users might be 'Customer'. Whatever choice is made should be propagated across designs/specs/tickets as appropriate.

dil We have been using 'Recipient'(and 'Issuer') so far. If we want to use more normal words, then 'Customer' seems right, with 'Supplier' the counterpart.

tfwoodroof 'Reference' isn't a mandatory field when issuing an invoice from Xero, whereas 'Issuer number' is (format is e.g. INV-001, very similar to typical Reference format). Need to make a decision here, and propagate across designs/specs/tickets as appropriate. Simplest decision to me seems to be to go with 'Invoice number', acknowledging that we have future flexibility as Promis is currently collecting 'Reference' as well (as per ticket #926).

dil 1: (wrt previous comment) Note that Xero use 'Issuer'
dil 2: We don't have a design showing a reference number. I don'y think we need to. Names and amounts are what people remember and look for, by and large. Reference numbers are secondary. I have for a while thought that a tooltip/pop-over with fuller invoice details could resolve several thoughts about this sort of thing.

tfwoodroof Terminology comment: pilot app admin view uses 'Invoice date', whilst Xero uses 'Issue date'. Suggest 'Issue date' is clearest. Decide & propagate.

dil idk why we are now thinking of offering so much more detail than previously? If we didn't consider additional detail in the main list view necessary for the invoice upload workflow, why is it needed in the pilot app? Comment aboove about tooltip answers any need without building a detailed table which will always be horrible on mobile. Applies to all data below. simply not necessary in our app imnsho

[From TomN] Descriptions are a required field on Xero invoices/line items within each Xero invoice. Suggest we show line item descriptions together, grouped within each item. As with Reference, this data is already available to us.

tfwoodroof A smooth auto-refresh/update experience would be nice to have here (in the admin backend manual page refresh is required - also noted in admin section as a possible improvement there).

dil depends on T-shirt size for me. If simple, great.

tfwoodroof Syncing/import of new data currently seems to take up to 5 minutes - greater frequency is desirable (also noted in admin section as a way to significantly speed up testing).

dil afaik this is a configured polling frequency from Promis to Xero. Should be easy enough to have a manual request button for early testing or decrease interval for pre-release testing .

tfwoodroof Do we want to introduce 'seen/acknowledged by recipient/debtor/customer' at this stage as an early uncertainty-reduction value proposition + pre-figuring of clearing service and 'bring your friends' dynamics?

dil imho, no.

tfwoodroof See corresponding comment in previous section.

dil We should think about when in the layering onto ilot we will display data parsed manually from file uploads in the app.

??? Check/improve data quality ???

tfwoodroof Initial thoughts on this are that edit functionality shouldn't be available - if data is missing or wrong, this should be dealt with 'at source' (i.e. in Xero, or by deleting and re-uploading documents from which unsatisfactory data was extracted)

dil Agree.

  • Table should be located on Pilot Dashboard

tfwoodroof See corresponding comments in earlier sections.

tfwoodroof Plenty of options here, but suggest this section is best informed by ongoing analytics work with Mohammed @mcs-admin (Dil).

dil yes

tfwoodroof Visualisation not currently mentioned, but previous comment also applies.

dil yes

tfwoodroof Presumably dependent on ticket #606, for which business requirements & testing script/acceptance criteria not yet specified.

tfwoodroof Contact form not currently accessible in auth state - instead, there are just messages on the 'Dashboard' and 'About' screens to the effect of 'send an email to hello@llm'.

Invoice management for admins - Admin user dashboard

  • Admin user should already be able to view invoices and files, filtered by user

Ability to remove invoices

tfwoodroof Not sure this is a good idea. Admin can currently delete accounts, and might be better to expand on this along the lines of 'delete account and all associated data on user request', rather than allowing the possibility of admins deleting individual invoices ad-hoc.

dil agree

  • Invoice records collected from Promis should have an associated 'remove' button
    • This should flag this invoice record so:
      • it can be excluded from any exported data
      • it is not "recollected" by the Promis connection

dil As per above, let's not do this

Ability to edit invoices

tfwoodroof Not sure this is a good idea - see previous comments about client-facing editing 'at source'.

dil Agree strongly - what value would a pilot client get from editing an invoice?

  • Invoice records collected from Promis should have an assoicated edit button
    • The following values should be editable
      • Recipient
      • Total amount due
      • Due date
      • Reference
      • Date of issue
    • This should only change our (LLM) values for this invoice, and not attempt update on Promis, or Xero
    • Any changes should also flag this invoice record so:
      • changes are not overwritten back to original values by the Promis connection
Last changed by 
 
MCS docs
0
65

Read more

Download the Data to Your Machine

Log in to the Migadu

Jun 1, 2025
Log a Working Session

This sequence involves:

Jun 1, 2025
Pilot User app

Set out the high level requirements this app must satisfy

Apr 10, 2025
Pilot/MVP Roadmap Planning

This a source document to support planning Material here should end up in the LLM Technical Development Roadmap (https://hackmd.io/aAZOoXCVTO2wMnRHf39zxA)

Mar 25, 2025
Read more from MCS docs
Published on HackMD