# v1.1 (version 1)

See [here](https://hackmd.io/x7b95YKQQs2ApC9PGFHVSQ) for version 3 of this BRD.

See [here](https://hackmd.io/6wa2outuSp6zFIDoy64rrg) for version 2 of this BRD.

See [Vision statement](https://www.figma.com/board/MzXW3RC788dVEvRp127iHe/LLM-Product-Roadmap?node-id=18-99&t=Kc7xj5uU1WpTSwcV-0) 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.
1. 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](https://github.com/CredComSoc/cofi-app-llm/issues/978).
* Due date
1. On initial connection to Xero, first data visible within 5 seconds (it's fine if this is a very minimal amount).
1. 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
1. 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.

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

1. ### 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.
1. Contains:
1. Total count of invoices collected from Xero
1. Total value of invoices collected from Xero
1. Total number of unique customers listed in Xero
1. Total count of files currently associated with user
1. Continuous and automatic update on new invoice data collection and/or file upload and deletion.
1. Design to accommodate continuous enrichment towards a full dashboard/landing screen (displacing some or all of current 'Home' screen content):
* More statistics
* (Access to) visualisations
* May resemble [existing dashboard design](https://www.figma.com/design/uBNHxRO15NxiDPaCaSSdmJ/LLM-Designs?node-id=5475-2538&t=eHxxsvc8I6Hyv9bh-0)
1. Design to accommodate future presence of network-level dashboard.

1. ## Admin user features

1. ### Accounts
Intention: simplify existing admin account arrangements. Allow admin-created organisations to become client users.
1. Single admin user login.
1. Clean-up of existing admin users.
1. 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.

1. ### 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).
1. Refresh the view of client user in a manner that also triggers display of all new data and files.
1. Make client user's Xero connection status visible:
1. Not connected
1. Connected
1. Disconnected (if possible to distinguish from 'Not connected')
1. Reconnected (if possible to distinguish from 'Connected')

1. ### 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.
1. Delete all client user Xero invoice data and files at time of account deletion.
1. 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)

1. ## 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.
1. Change 'Name' field placeholder text to 'Your Name' (for consistency with other fields).
1. Authenticated users: 'Your Email Address' field pre-populated with user's email address.

1. ## 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).
1. 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
1. Prevent any given Xero organisation from being connected to multiple client users
* Need to reconcile with [this comment](https://github.com/CredComSoc/cofi-app-llm/issues/931#issuecomment-2785903639) on [#931](https://github.com/orgs/CredComSoc/projects/6/views/4?pane=issue&itemId=103151262&issue=CredComSoc%7Ccofi-app-llm%7C931).
1. 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.
1. Review and amend data collection spec in tickets [#978](https://github.com/CredComSoc/cofi-app-llm/issues/978), [#993](https://github.com/CredComSoc/cofi-app-llm/issues/993), and [#977](https://github.com/CredComSoc/cofi-app-llm/issues/977) with reference to Promis API (rather than Xero API).

1. ### 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.
1. Should not delete previously collected data.
1. Should not prevent or discourage reconnection.
1. Should not require the user to confirm in Xero, or otherwise leave the app.
1. Modal:
1. Confirmation of disconnect
1. 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
1. Reference ticket [#961](https://github.com/orgs/CredComSoc/projects/6/views/4?pane=issue&itemId=104713975&issue=CredComSoc%7Ccofi-app-llm%7C961) (including comments) for deliberate client disconnection from Xero side.

1. ### 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.
1. Workflow should be identical (or as close as possible) to that of initial connection.
1. 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](https://github.com/CredComSoc/cofi-app-llm/issues/978).
1. Resume behaviour as if connection had never been interrupted.

1. ## 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).

1. ## Continuous improvements
1. Populate Registration drop-down with existing Companies House org name list, plus existing client user org names.
1. Spike on populating Registration drop-down with IDM canonical org name list, plus existing client user org names.
1. Change 'Invoice date' to 'Issue date' in admin view of client user's Xero data.
1. Change 'Total Due' to 'Amount' in admin view of client user's Xero data.
* Need to confirm this choice with reference to ticket [#978](https://github.com/CredComSoc/cofi-app-llm/issues/978).
1. Rename 'Pilot dashboard' screen in accordance with Sales/Marketing input.
1. Update 'Home' screen text in accordance with Sales/Marketing input.
1. Update 'About' screen text in accordance with Sales/Marketing input.

1. ## 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.

### Legal
* No new requirements on Legal.

## Resolved comments
> [name=tfwoodroof] Given that we are collecting, processing, and sharing results from 2024 data, should we display this as well?
> > [name=dil] Yes! We should display by month initially, then later move to 'clearing run period'

> [name=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](https://www.figma.com/design/uBNHxRO15NxiDPaCaSSdmJ/LLM-Designs?node-id=6040-15963&t=o9gY7HCqRAAt5DKU-0)?
> > [name=dil] A simpler version of the table /screen found there makes sense to me, yes

> [name=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.
> > [name=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.

> [name=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).
> > [name=dil] 1: (wrt previous comment) Note that Xero use 'Issuer'
> > [name=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.

> [name=tfwoodroof] Terminology comment: pilot app admin view uses 'Invoice date', whilst Xero uses 'Issue date'. Suggest 'Issue date' is clearest. Decide & propagate.
> > [name=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.

> [name=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).
> > [name=dil] depends on T-shirt size for me. If simple, great.

> [name=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).
> > [name=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 .

> [name=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?
> > [name=dil] imho, no.

> [name=tfwoodroof] See corresponding comment in previous section.

> [name=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 ???
> [name=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)
> > [name=dil] Agree.

* Table should be located on Pilot Dashboard
> [name=tfwoodroof] See corresponding comments in earlier sections.

> [name=tfwoodroof] Plenty of options here, but suggest this section is best informed by ongoing analytics work with Mohammed @mcs-admin (Dil).
> > [name=dil] yes

> [name=tfwoodroof] Visualisation not currently mentioned, but previous comment also applies.
> > [name=dil] yes

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

> [name=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
> [name=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.
> > [name=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
> [name=dil] As per above, let's not do this

#### Ability to edit invoices
> [name=tfwoodroof] Not sure this is a good idea - see previous comments about client-facing editing 'at source'.
> > [name=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