BankX Application by Caroline Jones
1. Overview:
The application is a Spring REST interface which consists of the following technologies:
- Spring Boot 3.0.5, with Java 17.
- Choice between MySql or H2.
- Kafka and Zookeeper for offline processes.
- Freebase for push notifications.
- Maven as the build tool.
No frontend is provided. However, a Postman project will be shared on request.
JSON examples files have been provided in the resources folder.
The application runs as a stand-alone jar file. A docker-compose.yaml file is provided to
create the Kafka and Zooper servers that it needs. It can be configured to use an existing Kafka setup.
2. Quick Start:
To get going quickly, use the defaults and take the following steps:
2.1. Clone the project:
https://github.com/codingthemystery/bank-x-app.git
2.2. Start up Docker.
2.3. Navigate to root directory of the project and enter the command to start up the Kafka server configuration:
docker-compose.yaml
2.4. Check that the containers broker and zookeeper are running:
docker ps
2.5. Run the mvn build command:
mvn package
2.6. Run the application:
java -j target/Bankx-1.0.0-SNAPSHOT.jar
2.7. Use the following URL in Postman to access the API endpoint. For a link to the existing Postman
project, send an email to [email protected] so that the link can be shared.
http://localhost:8080
Locate the sample JSON files in the resources folder. The API endpoints are documented below.
2.8. To view data in the in-memory H2 Database, open your browser and type this URL: (Use the default name and a blank
password:
http://localhost:8080/h2-console
3. Configuring the Application:
3.1. Clone the application from GitHub:
https://github.com/codingthemystery/bank-x-app.git
3.2 Configure the Spring Environment:
3.2.1. There are three Maven profiles in pom.xml: DEV, STAGE and PRD. STAGE is set as the default will be used if
none is provided at build time.
3.2.2. There are two Spring profiles: win and linux. The spring.profiles.active property (in the application.properties file)
is set at build time depending on which Maven profile is used to build the project.
Currently, DEV will activate the win profile and STAGE and PRD will activate the linux profile. This
can be changed in the pom.xml file or at build time using the -P [profile.id] operator on the Maven command).
<profiles>
<profile>
<id>DEV</id>
<properties>
<spring.profiles.active>win</spring.profiles.active>
</properties>
<activation>
<activeByDefault>false</activeByDefault>
</activation>
</profile>
<profile>
<id>STAGE</id>
<properties>
<spring.profiles.active>linux</spring.profiles.active>
</properties>
<activation>
<activeByDefault>true</activeByDefault>
</activation>
</profile>
<profile>
<id>PRD</id>
<properties>
<spring.profiles.active>linux</spring.profiles.active>
</properties>
<activation>
<activeByDefault>false</activeByDefault>
</activation>
</profile>
</profiles>
3.2.3. Go to src/main/resources and change the application-win.properties or application-linux.properties as necessary.
3.3. Configure Logging:
The application uses Logback. The location of the logs differs depending on the Spring profile.
3.3.1. To adjust the settings, navigate to the /src/main/resources folder and makes changes to:
logback-spring.xml
3.4. Configure the database:
There are two database configurations: MySql and H2. By default, the win profile uses MySql and the linux profile
H2 but this can be changed.
3.4.1. To run the application in memory with the database, schema and data being refreshed on each startup, use these
settings: (this is the default setting with the linux profile)
spring.datasource.url=jdbc:h2:mem:bankx
spring.jpa.hibernate.ddl-auto=create-drop (options: create, create-drop, validate, update)
spring.sql.init.mode=always
3.4.2. If you want to persist the data, you first need to get the database schema (and database in the case of H2)
created by Spring and then change the settings afterwards. The settings below will create the schema and run the data.sql script
to populate the database tables.
spring.jpa.hibernate.ddl-auto=create-drop (options: create, create-drop, validate, update, none)
spring.sql.init.mode=always
3.4.3. Once the database has been created, change the settings to:
spring.jpa.hibernate.ddl-auto=none
spring.sql.init.mode=never
3.4.4. If using H2, use this setting to persist to the file system instead of using an in-memory only database instance:
spring.datasource.url=jdbc:h2:file:./data/bankx
3.4.5. Otherwise, use Mysql as your databse. It needs to be installed separately and the bankx database needs to be create manually before running the app:
CREATE DATABASE `bankx`
To recreate, first use this command:
USE `bankx`;
DROP DATABASE `bankx`;
Test with:
SHOW DATABASES;
3.5. Configure Bank IDs:
3.5.1. At application startup, a data.sql file in the resources folder, polulates the database. Bank X and Bankz Z are created,
along with customers, accounts and transactions.
3.5.2. CHECK THAT THE ID VALUES FOR BANK X AND BANK Z ARE 1 AND 2 RESPECTIVELY. IF NOT, CHANGE THESE PROPERTIES
IN THE SPRING PROPERTIES FILE NEED TO BE UPDATED TO MATCH YOUR DATABASE:
bankx.bankid=1
bankz.bankid=2
3.6. Setup Kafka
The application requires a Kafka/Zookeeper server setup. You can change the configuration in the application-[profile].properties file
to use an existing server, or you can use the provided docker-compose.yaml script to create a server environment.
3.6.1. To use an existing environment, alter this setting in the Spring property file:
spring.kafka.bootstrap-servers=localhost:9092
3.6.2. Topics:
The following topics are created at startup: (See below how to view them on the Kafka server.)
transactions
transactions-reponses
reconciliations
reconciliations-responses
3.6.3. The groupid can be adjusted in the Spring properties file:
bankz.groupid=bankz
3.7. Build the Application:
If no profile is added to the command, STAGE will be used by default, activating
the Spring linux profile. You can use the -P flad to use a different configuration.
3.6.1.1. From the root directory of the project, type:
mvn package (optional: -P [DEV, STAGE or PRD])
3.6.1.2. To check, which profile is active, run this command:
mvn help:active-profiles
4. Running the Application:
4.1. Starting Kafka/Zookeeper:
4.4.1. Docker needs to be installed on the machine and running. From the project's root directory, run:
docker-compose up -d
4.1.2. Make sure both the broker and zookeeper containers are running:
docker ps
Useful commands:
docker ps
docker stop [containerName]
docker kill [containerName]
4.2 To access the topics type:
docker exec --interactive --tty broker kafka-console-producer --bootstrap-server broker:9092 -topic [topicName] --from-beginning
Enter CTRL+C to exit.
4.3. To run the applications, from the projects root directory, type:
java -jar Bankx-1.0.0-SNAPSHOT.jar
Alternatively, you can run the app without packaging it using:
mvn spring-boot:run
Use CTRL+C to cancel.
The app will start running on http://localhost:8080
4.4 Explore the APIs:
The application provides two APIs. The first is accessed directly through REST API calls; the second uses
Kafka to write and read from topics. The intent is that internal systems and a front-end app would use the
first API, while external organizations, such as Bank Z would use the latter.
4.4.1. Internal REST API:
4.4.1.1 Basic CRUD Calls:
There are four database tables:
banks
customers
accounts
transactions
4.4.1.2. Access the CRUD APIs with these standard URLS: :
4.4.1.2.1. Get all records:
GET http://[hostname:port]/[table]
4.4.1.2.2. Get single record by Id:
GET http://[hostname:port]/[table]/[id]
4.4.1.2.3. Create a new record:
POST http://[hostname:port]/[table]
4.4.1.2.4 Update a record:
PUT http://[hostname:port]/[table]/[id]
4.4.1.2.5. Delete a record:
DELETE http://[hostname:port]/[table]/[id]
Deletions are set to cascade and any records in dependent tables will be deleted too. For instance, deleting
an account will delete all transactions for that account. Deleting a customer will delete all accounts and
transactions for that customer. Deleting a bank will delete all customers, accounts and transactions for
that bank.
4.4.1.2. Additional Endpoints:
4.4.1.2.1. Get Account by cardNumber:
http://localhost:8080/accounts/card?cardnumber=[cardNumber]
4.4.1.2.2. Get Accounts by CustomerId:
GET http://[hostname:port]/customers/accounts/[customerId]
4.4.1.2.3. Customer Onboarding:
POST http://[hostname:port]/customers
This will create a new customer, a SAVINGS and a CURRENT account with a starting bonus of R500. A record in the
transactions database will reflect this credit.
4.4.1.2.4 Transactions:
There are several types of transactions, each with their own rules:
TRANSFER
PAYMENT
CREDIT
DEBIT
FEE
INTEREST
4.4.1.2.4.1. To process a transaction, enter the following POST and include the relevant transactionType in the JSON body:
POST http://[hostname:port]/transactions
4.4.1.2.4.2. Multiple transactions can be sent at once for immediate processing:
POST http://[hostname:port]/transactions/multi
4.2.2. The Bank Z API:
This service uses a DTO for Transaction and therefore the JSON is slightly different. This API
allows for offline and off-peak processing of large numbers of transactions.
All services are accessed starting with /api:
http://[hostname:port]/api
4.2.2.1. Queries:
4.2.2.1.1. Get all Transaction originated by Bank Z. Order by External Reference.
GET http://localhost:8080/api/transactions
4.2.2.1.2. Get Transaction by Transaction Id (Currently doesn't restrict to Bank Z only)
GET http://localhost:8080/api/transactions/[transactionId]
4.2.2.2. Transactions: (topics: transactions, transactions-responses)
Batches of Transactions are submitted to Kafka topics to be processed offline.
4.2.2.2.1. To post a batch of Transactions to the transactions topic for processing, post a batch of tranaction to this URL:
POST http://localhost:8080/api/transactions/batch
View on the Kafka server with this command:
docker exec --interactive --tty broker kafka-console-consumer --bootstrap-server broker:9092
\ --topic transactions --from-beginning
4.2.2.2.2. Retrieve responses with the URL below. If this endpoint is not yet implemented, view responses on the Kafka server.
GET http://localhost:8080/api/transactions/batch
docker exec --interactive --tty broker kafka-console-consumer --bootstrap-server broker:9092
\ --topic transactions-responses --from-beginning
4.2.2.3. Reconciliations: (topics: reconciliations, reconciliations-responses)
Batches of Reconciliations are submitted to Kafka topics to be processed offline. Reconciliations use the same structure as
transactions but with different statuses. They look up the original tranactions and check if it was persisted to the database, the
amount and other details. Error codes and statuses are returned with the reconciliations-reponses topic.
4.2.2.3.1. To post a batch of Reconciliations to the reconciliations topic for processing, post this URL with
a batch of reconcilions in the body to:
POST http://localhost:8080/api/transactions/reconciliations
View on the Kafka server with this command:
docker exec --interactive --tty broker kafka-console-consumer --bootstrap-server broker:9092
\ --topic reconciliations --from-beginning
4.2.2.3.2. Retrieve responses with the URL below. If this endpoint is not yet implemented, view responses on the Kafka server.
GET http://localhost:8080/api/transactions/reconciliations
docker exec --interactive --tty broker kafka-console-consumer --bootstrap-server broker:9092
\ --topic reconciliations-responses --from-beginning
5. Known Limitations and Bugs:
Due to time restrictions, some features haven't been fully implemented. There are also a few bugs.
5.1. Lack of a frontend. You can use Postman to interact with the API in the meantime. Contact Caroline on [email protected] for a link
to the Postman project with all the API endpoints and test data.
5.2. Firebase:
Firebase is used to send push notifications to customers to notify them of transactions. For it to be fully implemented, however, the customer
would need to login and receive a token from FCMs server. Without this token, notifications fail.
5.3. Nice to have: Add Spring bacth scheduling to the Kafta consumer processes so they can run during off-peak hours.
5.4. Retrieving the responses for the batch submissions is not yet implemented. The producer code may need to change too.
5.5. Testing:
Unit and Integrations test have not been provided. The CRUD has been well tested but transactions and reconciliations may include bugs.
Reconciliations have been fully tested. Cross bank transaction handling is not clearly defined or consistently implemented.