Skip to content

Contribute to Tock

The Tock project is open to contribution and any feedback is welcome!

This page details the source structure and coding conventions for the platform.

TL;DR

See CONTRIBUTING.md.

Main technologies

See Technologies on the home page.

Source structure

Repositories

The tock repository

Here is an overview of the sources of the tock repository (see also the packages page):

  • bot: the conversational platform (interfaces, API, connectors, etc.), depending on the NLU modules
  • docs: this documentation site, built with MkDocs
  • etc: utility scripts
  • gen-ai: the Gen AI orchestrator (Python) and its Kotlin client
  • nlp: the NLU platform alone (interfaces, API, entity models, etc.)
  • scripts: other utility scripts, for instance to develop on Messenger with ngrok
  • shared: Kotlin components shared between the modules of the framework
  • stt: speech-to-text implementations and wrappers
  • translator: implementations and wrappers for multilingual bots (i18n)

Note: there are "two admins" (i.e. two Tock Studio interfaces) in the sources. The NLU / NLP platform can indeed be installed alone, without the conversational tools. Hence:

  • nlp/admin: the components and interfaces for NLU / NLP only
  • bot/admin: reuses the NLP / NLU components (as Maven dependencies) and rebuilds the interfaces, adding the conversational tools

The tock-docker repository

The repository contains a Maven module structure mirroring the components of the Tock platform. Each module holds the Docker implementation of a component and relies on the io.fabric8:docker-maven-plugin Maven plugin to wrap the Docker build.

At the root of the repository, several Docker Compose descriptors deploy a platform from the already built images. Different configurations are available, including Bot API mode, integrated mode, standalone NLU platform, etc. The reference descriptor for the Bot API mode is docker-compose-bot.yml.

Build & run

Build Tock from sources

Tock (core)

Tock is built with Maven, including the Web modules leveraging NPM and Angular. It requires a JDK 21 or later; Node.js is downloaded by the Maven build for the Web modules:

$ mvn package

Continuous integration builds run on GitHub Actions.

Docker images

Tock Docker images can be rebuilt from sources, included in repository tock-docker. One can use Maven to trigger the Docker build:

$ mvn package docker:build

Docker containers can then be instantiated from images, or Docker Compose stacks from the various descriptors at the root of the repository.

Run Tock in IDE

To run Tock using Docker Compose outside the IDE, rather see Deploy Tock with Docker.

Tock components (NLU, Studio, bot...) can run in an IDE, such as
IntelliJ, Eclipse or Visual Studio Code for instance.

Beside the Docker images, IntelliJ configurations are provided with Tock sources:

The OpenDataBot example also has a run configuration available:

To start the Tock Studio interfaces, please refer to the commands described in the following page:

Code

Commits & merge requests

To submit a feature or bugfix:

  1. Create an issue:
  2. Recommended format for the title: - [Component] Title where component might be Studio, Core, Doc, etc. and title usually is like Do or fix something
  3. Create a pull request and link it to the issue(s):
  4. All commits should be signed
  5. Please rebase and squash unnecessary commits (tips: PR can be tagged as Draft) before submitting
  6. Recommended format for the branch name :
    • ISSUEID_short_title
  7. Recommended format for the commit(s) message(s):
    • resolves #ISSUEID Component: title for features
    • fixes #ISSUEID Component: title for fixes

Code conventions

Kotlin Code Conventions are used.

Unit tests

Every new feature or fix should embed its unit test(s).

Contact us

To contribute to the project or to known more about the implementation, feel free to contact us. Ideas and feedback is more than welcome.

Chat with Tock
×