This repository implements the Three Letter Abbreviations (TLA) Sample Application of the Context Mapper project with serverless technology. It can easily be deployed on AWS. The following graphic gives an architecture overview of the app:
The app uses the following AWS services:
- Amazon API Gateway now serves the RESTful HTTP API to access the TLA's.
- AWS Lambda is used (one function per endpoint) to process the request events of the API gateway, load the data from a DynamoDB table and return a response event back to the gateway.
- Amazon DynamoDB is used to persist the TLA's.
- Amazon EventBridge is used to send events from the manager to the resolver
The app uses the following tools and frameworks:
- Maven to build the resolver app deployable (JAR)
- Spring Boot and Spring Cloud Function to implement the resolver functions.
- The AWS SDK for Java 2.x to connect the resolver functions to the DynamoDB and EventBridge.
- .NET to implement the manager functions.
- The AWS SDK for .NET to connect the manager functions to the DynamoDB and EventBridge.
- The Serverless Framework to deploy the whole application on AWS.
- Including the definition of the API endpoints, the DynamoDB table and the EventBridge.
- GitLab CI/CD Pipelines as CI/CD tool to automatically deploy the app to AWS.
The following graphic shows a more detailed architecture overview:
The "TLA Manager" and "TLA Resolver" communicate through events that are sent to an Amazon EventBridge. The EventBridge needs to be deployed before the other services, using the following commands:
cd eventbridge
serverless deployThis section documents the different types of events.
The general format of EventBridge events is documented in the Amazon documentation. All events use the "detail-type" to differentiate between the different types of events.
When accepting a TLA (see Accept a Proposed TLA) the "TLA Manager" sends an event to the EventBridge.
The event includes the necessary information for the "TLA Resolver" to add the accepted TLA to its database.
The event has a detail-type of TLA_Accepted.
The detail of the event has the following format:
{
"tlaGroupName": "{Name of Group}",
"tlaGroupDescription": "{Description of TLA Group}",
"tlaName": "{Name of TLA}",
"tlaMeaning": "{Meaning of TLA}",
"tlaAlternativeMeanings": [
"{Alternative meaning 1}",
"{Alternative meaning 2}"
],
"tlaLink": "{tla link, nullable}"
}Here, an example of an actual event:
{
"version": "0",
"id": "4fb14a18-76fe-f6c8-eccf-65d23adfecbb",
"detail-type": "TLA_Accepted",
"source": "TLAManager",
"account": "64...72",
"time": "2025-05-26T10:52:59Z",
"region": "us-east-1",
"resources": [],
"detail": {
"metadata": {
"version": "1.0",
"created_at": "5/26/2025 10:52:59 AM",
"domain": {
"name": "TLAs",
"subdomain": "review_process",
"service": "TLAManager",
"category": "domain_event",
"event": "TLA_Accepted"
}
},
"data": {
"tlaGroupName": "OST",
"tlaGroupDescription": "OST modules",
"tlaName": "CldSol",
"tlaMeaning": "Cloud Solutions",
"tlaAlternativeMeanings": [],
"tlaLink": null
}
}
}As a prerequisite, you must have the .NET 10 SDK and the serverless CLI installed.
Building the app is done using the dotnet CLI. We provide a build script which executes the necessary commands for you:
cd manager
./.build.shThe command above creates a zip file bin/release/net10.0/deploy-package.zip which contains all the functions (lambdas) of the app.
Once successfully built, the app is easily deployed with:
serverless deployNote: serverless deploy only works if you have already set up the serverless framework locally, including logging in and connecting to your AWS account. See the Serverless Framework documentation for more information on how to do this.
Once serverless deploy was successful, you can fill the DynamoDB table with some sample data by executing our seedDatabase function. You can do this via the following command:
sls invoke --function seedDatabase --data 'unused'Now you can access the TLA's via the apps API.
The manager currently supports the following use cases, for which we provide some sample CURLs.
Disclaimer: Please note that we have not implemented any identity and access control measures for this sample application. All endpoints are publicly available; including the writing ones (commands).
Note that you will need to replace {baseUrl} with the URLs you get from sls deploy in all the following examples.
| Endpoint | Method | Description |
|---|---|---|
| /tlas | GET | Get all TLA groups including their TLAs (accepted TLAs only). |
| /tlas?status=PROPOSED | GET | Get TLAs in PROPOSED state. |
| /tlas | POST | Create a new TLA group (see sample payload below). Containing TLAs will be in PROPOSED state. |
| /tlas/{groupName} | POST | Create a new TLA within an existing group (see sample payload below). The created TLA will be in PROPOSED state. |
| /tlas/{groupName}/{name}/accept | PUT | Accept a proposed TLA (state transition operation: PROPOSED -> ACCEPTED). |
The /tlas (GET) endpoint returns all TLAs of all TLA groups that are in the ACCEPTED state (read on to see how to propose and accept new TLAs). Note that all TLAs are part of a group.
CURL: curl -X GET {baseUrl}/tlas
Sample output:
[
{
"name":"common",
"description":"Common TLA group",
"tlas":[
{
"name":"TLA",
"meaning":"Three Letter Abbreviation",
"alternativeMeanings":[
"Three Letter Acronym"
]
}
]
},
{
"name":"AppArch",
"description":"Application Architecture",
"tlas":[
{
"name":"ADR",
"meaning":"Architectural Decision Record",
"alternativeMeanings":[
],
"link":"https://adr.github.io/"
}
]
},
{
"name":"DDD",
"description":"Domain-Driven Design",
"tlas":[
{
"name":"ACL",
"meaning":"Anticorruption Layer",
"alternativeMeanings":[
]
},
{
"name":"CF",
"meaning":"Conformist",
"alternativeMeanings":[
]
},
{
"name":"OHS",
"meaning":"Open Host Service",
"alternativeMeanings":[
]
},
{
"name":"PL",
"meaning":"Published Language",
"alternativeMeanings":[
]
},
{
"name":"SK",
"meaning":"Shared Kernel",
"alternativeMeanings":[
]
}
]
}
]Note that the endpoint returns all TLAs in state ACCEPTED by default.
Use the query parameter status with the value PROPOSED to list TLAs in the PROPOSED state (see example below under "Query Proposed TLAs").
Via /tlas (POST) you can create a new TLA group.
Sample CURL 1 (without containing TLA):
curl --header "Content-Type: application/json" \
-X POST \
-d '{ "name": "FIN", "description": "Finance TLAs", "tlas": [] }' \
{baseUrl}/tlasSample CURL 2 (with containing TLA):
curl --header "Content-Type: application/json" \
-X POST \
-d '{ "name": "FIN", "description": "Finance TLAs", "tlas": [ { "name": "ROI", "meaning": "Return on Investment", "alternativeMeanings": [] } ] }' \
{baseUrl}/tlasSample output: (created group is returned)
{
"name": "FIN",
"description": "Finance TLAs",
"tlas": [
{
"name": "ROI",
"meaning": "Return on Investment",
"alternativeMeanings": []
}
]
}Note that the new TLA is now in state PROPOSED and not delivered by the endpoints mentioned above. They only return TLAs in state ACCEPTED by default. Use the following endpoint ("Accept a Proposed TLA") to accept a proposed TLA.
With the endpoint /tlas/{groupName} (POST) you can add a new TLA to an existing group.
Sample CURL:
curl --header "Content-Type: application/json" \
-X POST \
-d '{ "name": "ETF", "meaning": "Exchange-Traded Fund", "alternativeMeanings": [] }' \
{baseUrl}/tlas/FINSample output: (updated group is returned)
{
"name": "FIN",
"description": "Finance TLAs",
"tlas": [
{
"name": "ETF",
"meaning": "Exchange-Traded Fund",
"alternativeMeanings": []
},
{
"name": "ROI",
"meaning": "Return on Investment",
"alternativeMeanings": []
}
]
}Note that the new TLA is now in state PROPOSED and not delivered by the endpoints mentioned above. They only return TLAs in state ACCEPTED by default. Use the following endpoint ("Accept a Proposed TLA") to accept a proposed TLA.
The endpoint /tlas (GET) offers a query parameter to list all TLAs in the PROPOSED state: /tlas?status=PROPOSED
Sample CURL: curl -X GET {baseUrl}/tlas?status=PROPOSED
Sample output:
[
{
"name": "FIN",
"description": "Finance TLAs",
"tlas": [
{
"name": "ETF",
"meaning": "Exchange-Traded Fund",
"alternativeMeanings": []
},
{
"name": "ROI",
"meaning": "Return on Investment",
"alternativeMeanings": []
}
]
}
]With the endpoint /tlas/{groupName}/{name}/accept (PUT) you can accept a TLA ("name") within a group ("groupName").
This is a so-called state transition operation.
Sample CURL: curl -X PUT {baseUrl}/tlas/FIN/ROI/accept (puts the TLA 'ROI' in group 'FIN' into state ACCEPTED)
This endpoint does not expect a body (JSON) and does also not return one. The command is successful if HTTP state 200 is returned.
Once the TLA is accepted, the query endpoints listed above (such as /tlas or /tlas/{groupName}) will now list them.
Acceptance of a TLA sends an Accept TLA Event to the "TLA Resolver" to add the TLA (and possibly also a new group) to its database. After this event is handled by the resolver, the query endpoints of the resolver will also list this TLA.
Building the app and its JAR file is done with Maven:
cd resolver
./mvnw clean packageThe command above creates a JAR file target\tla-resolver-serverless-1.2-SNAPSHOT-aws.jar which contains all the functions (lambdas) of the app. Once successfully built, the app is easily deployed with:
serverless deployNote: serverless deploy only works if you have already set up the serverless framework locally, including logging in and connecting to your AWS account. See the Serverless Framework documentation for more information on how to do this.
Once serverless deploy was successful, you can fill the DynamoDB table with some sample data by executing our seedDatabase function. You can do this via the following command:
sls invoke --function seedDatabase --data 'unused'Now you can access the TLA's via the apps API.
The resolver currently supports the following use cases, for which we provide some sample CURLs.
Disclaimer: Please note that we have not implemented any identity and access control measures for this sample application. All endpoints are publicly available; including the writing ones (commands).
Note that you will need to replace {baseUrl} with the URLs you get from sls deploy in all the following examples.
| Endpoint | Method | Description |
|---|---|---|
| /tlas | GET | Get all TLA groups including their TLAs. |
| /tlas/{groupName} | GET | Get all TLAs of a specific group. |
| /tlas/all/{name} | GET | Search for a TLA over all groups. This query can return multiple TLAs as a single TLA is only unique within one group. |
The resolver only lists TLA that have been accepted in the "TLA Manager". To add a new TLA to the resolver, see the Accept a Proposed TLA API of the "TLA Manager".
The /tlas (GET) endpoint returns all TLAs of all TLA groups. Note that all TLAs are part of a group.
CURL: curl -X GET {baseUrl}/tlas
Sample output:
[
{
"name":"common",
"description":"Common TLA group",
"tlas":[
{
"name":"TLA",
"meaning":"Three Letter Abbreviation",
"alternativeMeanings":[
"Three Letter Acronym"
]
}
]
},
{
"name":"AppArch",
"description":"Application Architecture",
"tlas":[
{
"name":"ADR",
"meaning":"Architectural Decision Record",
"alternativeMeanings":[
],
"link":"https://adr.github.io/"
}
]
},
{
"name":"DDD",
"description":"Domain-Driven Design",
"tlas":[
{
"name":"ACL",
"meaning":"Anticorruption Layer",
"alternativeMeanings":[
]
},
{
"name":"CF",
"meaning":"Conformist",
"alternativeMeanings":[
]
},
{
"name":"OHS",
"meaning":"Open Host Service",
"alternativeMeanings":[
]
},
{
"name":"PL",
"meaning":"Published Language",
"alternativeMeanings":[
]
},
{
"name":"SK",
"meaning":"Shared Kernel",
"alternativeMeanings":[
]
}
]
}
]The endpoint /tlas/{groupName} (GET) returns all TLAs of a specific group.
Sample CURL: curl -X GET {baseUrl}/tlas/DDD
Sample output:
{
"name": "DDD",
"description": "Domain-Driven Design",
"tlas": [
{
"name": "ACL",
"meaning": "Anticorruption Layer",
"alternativeMeanings": []
},
{
"name": "CF",
"meaning": "Conformist",
"alternativeMeanings": []
},
{
"name": "OHS",
"meaning": "Open Host Service",
"alternativeMeanings": []
},
{
"name": "PL",
"meaning": "Published Language",
"alternativeMeanings": []
},
{
"name": "SK",
"meaning": "Shared Kernel",
"alternativeMeanings": []
}
]
}With the endpoint /tlas/all/{name} (GET) you can search for a TLA through all groups. Note that this might return multiple results, as TLAs are only unique within one group.
Sample CURL: curl -X GET {baseUrl}/tlas/all/ACL
Sample output:
[
{
"name": "DDD",
"description": "Domain-Driven Design",
"tlas": [
{
"name": "ACL",
"meaning": "Anticorruption Layer",
"alternativeMeanings": []
}
]
}
]Contributions are always welcome! Here are some ways how you can contribute:
- Create GitHub issues if you find bugs or just want to give suggestions for improvements.
- This is an open source project: if you want to code, create pull requests from forks of this repository. Please refer to a GitHub issue if you contribute this way.
This refactored version of the original serverless TLA sample application was implemented by Anja Friedrich and Mona Panchaud as part of a group assignment for the Cloud Solutions course at OST in the spring semester of 2025. Many thanks to Anja and Mona for their contribution!
This project is released under the Apache License, Version 2.0.
