TalkAdvisor

TalkAdvisor is a hexagonal architecture demo application developed with Kotlin and SpringBoot. This application recommends IT Talks recorded on YouTube given some criteria

Build

To build TalkAdvisor, run the following command:

mvn clean install

By default the build will run the integration acceptances tests against an isolated TalkAdvisor instance using wiremock to stub external services.

Launching the End to End tests

To launch those tests, you need first a run a "deployed" instance of TalkAdvisor. Please refer to Running the application.

Then you can launch the end-to-end tests:

cd talkadvisor-infra/talkadvisor-infra-acceptance-tests
mvn test -De2e

Running the application

Production mode

In order to run TalkAdvisor in "production" mode, you need to generate a Google Api Token. Once the token generated, you can define an environment variable named GOOGLE_API_KEY which will be automatically taken by TalkAdvisor.

Then you'll be able to run TalkAdvisor as follow:

cd talkadvisor-infra/talkadvisor-infra-application
mvn spring-boot:run

or

cd talkadvisor-infra/talkadvisor-infra-application
java -jar target/talkadvisor-infra-application-0.0.1-SNAPSHOT.jar

You can also use: --GOOGLE_API_KEY= in the command line if you don't want to store it in your env.

Development mode

If you don't want to generate a Google Api Token, you can launch TalkAdvisor with an embedded wiremock which will stub YouTube by adding --spring.profiles.active=YouTubeStub to the command line. You can also use the search talk domain stub with --spring.profiles.active=searchTalksStub, it will stub TalkAdvisor at the SPI level so http calls will be made and no wiremock instance will be launched.

Living Documentation

Once TalkAdvisor is running, you can reach the documentation of the REST API with this URL

http://localhost:7777/docs/rest-api.html

Technical Overview

TalkAdvisor is composed of 4 different modules:

talkadvisor-domain the inside of the hexagon

This single module holds all the business value of the application where you find its aggregate Recommendation. Maven has been configured such a way to prevent any external artifacts from being imported in the domain:

            <plugin>
                <artifactId>maven-enforcer-plugin</artifactId>
                <executions>
                    <execution>
                        <goals>
                            <goal>enforce</goal>
                        </goals>
                        <configuration>
                            <rules>
                                <bannedDependencies>
                                    <excludes>
                                        <exclude>*</exclude> <!-- forbids non domain dependencies -->
                                    </excludes>
                                    <includes>
                                        <!-- but allow kotlin dependencies-->
                                        <include>org.jetbrains.kotlin:*</include>
                                        <include>org.jetbrains:annotations</include>
                                        <!-- and commons-lang3 because we don't want to make the wheel again -->
                                        <include>org.apache.commons:commons-lang3</include>
                                        <!-- and test dependencies-->
                                        <include>*:*:*:*:test</include>
                                    </includes>
                                </bannedDependencies>
                            </rules>
                        </configuration>
                    </execution>
                </executions>
            </plugin>

if any dependency is added to the pom, the build will fail if it is not allowed in this list.

talkadvisor-infra the outside of the hexagon

All the adapters are gathered in the talkadvisor-infra modules. talkadvisor-infra is a parent pom which centralizes the common configurations of all the adapters (Spring Boot BOM,...). The infrastructure is divided in 3 modules.

talkadvisor-infra-application

The whole application resides in this module. You can find here the controllers, the YouTube Client (SPI Adapter), the REST resources (API Adapter), and the Spring Boot Application.

talkadvisor-infra-external-stubs

Holds the stubs of the external services, basically this is a wiremock-based infrastructure where have been stored some responses payloads of the request we make to YouTube. Those stubs are launched during the integration acceptance tests in order to totally isolate the CICD build of TalkAdvisor. They can also be used to run the application, see Running the application.

talkadvisor-infra-acceptance-tests

Integration acceptance and end to end tests of the application. They are launched at each builds against a local instance of TalkAdvisor with the external stubs. The end to end tests can also be launched against a deployed instance plugged with real calls to YouTube, see launching the end to end tests.

Testing Strategy

If you wan to learn more on the testing strategy applied in TalkAdvisor, here is the dedicated documentation.

Contributors

Julien Topçu - @JulienTopcu

Jordan Nourry - @JkNourry

Juliette de Rancourt - @ju_derancourt

From craftsrecords.org

Special Credit

TalkAdvisor Project Icon made by Freepik from www.flaticon.com