Skip to content

Code structure

Jump to bottom
msnwatson edited this page Apr 24, 2023 · 15 revisions

This page does not seek to explain testing and how it is performed or the runtime/deployment infrastructure for the VRO project.

This page also does not seek to explain the details of any domain-specific code that is accessible within the VRO app. Each domain should include a separate page which provides details about its logic and components.

Initial things to review

Application Entrypoint

VRO exposes a single API through a Java Spring Boot Application within the app subproject. The exact structure of the API endpoints along with the expected form of requests and responses can be subject to frequent changes. VRO uses OpenAPI to allow for dynamic creation of documentation for API endpoints. LHDI Docs for using OpenAPI for applications (requires membership in abd-vro Github team)

To see the most recent VRO API spec, run the software and browse to http://localhost:8080/swagger.

The Spring MVC framework is used to define the implementation of the Spring Boot Application, giving the following key components for defining the application logic:

  • api defining VRO's API
  • controller for the API
  • persistence:model defining DB Entity classes
  • service:db for DB interactions
  • service:spi containing Java interface and model definitions
  • service:provider containing Apache Camel configurations

The following is a basic graphic depiction of the application

Domain-Specific Logic

As VRO is a host of domain-specific logic, the Spring Boot Application defined within the app Gradle subproject takes a dependency on Gradle subprojects of the form domain-* which are responsible for defining their own domain-specific API routes and controllers which can then be exposed through the base VRO Spring Boot Application.

For instance, logic specific to some ABC functionality would have code following the structure:

  • domain-ABC: domain-specific code with subfolders:
    • ABC-api-controller: module that defines domain API endpoints and controller
    • ABC-workflows: defines domain workflows (i.e., Camel Routes)
    • svc-*: domain microservices supporting the workflows

Camel Routes and Microservices

The Spring Boot web app processes a request by delegating to a workflow defined by Apache Camel routes. More information on Apache Camel and how it is used in this project can be found here.

Once a request is received by the Spring Boot application entrypoint, it can be routed by Camel through a number of different steps including to a microservice (discrete component which is responsible for completely handling a smaller piece of computation) via a message bus or to some data sink.

Current list of microservices (each has an associated Gradle subproject):

  • 2 Python assessors
  • 1 Python pdf generator
  • 1 Java client for LH API svc-lighthouse-api
  • 1 Java client for MAS API svc-mas-api (in development)

Note that clients to external APIs are also modeled as microservices for compatibility with Camel routes.

Since the Python microservices have common code, it is extracted into a shared library:

  • service-python/main-consumer.py

RabbitMQ is used as our message bus for transporting messages to microservices while Redis and Postgres are used as data sinks depending on the use case. Postgres is deployed as a containerized application through the help of a separate init container called db-init. Both definitions for Postgres and this init container are found in the top-level directory of the project.

Shared libraries

VRO offers utilities and DB classes as shared libraries for use by domain-specific classes.

  • shared/api folder: (Java) general API models
  • shared/controller folder: (Java) Controller utilities, including InputSanitizerAdvice
  • shared/lib-camel-connector folder: (Java) Camel utilities, including a Spring Configuration for Camel and CamelEntry
  • persistence folder: DB utilities, including Java Entities
  • Python MQ utilities to facilitate interaction with the MQ
  • domain (PR Move domain folder to new shared folder #551)

Putting It All Together: Project Folder Structure

  • app: VRO entrypoint; pulls in domain-specific api-controller modules
  • db-init: initializes and updates the database schema
  • postgres: defines a customized database container
  • shared: utility and library code shared across domains (Shared libraries)
  • svc-*: domain-independent microservices, typically for integrations (Shared microservices)
  • domain-ABC: domain-specific code with subfolders:
    • ABC-api-controller: module that defines domain API endpoints and controller
    • ABC-workflows: defines domain workflows (i.e., Camel Routes)
    • svc-*: domain microservices supporting the workflows
Clone this wiki locally