Konomi.ai Documentation

This is where we store all meeting minutes, API reference and product documentation!

SPA patient record management system

Problem Description

On a daily basis, our client has to track customer experience and manage practice related information. Their current solution involves saving records on paper and public cloud softwares like OneDrive. This solution has limits when it comes to scalability, customizability, and reportability. The solution also has limited searchability and is time consuming to build reports. Therefore, the client is seeking a solution for an affordable and scalable practice management software that allows them to track customer experience and improve team productivity.

Proposed Solution

We propose a cloud hosted, on-premise available customer management tool that allows the client to create and manage customer profiles, record details throughout customer visits, and generate comprehensive reports to improve customer experiences. The solution will support user identity, customizable forms, enhanced user inputs, full-text search, data reporting, and AI enabled analytics. Our solution will simplify customer visit tracking and improve user experience.

Areas of focus:

• User identity for customers, employees and administrators
• Data collection with customizable forms
• External service integrations
• Full-text search
• Security & privacy
• AI enabled natural language processing and analytics

Stakeholder Contact:

MVP Scope

The following represents the scope of our Minimum Viable Product (MVP) with a delivery target of April 2022.

Top priority (Must have)

• Customer profile
  • Core fields
• Activity entry
• Inventory
  • only the data structure & reading the data
• Customizable IP whitelist
• Identify staff for logging
• user identity
• Role based access control
• One hard coded statistic report generation

Medium priority (Nice to have)

• Customer profile
  • Custom fields
• Customizable roles/permissions
• User identity management
• Audit log

Low priority (Stretch goals)

• Custom stat reports
  • automated time based
  • manual reports
  • report templates
• Inventory
  • Management UI

Konomi.ai Chronicle Technology Stack

Front end

• Platform: Web
• Language: TypeScript
• UI Framework: React SPA
• Build tool: Vite
• Styling: MUI
• Libraries:
  • Data layer: React Query
  • Form handling: React Hook Form
  • State management: Zustand
• Testing:
  • Unit test: Vitest
  • E2E test: CypressJS

Back end

• Platform: NodeJS
• Language: TypeScript
• Framework: NestJS
• Testing:
  • Jest
• Database:
  • MongoDB
• Libraries
  • OR(D)M: Prisma/Mongoose

Infrastructure management

• IaaC: Terraform
• CI: GitHub Action
• Cloud Service Provider: GCP

Database Design

