ballerine-io/ballerine

Open-source infrastructure and data orchestration platform for risk decisioning

Open-Source Risk Management Infrastructure

Documentation · Slack · Website · Contact · Issues

Ballerine is an Open-Source Risk Management Infrastructure that helps global payment companies, marketplaces and Fintechs to automate their decisions for merchant, sellers and users throughout the customer lifecycle. From account-opening (KYC, KYB), underwriting, and transaction monitoring, using a flexible rules & workflow engine, 3rd party plugin system, manual review back office, and document & information collection frontend flows.

Modules

• Back Office - Case management dashboard for manual decision-making.
• Workflow Engine - Orchestrates and automates the different system's parts.
• KYB Collection Flow - Real-time modification of KYC/KYB frontend user journeys.
• Rule Engine - Leverage various rule types to ensure user compliance with your risk policy.
• Plugin System - Integrates with 3rd-party vendors, APIs, and databases. see plugins.
• No-Code Builder - Leverage various rule types to ensure user compliance with your risk policy - 🚧 WIP.

Why Open Source?

We believe in enabling companies to manage user identity and risk according to their unique and evolving requirements. Ballerine empowers you to create decisioning processes that are right for you. It is flexible, future-proof, easy to implement, secure, and supported by a robust community.

Explore What You Can Do With Ballerine

• Dynamic Experience: Adaptive user journeys that modify in real-time based on the user's risk.
• Data Ownership: Self-host on-premise to keep sensitive data within your infrastructure.
• Global Orchestration: Add/change vendors and data sources to cater to users from multiple countries.
• Cost Reduction: Retain control over vendor relationships, costs, and communication.
• And More.

Try Ballerine Now

In the following example you can test a simple form of the following infrastructure capabilities

1. Document collection flow.
2. A manual review case management Back Office.
3. Live communication between the parts using a Workflow Engine, that also defines the process steps.
4. A simple JSON containing Risk Rules that are checked during the flow.

Parts of the system you might look for but are not in THIS demo:

• Our Rule Engine is still under construction and will soon be released.

Getting started To set up a local environment, follow these steps:

1. Install prerequisites:

   • Node.js (Install NVM)
   • Latest PNPM version (Install PNPM)
   • Docker and docker compose (Docker, Docker Compose)

2. Clone and install the project:

3. Clone the project:

git clone https://github.com/ballerine-io/ballerine.git

2. Install npm dependencies:

pnpm install

3. Initialize monorepo:

pnpm monorepo:init

3. Run an example

   • KYB

   pnpm kyb-manual-review-example

   • KYC

   pnpm kyc-manual-review-example

Once the process is complete, 2 tabs will open in your browser:

1. http://localhost:5173/ - for the KYB document collection flow OR http://localhost:5202 - for the KYC document collection flow

2. http://localhost:5137/ - for the backoffice (It's recommended to have them positioned side-by-side).

   _{If the required tabs have not opened automatically, please use the links we have provided above.}

   Steps to go over the flow:

3. On the collection flow, fill the required fields on each step

4. Go through and complete the flow

5. Go to the backoffice tab to review the new user that was created

6. Sign-in with the following credentials:

   • Email: [email protected]
   • Password: admin

7. Approve / Reject / Ask to resubmit

8. For ask to resubmit, go back to the collection flow to re-upload, then go back to the backoffice to see the updated information

• Note: some components are currently in beta, if you run into an issue please ping us on Slack

Contributing

We appreciate all types of contributions and believe that an active community is the secret to a rich and stable product. Here are some of the ways you can contribute:

• Give us feedback in our Slack community
• Help with bugs and features on our Issues page
• Submit a feature request or bug report

Contact Ballerine

To start using the paid version or if you need any assistance, reach out to us at [email protected]. Join our Discord Channel and Slack Channel to stay updated and engage with our community.

ballerine's Issues

Business entity

Integrate Nestjs devtools to the workflow-service

Nest Docs reference: https://docs.nestjs.com/devtools/overview

File service

Make the camera overly responsive and lightweight

Try and see if with these properties we can make the overlay look good on every screen.

