Twill Brain

facade — Architecture

3 min read

facade

Repo: Twill-AI/facade
Language: Python
Description: Main back-end server for UI

README

Facade

Main back-end service for Twill-AI application facing the internet and serving front-end requests.

Setup

Install:

  • Poetry v2+ (pip install poetry). Don’t run poetry commands on this stage.
  • Docker (OS-specific command).
  • Make sure you you can clone github repos using SSH. (see instructions on how to add your ssh keys)
  • Run poetry config virtualenvs.in-project true (optional), poetry shell (terminal invitation should get prefix like “(facade-py3.12) ”), poetry install.
  • (for development) Install make command. See Makefile.
  • (for development) Run pip install pre-commit outside of any virtual environment to allow git to run it. Next pre-commit install. To run it on-demand use pre-commit run --all-files - note that it may update files.
  • (for development) install EditorConfig plugin for IDE.
  • (for development, optional) install Black, Flake8 plugins for IDE.

Run make version to generate “app/version” file. Duplicate .env.template into “.env” and set your values (actually only LLM required). Try to don’t use quotes because Docker understands them as part of value.

After pull-ing run make deps-sync to get fresh dependencies in local venv.

LLM specific ENV variables.

The LLM engine requires three external services to run:

  • Azure OpenAI
  • Forecasting
  • Langsmith Tracing

These services are configured through the following ENV variables:

AZURE_OPENAI__API_KEY=
AZURE_OPENAI__ENDPOINT=

FORECASTING_PREDICT_URL=

LANGCHAIN_API_KEY=
LANGCHAIN_TRACING_V2=
LANGCHAIN_ENDPOINT=

None of these setting are required to import the library but the corresponding services will not work if they are not set. Please note that not setting the AZURE_* variables means there is no LLM provider available and so the llm-engine is mostly unusable.

Authentication

Authentication happens through Supabase, with its JWT and Facade just verifies signature with secret key provided from it. See details in #2 of https://twillpayments.atlassian.net/wiki/spaces/TD/pages/58589185/Users+Security+Implementation

There are 2 main ways to authenticate:

  • With email and password. See POST /sign-up endpoint.
  • Through 3d party (OAuth2) providers. See POST /loginForTokenViaGoogle.

For local run authentication is mocked - any JWT would work.

Also note that new users will be very limited in access to API. Actually the only action here is to create tenant and “profile” via POST /api/v1/self-management/tenant.

Run PostgreSQL for tests with Docker Compose

Use make db command. Or manually run docker-compose up (with -d if don’t want to check logs and get it as daemon).

It would launch:

  1. PostgreSQL v15 on http://localhost:5432.
  2. Adminer (simple RDBMS UI) on http://localhost:5433. Here need to choose “PostgreSQL”, server “db

Recent Open Issues

  • #471 Create approximation function for current month commissions
  • #843 Track Merchant Processing Lifecycle
  • #1093 [Bug]: update card_type based on the bin list in transaction table
  • #832 Add authorization kpis
  • #1083 Merchant chat feature
  • #1115 Merchant Field extractor logic improvements
  • #1040 [bug] KPI and trend data mismatch
  • #1139 Processor matching
  • #1131 Get EMS equipment and fees data
  • #1132 Luqra and EMS Application Issues

Patterns & Notes

Dash adds architecture notes here as work progresses

Graph View