erDiagram
    Activity {
        string id
        string name
        int price
        boolean isArchived
        createdAt DateTime
        updatedAt DateTime
    }
    Role {
        string id
        string name
        json permissions
        list staffIds
    }
    Staff {
        string id
        string firstName
        string lastName
        string email
        string dateOfBirth
        string authKey
        gender Gender
        boolean isSuperUser
        boolean isSuspended
        timestamp createdAt
        timestamp updatedAt
        boolean deletedAt
    }
    Variant {
        string id
        string description
        int price
        string barcode
        boolean isAvailable
        timestamp createdAt
        timestamp updatedAt
        string productId
        string activityEntryId
        boolean isArchived
    }
    Product {
        string id
        string name
        string brand
        list imageUrl
        boolean isArchived
        timestamp createdAt
        timestamp updatedAt
    }
    Ip {
        string id
        string ip
        string description
        timestamp createdAt
        timestamp updatedAt
    }
    Form {
        string id
        string title
        string description
        FormPurpose purpose
        timestamp createdAt
        timestamp updatedAt
        string latestFormId
    }
    FormVersion {
        string id
        string body
        timestamp version
        string latestFormId
        string formId
    }
    Response {
        string id
        timestamp createdAt
        timestamp updatedAt
        string latestResponseVersionId
        string customerId
        string activityEntryId
    }
    ResponseVersion {
        string id
        string body
        timestamp version
        string staffId
        string responseId
        string formVersionId
    }
    Customer {
        string id
        string firstName
        string lastName
        Gender gender
        string dateOfBirth
        string email
        string phone
        boolean isDeleted
        timestamp createdAt
        timestamp updatedAt
    }
    ActivityEntry {
        string id
        list variantIds
        string customerId
        timestamp createdAt
        timestamp updatedAt
        string activityId
        string staffId
        int tipCharged
    }
    Ledger {
        string id
        int amount
        string description
        timestamp createdAt
        string customerId
        string staffId
        string activityEntryId
    }
    Audit {
        string id
        string staffId
        string endpointMethod
        string params
        string query
        string payload
        timestamp createdAt
        timestamp updatedAt
    }

    Role ||--|{ Staff: in
    Staff |o--|{ ActivityEntry: associated
    ActivityEntry }o--|| Customer: associated
    Form ||--o{ Response: has
    Activity ||--o{ ActivityEntry: has
    Staff ||--o{ ActivityEntry: creates
    Staff ||--o{ Audit: produces
    Staff ||--o{ Ledger: creates
    Staff }|--|{ ResponseVersion: creates
    Product ||--|{ Variant: has
    Form ||--|{ FormVersion: has
    Response ||--|{ ResponseVersion: has
    Customer ||--o{ Response: has
    ResponseVersion }|--|o FormVersion: has
    ResponseVersion ||--|{ Response: has
    Ledger }o--|| Customer: has
    ActivityEntry ||--o{ Response: associated
    ActivityEntry ||--|{ Variant: has

User Stories

This document includes a list of user stories we target in Chronicle.

User stories that are fully implemented and verified are checked, user stories with automated testing implemented, will have the testing method labeled.

Identity and login

• As a user, I can sign in and sign out of the application using correct credentials (e2e)
• As a user, I can update their password and sign in with updated password (e2e)
• As a user, when I try to login from a disallowed IP source, an error message should be displayed to the user (jest)

Identity and access control

IP Allowlist

• As an Owner, I want to be able to update the IP Whitelist, so I can prevent offsite activities. (e2e)
• As an Owner, I want to ensure my staff cannot access the data from an unknown IP address. So I can protect the privacy of my customers
• As a staff member, I want to be able to add staff to the system, so other staff could access the system as well. (e2e)

Staff management

• As a staff, I want to be able to reset another staff's account password, so they can regain access if they forgot their password
• As a staff member, I want to be able to view the email and role details of another staff (e2e)
• As a staff member, I want to be able to suspend other staff accounts so I can prevent them from accessing the system. (e2e)
• [] As a staff member, I want to be able to delete a staff account, so I can remove their personal information from the system.

Role Management

• As a staff member, I want to be able to view the roles created for my company, so I can create missing roles and update existing ones. (e2e)
• As an owner, I want to be able to view the IP addresses I allowlisted and add new ones and remove old ones, so I can adapt to company network changes.
• As a staff member, I want to be able to create roles, so that nothing more than the required permissions are given. (e2e)
• As a staff member, I want to be able to update staff roles, so other staff can get access to what they need. (e2e)
• As a staff member, I want to be able to update other staff account's details, so that their information can be up to date.
• As a staff member, I want to be able to delete an unused role so other staff doesn't become confused and accidentally use the role
• As a staff member, I want to be able to update existing roles, so that only the correct permissions are given to other staff.
• As a staff member, I want to be able to sign into the dashboard using my username and password

Inventory

• As a staff member, I should be able to create treatment or physical goods
• As a staff member, I should be able to update the price of physical goods
• As a staff member, I should be able to support internal client's own id in the form of an SKU
• As a staff member, I should be able to support universal barcode scanning for physical goods
• As a staff member, I should be able to update all attributes of a product
• As a staff member, I should be able to delete inventory items that are not used in an activity entry
• As a staff member, I should be able to find inventory items by names
• As a staff member, I should be able to find inventory items by SKU
• As a staff member, I should be able to find physical goods by barcode
• As a staff member, I should be able to manage variants and automatically generate a table of variants based on options
• As a staff member, I should be able to manage variants and change price/SKU/barcode for each item
• As a staff member, I should be able to manage variants and customize product options (option name, list of options)
• As a staff member, I should be able to mark a product/service as unavailable
• As a staff member, I should be able to manage variants and change price/SKU/barcode for any number of variants selected (stretch goal)

Data Reporting

• As a BA staff, I want to see the total spending per customer in a set period of time

• As a manager, I want to see the revenue generated by each practitioner in a set period of time

• As a procurement staff, I want to see the total sales of each product in a set period of time

• As an owner, I want standard reports sent to me on a periodic basis (EOD/EOW)

• As an owner, I want to be able to specify what information is in a report

• As an owner, I want to be able to see the list of activities that were performed at a specified period of time

• As an owner, I want to be able to see the items and variations bought by customers during a specified period of time

• As an owner, I want to be able to view membership attendance and new members onboarded

Forms

• The system shall record when a staff member edits a form response

• As a staff member, I want to be able to make edits to a form response

• As a staff member, I want to be able to create a form

• The system shall have preset forms with the following fields
  - customer info: first name, last name, DoB, sex, email, phone number
  - medical record: height, weight, allergies, conditions, additional notes
  - membership purchase/renewal (out of mvp scope): email, phone number (tied to customer info) level, date
  - Activity Entry: treatment, price, date/time, general notes, critical notes, and photos
  - Purchase/Transaction entry: product name, size, barcode, price

• The system should validate data before writing to the database to ensure consistency.

• As a staff member, I want to be able to create new fields on an existing form

• As a staff member, I want to be able to delete fields on a existing form

• As a staff member, I want to be able to view form responses

• As a staff member, I want to be able to view forms

• The system shall have a unique ID for each customer

• The system shall validate fields of a form before saving to the database.

• The system shall associate form responses with the respective customer and provider

• As a staff member, I want to be able to delete a form

• As a staff member, I want to be able to fill out a form response

• As a staff member, I want to be able to add sections to a form

• As a staff member, I want to be able to delete sections on a form

• As a staff member, I want to be able to update the order of the fields, so I can save time if I make a mistake making the form.

• As a provider, I should be able to search for specific entries involved with specific customers.

• As a provider, I should be able to view all a customer’s entries under their profile

Customizable form system

One key feature of our application is that it allows users to create their own forms and attach those forms to entities like customers, daily visits, products etc. The app also allows the user to perform analytics and data reporting using the custom data. This document will discuss a few ways to implement custom fields in our system.

Components of the system

There are three components to the system.

1. The template schema
2. Forms
3. Responses

The template schema

The template schema is a json schema managed by the Konomi.ai team. This schema defines the possible shape of tenant forms. The schema includes all allowed field types, field properties and form structure information.

The template is in the shape of a json schema version 7

Forms

Forms are created by tenants and used within the tenancy. The shape of the forms are governed by the template schema. All forms must pass a schema test before responses can be made to the form.

The form shape is sanctioned by the template schema, upon saving a form, a new json schema will be generated to validate form responses.

Responses

Responses are created by tenants's staff and are associated with a particular version of a form version. The response must pass a schema test before it can be used.

Form Features

Validation

Every response is validated against the version of the form it is responding to, this ensures that all fields are valid before the user can save a response. Response validation happens on the client first and then on the server. The validation logic is handled by the c-form package which includes helper function that take in a form definition and validate against it.

Currently, we aim to support optional fields first. In the future we want to support more complex field validation logic.

Versioning

A core design of the form is the ability to keep track of versions for forms and responses. When a change is made to a form/response, a new version of the entity will be created, this will ensure a full track of audit history on changes and allow the ability to rollback potential changes. This also keeps the database sain for the sake of the developers.

Field types

The form will support the following form types for now:

1. Short text - usually text within one line
2. Long text - text that can span multiple paragraphs
3. Multiple choice - select an option from a list of possible options
4. Multi select - select up to a number of options from a list of possible options
5. Number - an input that can only be a numerical value (no scientific values allowed)

Load multiple choice options from server

The system will be able to load multiple choice options dynamically using REST APIs.

Connection with entities

Entities like activity entry, customers, etc. will have a new responses field. This will keep track of all the responses that was filled for the entity.

For activity entry, upon creation, all forms with activity entry as the purpose is loaded. The user selects one form and completes it. Then users can add any number of activity entry, or null purpose forms to the entry.

For all other entities, by default all forms whose purpose is matching the entity are required to be completed. Then users can attach any additional fields.

Form management lifecycle

Create new form

sequenceDiagram
  autonumber
  participant Client
  participant Server
  participant Database
  Client->>Client: Validate form with c-form
  Client->>Server: Send created form to server
  Server->>Server: Validate form with c-form
  Server->>Database: Save new form
  activate Database
  Database-->>Server: Form saved with ID
  deactivate Database
  Server-->>Client: Form created with ID

Update existing form

sequenceDiagram
  autonumber
  participant Client
  participant Server
  participant Database
  Client->>Client: Validate form with c-form
  Client->>Server: Send updated form to server
  Server->>Server: Validate form with c-form
  Server->>Database: Save updated form as draft
  activate Database
  Database-->>Server: Form saved with ID
  deactivate Database
  Server-->>Client: Form draft saved with ID
  Client->>Server: Update form to draft version
  Server->>Database: Update form to draft version
  Database-->>Server: Form version updated to draft version
  Server-->>Client: Form version updated to draft version

Database design

Here we describe the proposed database design for this system

erDiagram
  form ||--|| latestForm  : uses
  form ||--|{ formVersion : versions
  form {
    string id
    string templateVersion
    string purpose
  }
  formVersion ||--o| latestForm : is
  formVersion {
    string id
    string formVersionId
    json formData
  }
  response |o--|| formVersion : responsesTo
  response ||--|| latestResponse : uses
  response ||--|{ responseVersion : versions
  response {
    string id
  }
  responseVersion ||--o| latestResponse : is
  responseVersion {
    string id
    json responseData
  }

Data analytics system design

We want to help our customers better understand the performance of their business and gain insights from the data they collect. To achieve this goal, we designed a powerful analytics system with progressive improvements in mind.

Setting the goals

The first issue we tackled as a team is to understand the goal of our analytics service and the MVP scope of the service. From there we setup a future outlook on the features we want to see the service deliver.

Through discussion, we decided that the goal of our analytics service is:

• Customizable
• Easy to use
• Comprehensive & Dynamic

Customizable

We want to build a service where the customer can have maximum control over the reports they generate, they can chose the filtering criteria, select the column and aggregations and more importantly receive the data in the format they prefer.

For our MVP product, we want the user to be able to set the time-based filtering criteria, select the columns to display and data to aggregate. We plan on generating JSON and in-app table as the initial export solution

In the future we plan on implementing the following capabilities.

• Filter data with more fields
• Customizable aggregation techniques (average, min, max over period)
• More data exporting methods (CSV, XLSX, or to other analytics services)

Easy to use

We want to build an analytics service that does not require a degree in data science to use. For that we need a simple and streamlined customer experience with the ability to build commonly used reports with a click of a button.

For our MVP product we will include handcrafted templates that customers can implement without fiddling with a bunch of filters and form controls.

In the future we plan on making the system more accessible by adding:

• Column suggestions
• Automatically generated reports
• In-app data visualization with charts

Comprehensive and dynamic

We want to ensure our focus of ease-of-use and accessibility does not hamper the clients' capability to perform more advanced analytical tasks. For that we have.

For the MVP, we want to build predefined aggregation views that cover at least 90% of the client's analytics use cases.

In the future we will add:

• The ability to aggregate any column
• The ability to set aggregation window sizes
• The ability to work with data from user generated custom forms
• Multiple data sources on a single table to see relationship between data sources (a)

Building the MVP

To summarize, the MVP version of the data analytics will have pre-defined aggregation capabilities and not feature data from customizable forms.

Understanding the data

The first goal was to understand the data we have collected through the 4 major business focused models of the application

• Customer
• Inventory
• Staff
• Activity Entry

We selected the following aggregations to integrate in the MVP

Aggregating the data

The data will be aggregated and processed on the service and not in the database, this is due to the concern of the limited capabilities of our MongoDB instance. Data will be mapped on the API.

This is also due to the fact that for our service, the API can scale quickly (new instance ready in under 500ms) and the database cannot do so as quickly.

Saving the reports

Once a report is generated, the report will be sent to the client and also saved in the database alongside the configuration template. The user will be able to come back to the report anytime without needing to perform the aggregation again.

Summary

Chronicle is not only for collecting personal care practice data, it is also designed to help business owners to gain insights in their business from the data collected, this will help them make more informed decisions.

Item versioning & customer balance system

Inventory versioning proposal

Inventory data is currently mutable, this could lead to issues with analytics and in the future the balance system we want to implement. This proposal details a way to make our inventory system immutable to allow us to scale our application capabilities in the future.

New record on update

The solution to the mutation problem is to create a new copy of the inventory item whenever the user updates the item's attributes. What this looks like with our current data:

• For activities, whenever the user updates a field, a new record is created and the previous one is marked legacy and hidden from user, the only way to access it again is through activity entries.
• For Product variants, the process is a bit more complex. When the user updates a variant, the variant is recreated as a new record and the previous record is archived, the link between the variant and the product will remain but loading the product data will not show any archived variants. When a product is updated, we have two viable solutions:
  • the product is not recreated as a new record and remains mutable, instead the user will get the warning that updating the product name will cause their analytics data to be impacted.
  • the product is recreated as a new record; all variants will be linked to both records. This can cause problems as we need to modify the existing relation between product/variant from 1-to-many to many-to-many, which increases the complexity of the application so it is not preferred unless we must.

Annotating legacy records to users

If a particular record is archived due to updates, we shall display a banner on the inventory details page informing users this item is archived and can no longer be used, if a product has archived variants, we can note that the product has archived variants.

On the activity entries page, archived activities and product variants will have distinct labels to inform the user that the product has been updated. There will also be a warning that if a user removes the archived activity/product they will not be able to add it back.

Determining if a record has been updated

This is an area that is out of the scope of the initial discussion, but should be considered as we progress, and can be added on later.

Customer balance

One thing we noticed from looking at the client's files is that the use of balance is quite important to the business. I believe we should consider implementing such system as part of our MVP, it would be a banger feature that can really help improve the efficiency of the client's business.

The following is a discussion on the few necessary components and changes to support such a feature.

A new ledger

To keep track of customer balance, we should use a dynamically calculated model in the form of a ledger. The ledger will resemble the following model:

model Ledger {
  id String   @id @default(auto()) @map("_id") @db.ObjectId
  amount Int
  description String @optional
  customer Customer
  activityEntry ActivityEntry @optional
  createdBy Staff
  createdDt DateTime @default(now())
}

Here is an explanation of the model described above:

• The model will track the transaction amount in cents like the rest of the application, the value is positive for a charge against the customer (e.g. spent $80 will be 8000)
• The model will allow the staff to also include a description in the charge, this will be displayed on the user's transaction history page
• Records in the table must not be updated and deleted, staff can create correctional transactions if they need
• A transaction can be linked 1-to-1 with an activity entry, this can help identify sources of charge.
• An activity entry may only have 1 charge on the ledger, any amendments must be done via adjustment.

Charges and negative balance

We propose allowing negative balances to simplify the system, but in the future we should allow the admin to set negative balance tolerance. They should be able to choose negative balance allowance for all customers or for a single customer. They can also disable the possibility all together which will prevent a negative balance from occuring.

Improved activity entries

Activity entries shall also be improved to better handle the new transaction system. Here is a list of proposed changes:

• New lock feature, when the staff creates a charge with the activity entry, it will also lock the activity entry preventing any changes to the customer, activity, or products fields. Activity entries will also be undeletable, but staff can change the custom field responses, and add or remove responses
• New UI for creating a charge, should be place after the information fields and before the custom form fields.

Improved customer UI

The customer page will also receive a UI upgrade to allow the following features

• Balance view on customer details page
• Transaction history on customer details page

Possible UI for managing the ledger

Conclusion

I believe we can bring our client great value if we implemented a customer balance management system, this is also in-line with the vision of the product and many other personal care agencies can use it as well.

Chronicle User Manual

This is the user manual for Konomi.ai's Chronicle app. Chronicle is a personal practice tracking, customer relations management (CRM) application that aims to simplify the way you and your business track practice data and customer engagement.

Table of content

TODO

Login & authentication

Chronicle has a robust access control system that protects you and your customers' data. This guide will detail how to use password sign in.

How to login to Chronicle dashboard

Steps:

1. Go to the login page of your organization
2. Enter your email and password and click Login

How to logout of Chronicle

Steps:

1. Click the profile icon on the top right of the page.
2. Click Logout

How long do I stay signed in for?

Each sign in session lasts 7 hours, that means you must sign in every 7 hours when using the application. We are working on allowing you to maintain your authorized session with automatically renewed sessions.

How can I reset my password?

Steps:

1. Ensure you are currently logged in
2. On the top right, click on your Profile to release a dropdown.
3. On the dropdown, click on Profile
4. Enter your new password. (Note: the minimum length for a password is 8)
5. Enter the same password again in the confirm password field
6. Click on change
7. You will currently still be logged in, however on your next log in attempt, your new password will apply

Customizable forms

Often, businesses have custom data collection requirements and forms that are tailored to their specific organization. Chronicle accommodates this by supporting the ability to create "custom forms". Custom forms are Google Form like forms where you can add questions, set validation rules and require your staff to fill out during any business process, whether that's creating a new customer profile, logging a service entry, or enrolling a new staff member. Custom forms allow you to collect and analyze data the way you want.

How to access custom forms

To see your custom forms and mange them:

1. click on the Customize Forms option on the side navigation
2. You should see a list of all custom forms in your organization.

What if I don't see the option on the side navigation?

If the Customize Forms option is not available for you, it likely means you do not have access to the feature. Ask your administrator to grant you access to custom forms to access the feature.

How to create a new custom form

To create a new custom form follow the following instructions,

1. Access the custom form list, you can follow the instructions above if you need assistance.
2. Click the Create button on the page.

You are now navigated to a new form creation page, follow the form to create your form.

1. Make sure to provide a title and description for your form, forms with clear description and title are more likely to be used.
2. Select a purpose for the form, forms with specific purpose are displayed before all other forms when used by your staff, they are also marked as recommended.
3. Give your first section a title, every form must have at least one section and one question.
4. Add a question to the new section, a question must have a title.
5. You can change the question type using the Question type dropdown next to the question title
6. For multiple choice and multi-select questions, you must also create a list of options, add option titles and press Add option to create more options
7. For dynamic data select questions, you must select a data source to populate the options from.
8. You can add a description to a question by clicking Add description, question descriptions are optional
9. You can make a question optional to complete by unchecking the required toggle.
10. You can add more questions to the section by clicking on Add question.
11. You can add more sections to the form by clicking on Add new section.
12. Make sure to press save at the bottom of the page when you are done.

Update an existing form

When you update an existing form, Chronicle creates a new version of the form and maintains the previous versions just in case they are being used in existing activity entries. This system ensures you will not lose any existing data when modifying form fields. You currently can't browse previous versions of your form, we are actively working to enable this feature.

Steps:

1. Access the custom form list, you can follow the instructions above if you need assistance.
2. Click on the form you want to update.
3. Follow the create form guide for details on how to use the form builder.

Custom form best practices

• While it is possible to create a form with no sections and no question, this is not a recommended practice.
• Use the paragraph option if you want your staff to provide text responses longer than a sentence.
• It is recommended to not delete fields from forms that are being used. While it will not affect any existing entries, you may potentially lose track of data.

Custom form limitations and in-progress features

• Currently you cannot reorder the fields you created, this is an in-development feature.
• Currently you cannot duplicate an existing field, this is an in-development feature.

Staff & role management

Chronicle features a robust staff management system that allows you to track staff information, grant access to specific parts of the system and gain performance insights.

Before proceeding, make sure you are signed in as the super user or you are a user with write access to security feature. This feature is granted to all users with the built-in administrator role

Role Management

You can view, create and update your roles in the system.

Create a new role

Steps:

1. Click on Security on the side menu to show all security menu options, click on Roles.
2. Click Create new role
3. Provide a name and a description for the role.
4. Select all accesses the role has in the system, note if a user has write permission in a role, they will automatically be granted read permission.
5. Remember to click Save at the bottom of the page.

Update an existing role

Steps:

1. Click on security on the side menu to show all security menu options, click on Roles
2. Select the role you want to update
3. Make the necessary changes in the form
4. Click Save when you are done

Deleting a role

Steps:

1. Click on security on the side menu to show all security menu options, click on Roles
2. Select the role you want to delete
3. Make the necessary changes in the form
4. Click delete in the danger zone section of the page. You cannot delete a role if it is assigned to a staff, even if the staff is no longer active. Remove the role from the staff or delete the staff to delete the role.

Staff management

You can currently create and manage staff information using the security feature of Chronicle. We are currently recording basic information about the staff, and are planning to allow custom forms be connected to staff records soon.

Invite a new staff

Steps:

1. Access the staff list by clicking on Staff on the side menu, if you don't see Staff, click on Security to see the option.
2. Click Invite
3. Fill in the form that showed up in the dialog
4. A temporary password will be created for the staff, take a note of the password as it is only shown once.
5. Send the login credentials to your staff member, they will be able to sign in using the credentials provided.

Reset a staff member's password

If your staff member forgot their login credentials, you can reset it using the staff details page.

Steps:

1. Access the staff list by clicking on Staff on the side menu, if you don't see Staff, click on Security to see the option.
2. Click on the staff that requested assistance
3. Click Reset password, then confirm the intent to reset the password.
4. A temporary password will be created for the staff, take a note of the password as it is only shown once.
5. Send the login credentials to your staff member, they will be able to sign in using the credentials provided.

Notes:

The staff will not be signed out of the app if you reset their password, we are working on a system to force sign out the user.

Update a staff member's profile

The process is the same as resetting the password, just update the fields in the form and remember to press save.

Deleting a staff member

When you delete a staff member, their record is not remove entirely. Instead we erase any personal information recorded about the staff member. This includes their email, name, gender, and any associated custom forms.

Steps:

1. Go to the staff member's details page.
2. Suspend the staff first by clicking on Suspend, this will disable the user's access to the system immediately.
3. You can delete suspended staff by clicking on the Delete button in the danger zone

Super user & additional security

You will receive a super user account when your account is first activated, the super user bypasses all firewall restrictions and has full access to the entire application. It is designed to allow the administrators of your establishment to configure the access control correctly before onboarding the remaining staff. We recommend that you suspend access to the account as soon as proper users have been configured.

IP Allowlist

IP allowlist is a powerful application level firewall feature that Chronicle supports to help protect you and your clients' personal data. The IP allowlist enables you to set a fixed list of IP addresses that can access the application to ensure imposters outside your network have no access to your data. To configure the IP allowlist, follow this guide.

Create new allowlist entries

By default, we have 0.0.0.0/0 setup for you, this address allows access from all possible IP addresses and is not safe, we recommend you update the allowlist as soon as possible to reflect the network of your establishment.

Steps:

1. Select IP allowlist on the side drawer.
2. Click Add new
3. Add an IP address and provide a description for additional context

How IP verification works on Chronicle

Chronicle uses Classless Inter-Domain Routing (CIDR) method to verify your IP address, this means you can allow several IP addresses by providing a subnet IP instead of just an IP address. If you are unsure how this works, we recommend that you simply use a single IP address. Chronicle supports both IPv4 and IPv6 addresses.

Delete an existing entry

Be careful, if you delete the entry you are actively using, you risk loosing access to the application immediately.

Steps:

1. Select IP allowlist on the side drawer.
2. Click the garbage can icon next to the entry you want to delete.

Customer profile

Chronicle allows you to keep track of customer information and balance within the application. By default, Chronicle requires the name and email of the customer and allows you to also collect the phone number, date of birth and gender of the customer. You can use custom forms to collect more information that is not already collected by the application

Create a new customer

Steps:

1. Select customer profiles on the side drawer.
2. Click New customer at the top of the page.
3. Fill in the form and press save
4. You can add custom forms to the customer using the custom forms card.
   1. Click on New form
   2. Select the form you want to add
   3. Fill in the form
   4. Click Save changes

Update a customer profile

Steps:

1. Select customer profiles on the side drawer.
2. Select the customer you want to update
3. Update the data in the form and press save

To update the customer's custom form, use the Custom forms module.

Top-up customer account

Steps:

1. Select customer profiles on the side drawer.
2. Select the customer you want to top-up
3. Click Top up account in the balance and transactions card
4. Enter the top up amount and add an optional description to the transaction
5. Press proceed, then press confirm in the confirmation dialog

Adjust customer balance

If you notice an error with the customer's balance you can make an adjustment to the balance on the customer's details page.

Steps:

1. Select customer profiles on the side drawer.
2. Select the customer you want to perform balance adjustment on
3. Click Adjust balance in the balance and transactions card
4. Select the adjustment type
   1. Positive adjustment adds to the customer's balance
   2. Negative adjustment subtracts from the customer's balance
5. Enter the adjustment amount and add an optional description to the transaction
6. Press proceed, then press confirm in the confirmation dialog

Inventory

Chronicle allows you to manage your product and service inventory inside the app. The inventory can then be applied to activity entries and charged to the customers.

Inventory concepts

Activity

An activity is a service performed to a customer, each activity entry can only have a single service. If a customer receives multiple services, multiple activity entries must be created.

Product

A product is a physical item sold to the customer, an activity entry can have any number of products sold.

Create a new inventory item

Activity (service)

Steps:

1. Access Inventory using the side drawer
2. Make sure the Activities tap is highlighted on the page, if not click Activities
3. Click Create
4. Provide the name and price information for the service
5. Press save at the bottom of the page

Product

Steps:

1. Access Inventory using the side drawer
2. Make sure the Product tap is highlighted on the page
3. Click Create
4. Provide the name and brand information for the product
5. Click Add new variant to add a variant to the product, then complete the fields of the dialog. (every product must have at least one variant)
   1. The variant descriptor can be used to describe the specific variant, for example size, capacity, color, etc.
   2. The price of the variant.
   3. A unique barcode for identifying the product
6. Press save at the bottom of the page

Update an existing inventory item

Activity

Steps:

1. Access Inventory using the side drawer
2. Make sure the Activity tap is highlighted on the page
3. Click the activity entry you want to update
4. You can update the activity name and price
5. Press save at the bottom of the page

Product

Steps:

1. Access Inventory using the side drawer
2. Make sure the Product tap is highlighted on the page
3. Click the product entry you want to update
4. You can update the product name and brand
5. Press save at the bottom of the page

You can also update a product's variant information.

Steps:

1. Go the the product details page you want to update.
2. Click on the variant you want to update.
3. Update the values in the form.
4. Press save

Chronicle Glossary

The following are terms used in Chronicle and what they mean

Useful links

Here are some useful links to navigate around the Chronicle project

Figma

• Design Board
• Prototypes