We can animate the border color of the overlay so the screen would feel more alive (like changing color from border: 3px solid #ffffff4d; to border: 3px solid #007aff75; and back.

Steps I did:

• remove previous overlay div
• added a div above the camera button
• added these properties:

Passport

.overlay.card.svelte-10mpprx {

width: 100%;

.overlay.svelte-10mpprx {

max-width: 80%;
max-height: 100%;
outline: 1000px solid #000000d6;
border: 3px solid #ffffff4d;
z-index: 1;
border-radius: 12px;
aspect-ratio: 3/4;

Still need to vertically center the div + make it so in small screens the text won't overlap with it

---

ID card / backside / drivers license

.overlay.card.svelte-10mpprx {

width: 100%;

.overlay.svelte-10mpprx {

max-width: 80%;
max-height: 100%;
outline: 1000px solid #000000d6;
border: 3px solid #ffffff4d;
z-index: 1;
border-radius: 12px;
aspect-ratio: 4/3;

Still need to vertically center the div

---

Selfie

.overlay.card.svelte-10mpprx {

width: 100%;

.overlay.svelte-10mpprx {

max-width: 80%;
max-height: 100%;
outline: 1000px solid #000000d6;
border: 3px solid #ffffff4d;
z-index: 1;
border-radius: 100%;
aspect-ratio: 3/4;

Still need to vertically center the div + make it so in small screens the text won't overlap with it

A4 doc

.overlay.card.svelte-10mpprx {

width: 100%;

.overlay.svelte-10mpprx {

max-width: 90%;
max-height: 100%;
outline: 1000px solid #000000d6;
border: 3px solid #ffffff4d;
z-index: 1;
border-radius: 12px;
aspect-ratio: 3/4;

Still need to vertically center the div + make it so in small screens the text won't overlap with it

Create enum `WorkflowRuntimeDataStatus`

Convert WorkflowRuntimeData's status column from a string into an enum in the schema.prisma file.

Name change: `sdks/web-sdk` to `sdks/web-ui-sdk`

Search for web-sdk reference

Known locations:

• folder name
• web-sdk package.json name
• monorepo root scripts
• vite config
• Readme's

Feature - add Netlify and Vercel deploy buttons

Description

We want to ease deployment, starting with the web app. let users self-shot it using Netlify and Vercel with deploy buttons.

Alternatives

Current deployment ways are still straightforward but one-click deploy buttons are an amazing experience for someone to quickly self-host and play with the web app

Examples and references

https://vercel.com/docs/deploy-button
https://docs.netlify.com/site-deploys/create-deploys/#deploy-to-netlify-button

Some examples from other repos:

Netlify: https://github.com/katiecorgieblahblah/soundboard
Netlify: https://github.com/ewuweblab/web-3-starter-static/blob/d007c942d5121854cb40547f5df003469dd8e3d8/README.md
Vercel: https://github.com/wk0/boilerplate-next/blob/eefff52c9b2f250d6ee4fa824fad0e47b23da292/README.md
Vercel: https://github.com/trfi/next-web3/blob/effb75c58e7b345c534eb69f22369de92f1395cd/README.md

Feature - Support addition of custom steps in UIConfig flows

Description

I would like to be able to add a custom and not a predefined flow step when initializing web SDK. This should make use of the components available such as image, input etc.

Alternatives

No alternative explored.

Does the feature have an issue or an open Canny ticket

N

If the feature request is approved, would you be willing to submit a PR

N

Examples and references

const ballerineInitConfig = {
  uiConfig: {
    general: {
      colors: {
        primary: '#1155cc',
      },
      fonts: {
        /*Change the font name to "Courier New", click Run, and see the how the font changes */
        name: 'Nunito',
        link: 'https://fonts.googleapis.com/css2?family=Nunito:wght@200;300;400;500;600;700;800&display=swap',
        weight: [400, 500, 700, 800],
      },
      translations: {
      },
    },
    flows: {
      'my-kyc-flow': {
        steps: [
          { 
            name: 'welcome',
            id: 'welcome',
          },
          { 
            name: 'customs',
            id: 'customs',
            // EXAMPLE STEP
            elements: [
                  {
          "type": "image",
          "props": {
              "style": {
                  "margin": "8px auto",
                  "flex-grow": 1
              },
              "attributes": {
                  "src": "https://cdn.ballerine.io/ui-packs/default/images/welcome.svg",
                  "alt": "welcome",
                  "width": "248px",
                  "height": "212px"
              }
          }
      },
    {
        "type": "input",
        "props": {}
    },
    {
        "type": "button",
        "props": {}
    },
            ]
          },
          {
            name: 'document-selection',
            id: 'document-selection',
            documentOptions: ['id_card', 'drivers_license', 'passport'],
          },
          {
            name: 'loading',
            id: 'loading',
          },
          {
            name: 'final',
            id: 'final',
          },
        ],
      },
  },
  translations: {
  },
  endUserInfo: { id: 'test-id' },
  backendConfig: {},
};

Policies

Dockerfile from Workflow-Service with Prisma Migrations inside

Hello, I was trying to deploy the app with the docker-compose file inside the deploy folder and I got an error while building the Workflow-Service. We would need to change the docker file to make migrations at the entrypoint and not inside the build stage.

Migrate all Env Vars to use https://env.t3.gg/docs/core

Add`resolvedAt` to `WorkflowRuntimeData` model

• Add resolvedAt column to the WorkflowRuntimeData table
• Fill it when the workflow enters a final state

Merge dev-> main (make sure both examples works - KYB/KYC)

• Update the data structure of context and a document
• Update auth to use session cookie
• Use the workflow status for active, rejected, and approved instead of the entity status
• Replace instances of re-submit with revision

Deployment - Kubernetes - Finish deploying the first application

Finish Kubernetes deployment with first workflow service deployment (

1. ingress
2. namespace
3. configmap + secrets
4. service (application service)
5. load balancer
6. node config
7. pod scaling.
   )
   app returns OK on requesting

Case management full screen image modal is not showing.

Description

Case management dashboard zoom on previewed image is not working.

Has the bug been reported before

No.

Expected Behaviour

Once you click on the image which is presented in the large image viewer, a modal should pop up, showing the image in full screen.
This behaviour was already implemented but it seems something prevents it from happening.

Actual Behaviour

Clicking the image doesn't do anything.

Environment

On https://www.backoffice-demo.ballerine.app/case-management
All browsers

Steps to Reproduce

1. Enter https://www.backoffice-demo.ballerine.app/case-management
2. Click on the big image on the right side of the screen.
3. Modal is not showing

Backoffice content block component

• Create an interface that accepts a component on a type basis with a default fallback and respects order of rendering, provide a way of passing props and access to the value to render
• Create a way of providing a header and footer
• Provide a way of changing columns
• Provide a way of specifying horizontal
• Add a way of rendering an array of blocks

Backoffice new skeleton UI

• Remove the avatar from the individual actions
• Add an avatar to the app's header (left-side sheet menu)
• Add an execute tasks button
• Add a re-assign button
• Refactor the individual view to use an array of arrays instead of an object for data (enables rendering tasks as blocks)
• Add options and approve buttons to each task block
• Remove the settings button from the app's header

wf-service: create dev image from dev branch

Landscape mode breaks the layout

Subject

Bug - Landscape mode breaks the layout

Description

The UI isn't built for landscape mode, yet when rotating the device the layout changes to landscape mode and breaks.

Has the bug been reported before

No.

Expected Behaviour

The screen rotation should remain in portrait mode when turning the phone horizontally.

Actual Behaviour

The screen rotation changes to landscape mode when rotated

Environment

• Device, operating system, and its version:
  • Mobile phone (Android & iOS)
• Browser and its version:
  • Any
• Version of the affected apps and packages:
  • Web SDK - 1.1.34

Steps to Reproduce

1. Enter the flow in portrait mode (https://simples-kyc-demo.ballerine.app).
2. Turn the phone to landscape

Any possible solutions

Try disabling landscape with meta tags, for example, https://wpmudev.com/forums/topic/disable-landscape-mode-on-mobile/

Definition of done

Use an iOS & Android device, go over the reproduction steps and make sure the phone stays in portrait mode.

Webhook handler

Primary button not working on large height screen phones

Issue
Something breaks in the layout and prevents the primary button from being clickable on mobile when the phone's screen height is above a certain size.
How to reproduce

• Open the flow
• On the first screen open "Inspect element"
• Change the view to "iPhone XR" (happened on other views as well)
• Try clicking the button > doesn't work
• then change the view to "iPhone SE"
• Try clicking the button > works

Test

Backoffice case filter

• Create two jsons with an id , kind, create one filter for individuals and one for businesses
• Render a list of routes by iterating over the filters and using the kind property as a label and the id as a path param
• Send the filter id to the lists fetch requests
• Change zod schemas based on fetched entity

Show a loader until the camera loads and only then enter the camera screen

Subject

Bug - The camera loads while the user is on the camera screen

Description

After entering the camera screen (where you take a picture of a document or a selfie) there are a few moments until the camera loads and appear on the screen. In the meanwhile, the user sees a grey screen.
This causes two problems:

1. The experience looks buggy and increases anxiety.
2. If the user clicks the camera button before the camera loads the flow will proceed to the next step, without an image taken.

Has the bug been reported before

No.

Expected Behaviour

After giving permission to use the camera and right before entering any camera screen, hold the flow on the current screen the user is in and put a loader for until the camera loads and the flow can proceed.
Once the camera has loaded, enter the camera screen.

Actual Behaviour

The user enters the camera screen and sees a blank page where the camera content should be presented, with UI on top of it.
Only once the camera has been loaded it appears on the screen.

Environment

• All environments

Steps to Reproduce

1. Enter the flow
2. Choose a document to upload
3. Approve camera permissions
4. Enter the camera screen
5. See the blank background
6. Once the camera loads it will show up

Any possible solutions

Use the loader that exists in Ballerine's flow: sdks/web-sdk/src/lib/atoms/Loader/Loader.svelte
Change the text on the loader to be: "Initiating camera"

Definition of done

1. Enter the flow
2. Choose a document to upload
3. Approve camera permissions
4. See a loader
5. Enter the camera screen when the camera is already running

Specify Node version using `.nvmrc`

Update prisma to latest version (workflow-service)

The latest Prisma versions have some performance improvements (4.13.0)

Once upgrade please run some e2e flow (like pnpm run kyc-manual-review-example) to check everything works

Test event endpoint, refactor plan (0.7 days)

1. understand best "logic definition" for the event ( 0.1 days )
2. generate test ( 0.4 days )
3. refactor plan ( 0.2 days )

Fix cyclical dependencies

[ ] - install eslint-plugin-import (https://www.npmjs.com/package/eslint-plugin-import)
[ ] - add import/no-cycle eslint rule to base eslint config (https://github.com/import-js/eslint-plugin-import/blob/HEAD/docs/rules/no-cycle.md)
[ ] - typescript support (https://github.com/import-js/eslint-plugin-import#typescript)

Make switching camera easier / possible

Description

Currently the default camera for taking ID card photos seems to be the selfie cam on my phone and I couldn't really find a way to switch it easily.

Suggestion

• If the user has one camera, use that.
• If the user has two cameras, provide a button to switch, and use the more suitable camera by default (by checking it's name, if possible and detecting words like "Front", "Rear")
• If the user has more than two cameras, provide a dropdown to switch, and also try to suggest the most suitable one.

Details

I tested using the live demo links in the repo.
Phone: OnePlus 7 Pro
Phone OS: Android 11 (stock)
Browser: Google Chrome 107.0

ID verification - Rejection Reasons

Description

I'd like the ability to enter in a "reject" reason when I reject the ID photo.

Alternatives

I don't think so

Does the feature have an issue or an open Canny ticket

Not sure

If the feature request is approved, would you be willing to submit a PR

Maybe

Examples and references

Links, screenshots, and other resources to help us understand the issue.

Illustration SVGs seem small on large screens

Right now it seems like the images take the size property from the one on the actual file.
this makes the images look small on large screens.
we can override the image size to be width 100%, and height 100% and it will fix it for all screens

Smoother transition animations on the new UI example theme.

Description

In order to make the experience of using the new UI them more appealing and trustworthy, the transitions between steps in the flow should be smoother.

###Tasks

• When clicking a button, make it so that the during the transition animation the background remains black instead of disappearing.

###Examples and references
Enter: https://examples-future.ballerine.app/ and see the colors and texts throughout the flow.

Create KYB basic workflow

Create kyb guide in readme

Case list filter

• Remove the user type filter
• Add a filter specific to a company
• Add a filter specific to an individual
• Change client-side filters based on fetched entity

Bug - Translations not working

Description

I have added translation overrides config for English & Swahili but can't seem to figure out how to change to other languages apart from English.

Has the bug been reported before

N

Expected Behaviour

A way to switch languages should be provided both - programmatically and through UI.

Actual Behaviour

Text is overridden for default locale only (English).

Environment

• Node version: v14.18.0
• Device, operating system and its version:
  • MacBook Pro 2017
  • MacOS Big Sur v11.6.5
• Browser and its version:
  • Chrome v108.0.5359.94 (Official Build) (x86_64)
• Version of the affected apps and packages:
  • next v13.0.6
  • react v18.2.0
  • @ballerine/web-sdk v1.1.38

Steps to Reproduce

1. pnpm create next-app
2. pnpm add @ballerine/web-sdk
3. Initialize UI flow https://github.com/ballerine-io/ballerine#embedded-flows

If the bug is confirmed, would you be willing to submit a PR

Maybe

Backend repo is not public

Backend repo is not set to public. How can we check the backend code?

BSA filing - SAR reports

Description

Do you plan to integrate with Fincen for e-filing SAR reports?

https://bsaefiling.fincen.treas.gov/

Move fetcher from browser-sdk and backoffice v2 to common package

Double-clicking on the "welcome" step action button produces an error and fails to move to the next step

Subject

Bug - Double-clicking on the "welcome" step action button produces an error and fails to move to the next step

Description

The navigation breaks when rapidly clicking on the action button on the "welcome" screen (probably can happen in other ones as well).

Has the bug been reported before

No.

Expected Behaviour

The flow should proceed to the next step without producing any error in the console.

Actual Behaviour

After pressing multiple times on the action button the flow proceeds to a blank page and the console has the following error:

Uncaught (in promise) TypeError: Cannot read properties of undefined (reading of 'type')

Environment

• Device, operating system, and its version:
  • All devices
• Browser and its version:
  • Tested on Chrome
• Version of the affected apps and packages:
  • Web SDK - 1.1.34

Steps to Reproduce

1. Enter the flow (https://simples-kyc-demo.ballerine.app).
2. When the first page appears (the "welcome" step), click multiple times on the action button ("Choose Document Type").

Any possible solutions, ranked high to low

1. Fix the issue on the route/flow manager level - make sure multiple activations of the navigation function don't break the flow
2. Make the button disabled after the first click

Solution pointers

Flow navigation mechanism: sdks/web-sdk/src/lib/contexts/navigation/hooks.ts:22
Welcome button: sdks/web-sdk/src/lib/pages/Welcome.svelte:60

Definition of done

Go over the whole flow and try to click rapidly on the action buttons when moving between steps - make sure the flow proceeds as usual and there a no console errors.

Define webhook schema, observe events and call webhook

• Base Schema
• Payload Schemas
• Webhook config

https://www.notion.so/ballerine/Webhook-schema-mapping-f3deaea449ac49cf8864d2b330bb1c37

Make all packages use shared eslint/prettier config

KYB workflow example

• Create a KYB workflow with a certificate of incorporation via the seed script
• Add an env var to the headless example to change between the kyb and kyc examples
• Map a document upload component to the certificate of incorporation state
• Add a policy to the KYB workflow via the seed script
• Generate two task blocks using the hardcoded policy mock
• On reject/approve in the backoffice task block make a call to the update workflow endpoint and update the relevant policy fields

Workflow docker image and ci/cd for it

Event Manager (Publisher)

Case filters - server-side

• Create a filter model
• Create a filter module, controller, service, repository
• Add a list filters endpoint
• Add a get filters by id endpoint
• Get a filter by filter id in getById and list service methods for end-users and businesses and pass the filter's query to the db
• Replace hardcoded filters in the backoffice with filters from the server

Workflow context schema

• Add to prisma schema
• Create minimal JSON schema for KYB-basic worflow
• On workflow creation validate context with JSON schema validation tools (TBD, probably ZOD)

Workflows service + backoffice authentication

• workflows service - use the auth decorators in the workflows service on endpoints consumed by the backoffice; end-users, workflows, storage, getting authenticated user
• backoffice - uncomment the API auth methods
• backoffice - receive the session cookie from the workflows service and add it to outgoing requests
• backoffice - re-add the sign in route
• backoffice - re-enable the auth provider and hooks
• backoffice - remove password strength from the sign in form
• backoffice - remove the sign in with google button
• backoffice - make the auth redirects work with dynamic routes (individuals/companies)

Create KYB example readme in github

"Future" KYC example UI changes

Description

In order to make the experience of the "Future" KYC example UI more appealing, please provide the following UI changes.

Tasks

• Change the paragraphs font color to white
• Change the CTA on the success and failure screens' buttons to “Close”
• Clicking on the success and failure screens CTA should redirect to Ballerine’s GitHub
• Add margins from the top of the "card back side" and "Selfie" illustrations (margin: 12vh auto;)

Examples and references

Enter: https://examples-future.ballerine.app/ and see the colors and texts throughout the flow.