1. Abstract
In software design, modular design facilitates building large systems by decomposing functionality into independent modules where each module defines an interface for the behavior it implements. The modular design evolved into component-based design that emphasized separation of concerns and into distributed systems, which gave rise to web services, service-oriented architectures and event-driven architectures. This evolution led to Microservices architecture in which each service defines a bounded-context for the business domain of its functionality. Each service is autonomous, agile, loosely coupled, resilient, reliable, independently deployable and scalable. This architecture encourages use of abstraction, single-responsibility, DRY, dependency-inversion, common-closure, common-reuse, release-equivalence and persistence Ignorance principles. The software development teams often use Inverse Conway Maneuver to define a clear ownership of the service, which improves developer velocity. As cloud computing gained wider adoption over the last 15 years, microservice architecture was extended with the architecture of cloud native applications (CNA), which offer properties of Isolated State, Distribution, Elasticity, Automation, and Loose Coupling (IDEAL). The extended benefits of CNA and Microservice architecture include:
- Fit for purpose
- Rightsized and modular
- Elasticity
- Sovereign and tolerant
- Resilient and protected
- Controllable and adaptable
- Workload-aware and resource-efficient
- Agile and tool-supported
- Observability including metric, tracing, and logging
- Resilience
- Availability
- Independent, autonomous
- Zero-Trust Security
- Automation
- Decentralized governance
2. Applying Domain-Driven Design
Following sections examines primary concepts from the domain driven design:
2.1 Layers
The domain-driven design by Eric Evans simplifies the architecture of microservices, which builds upon layer architecture such as:
- presentation layer for user-interface.
- application layer for use-cases that define the behavior.
- domain layer for representing business rules and domain model.
- infrastructure layer for data access and persistence for the domain objects based on Persistence Ignorance and Infrastructure Ignorance principles.
2.2 Domain Model
The software development team and domain experts define model using workshop based Event Storming. The domain layer employs defines following types of model:
- Entity is a mutable object defined not by their attributes, but rather by a thread of continuity and identity.
- Value object is an immutable object defined by their attributes instead of an identifier.
- Domain events to notify data update.
The domain-driven design recommends rich behavior in entity objects in addition to the data attributes and cautions against AnemicDomainModel that only hold data attributes.
2.3 Aggregates
The entities and values can be clustered into aggregates that become a unit for retrieving and persisting data together. An aggregate entity becomes root for controlling lifecycle and access to the objects inside its boundary.
2.4 Ubiquitous Language
The domain model employs Ubiquitous Language to bring domain experts and software development team together and eliminate inaccuracies, contradictions and confusion from the model.
2.5 Services
The services define high-level business logic that doesn’t fit within the domain objects. The services are generally designed as stateless with clearly defined interfaces.
2.6 Repositories
The repositories implement data persistence logic for retrieving and persisting aggregate and entity objects.
2.7 Factories
The factories help create complex objects, values and aggregates.
2.8 Bounded Context
The Bounded Context defines the boundaries of the domain model, which may consists of other sub-domains. This becomes foundation for the boundary of microservices, where each service is cohesive and loosely coupled that avoids chatty communication between microservices.
2.9 Context Map
The context map help define boundaries of bounded context explicitly to prevent Big Ball of Mud architecture with following patterns:
- Shared Kernel shares a common domain model between teams.
- Partnership with mutual dependency between teams.
- Customer-Supplier defines an interface that supplier implements and consumer consumes it.
- Open Host Service / Published Language relies on well documented or readily available information for integration.
- Conformist where the downstream team conforms to the model of the upstream without any translation of models.
- Anticorruption Layer isolates and abstracts the downstream’s models from external system’s models by translation.
3. Applying Hexagonal Architecture
The hexagonal architecture or ports & adapter architecture by Alistair Cockburn defines ports to receive incoming requests, which is then translated to internal message or procedure by an adapter. Similarly, when the application need to connect to external systems on the driven side, it sends a message through a port to an adapter. The port and adapter architecture decouples driver side and driven side from the implementation technology.
The port uses a protocol or an application program interface (API) for communicating with the application, which is then translated by the adapter for internal consumption. When the application needs to connect to external systems such as database, it goes through similar port or interface and is then translated into underlying database protocol by the adapter. This architecture essentially uses Dependency Inversion and Inversion of control Principles by only depending on the ports and decoupling external and internal components from the implementation technology. The application is the core of the system that defines use-cases that can be triggered by CLI or UI. The application layer internally contains commands, handlers and services, which receives commands or queries from ports and communicates with external systems via ports and adapters. The application layer may trigger application events as an outcome of a use-case. The domain layer defines domain model and domain specific services, which are used by the application layer. The driver or primary side in hexagonal architecture allows users to initiate communication with the application core and the driven or secondary side within the application core initiates communication with external dependent systems.
4. Applying Onion Architecture
The Onion Architecture defines concentric circles for layers where all code can depend on layers more central, but code cannot depend on layers further out from the core. The Domain Model represents the state and behavior combination that models truth for the organization. The number of layers in application core will vary but it has domain model at the center. The interfaces for repository to to retrieve and persist data surrounds domain model and the interfaces for repository are defined in the application core. The Onion Architecture uses the Dependency Inversion principle to inject implementations for the interfaces defined in the application core.
5. Applying Clean Architecture
The Clean architecture defines concentric circles to represent different areas of software and uses dependency rule to point dependency inwards.
- The entities encapsulate business rules with behavior and data structure.
- The use-cases encapsulates application specific use-cases and orchestrates flow of data to and from the entities.
- The interface adapters convert data from the use cases and entities to external systems, which are used by presenters, views and controllers.
- The frameworks and drivers layer is composed of frameworks and tools such as the database and web framework.
The Clean Architecture uses Dependency Inversion Principle to communicate across boundaries with interfaces and inner circle does not depend on outer circle.
6. Related Design Patterns
6.1 Model-driven architecture
Model-driven engineering and Model-driven architecture facilitate domain-driven design by generating source code, documentation, tests, etc. from the domain model.
6.2 Command Query Responsibility Segregation
Command Query Responsibility Segregation (CQRS) coined by Bertrand Meyer generalizes message-driven and event-driven architecture by segregating behavior for querying the data and updating the data.
6.3 Event sourcing
Event sourcing tracks internal by reading and committing events to an event store.
7. Putting it all together
Following sections describe how a library management system can be built with the domain driven and hexagonal/clean architecture:
7.1 User Stories
Following is a list of primary user-stories that will be implemented for the library management system:
- As a library administrator, I want to add a book to the collection so that patrons of the library may checkout it.
- As a library administrator, I want to remove a book from the collection so that it’s no longer available to borrow.
- As a library administrator or a patron, I want to search books based on different criteria such as title, author, publisher, dates, etc. so that I may see details or use it to checkout the book later.
- As a patron, I want to checkout a book so that I can read it and return later.
- As a patron, I want to return a checked out book when I am done with reading.
- As a patron, I want to hold a book, which is not currently available so that I can checkout later.
- As a patron, I want to cancel the hold that previously made when I am no longer interested in the book.
- As a patron, I want to checkout the book hold that previously made so that I can read it.
7.1.1 Constraints and Validation Policies
In addition, the library may impose certain policies and restrictions on the books and checkout/hold actions such as restricted book can be held by a researcher patron or limit the number of books that can be held or checkout at a time.
7.2 Layered Architecture
The library management application divides the application into multiple domains such as patrons, catalog, checkout and hold. Each domain then divides into following layers:
7.2.1 Application-Service and Controller Layer
This layer defines remote APIs for communicating with the microservices defined in the library management application.
7.2.2 Command and Query Layer (CQRS)
This layer defines operations for commands and queries that are invoked by the controller layer, which depend on underlying domain service layer. The command layer also defines the scope of a transaction so that all changes are persisted atomically.
Note: This layer may use SAGA pattern to handle distributed transactions when you need to invoke multiple services or databases for performing an operation.
7.2.3 Domain Service Layer
This layer defines additional business behavior that is built upon the domain model layer and is used by the commands and queries layer
7.2.4 Domain Model Layer
This layer defines data and behavior of the domain and defines entity, value, aggregates, factories, and interface to model the domain.
7.2.5 Infrastructure Layer
This layer defines repositories and gateways to persist domain entities and connect to external services such as messaging and logging.
7.3 Domain Model
Following domain model was defined as a result of above use-stories and an event-storming exercise:
7.3.1 Party Pattern
Above design uses party-pattern to model patrons, library administrator and library branches because they share a lot of common attributes to describe people and organizations. The base Party class uses Address class to store physical address, so the Party class acts as an Aggregate for all related data about people and organizations.
7.3.2 Book
The book class models a library book that can be added to the library collection, queried by the administrators or patrons and then checked out or held by the patrons.
7.3.3 Checkout
The Checkout class abstracts the data when checking out a book, which can be returned later.
7.3.4 Hold
The Hold class abstracts the data when holding a book that is not currently available so that it can be checked out later.
Note: The domain driven design considers anemic domain without business behavior an antipattern so above domain model defines invariant business rules and behavior along with the data attributes.
7.4 Components and Modules
The library management application was divided into following modules:
The core, utils and gateway module is shared by other modules; the parties and books module define low-level modules and catalog, patrons, checkout and hold modules define high-level modules, which also act as bounded context for managing books-catalog, patrons for managing library members and checkout/hold modules for defining behavior for the library operations.
7.4.1 core module
The core module abstracts common domain model, domain events and interfaces for command pattern, repository and controllers.
7.4.2 parties module
The parties module defines domain model for the party class and data access methods for persisting and querying parties (people and organizations).
7.4.3 books module
The books module defines domain model and data transfer model for books as well as repository for persisting and querying books using AWS DynamoDB.
7.4.4 patrons module
The patron module built upon the parties module and defines service sub-module for business logic to query and persisting patrons. The patron module also includes controller, command classes and binary/main module to define microservices based on AWS Lambda.
7.4.5 checkout module
The checkout module implements services for checking out and returning book, which are then made available as microservices using controller, command and binary sub-modules.
7.4.6 hold module
The hold module implements services for holding a book or canceling/returning it later, which are then made available as microservices using controller, command and binary sub-modules.
7.4.7 gateway module
The gateway module defines interfaces to connect to external services such as AWS CloudWatch for managing metrics and AWS SNS for publishing events from the domain and user-action changes.
7.5 Domain-Driven Design Patterns
The library management systems applies following design patterns from the domain driven design and hexagonal/clean architecture:
7.5.1 Ubiquitous Language
The domain model uses the same terminology used by the stakeholders and experts from underlying problem space such as library patrons, books, checkout, hold, etc. so that software development team can model the business problem as close as possible.
7.5.2 Domain Events
The domain events capture data change in the domain model specifically aggregate objects. This decouples domains in different bounded context as other domains can listen to the domain events asynchronously and make a local change. Following is an example of domain events in the library management systems:
#[derive(Debug, PartialEq, Serialize, Deserialize)]
pub(crate) struct DomainEvent {
pub event_id: String,
pub name: String,
pub group: String,
pub key: String,
pub kind: DomainEventType,
pub metadata: HashMap<String, String>,
pub json_data: String,
#[serde(with = "serializer")]
pub created_at: NaiveDateTime,
}7.5.3 Aggregates and Event Stream
The modules and domain model communicate with each other using event streams, which is built upon AWS SNS service underneath, e.g.,
impl EventPublisher for SESPublisher {
async fn publish(&self, event: &DomainEvent) -> Result<(), LibraryError> {
let topic = self.topics.get(event.name.as_str());
if let Some(arn) = topic {
let json = serde_json::to_string(event)?;
self.client.publish().topic_arn(arn).message(json).send().await?;
Ok(())
} else {
Err(LibraryError::runtime(format!("topic is not found {}", event.name).as_str(), None))
}
}
}Following example depicts publishing an event as a result of checking out a book:
async fn checkout(&self, patron_id: &str, book_id: &str) -> LibraryResult<CheckoutDto> {
let patron = self.patron_service.find_patron_by_id(patron_id).await?;
let book = self.catalog_service.find_book_by_id(book_id).await?;
if book.status() != BookStatus::Available {
return Err(LibraryError::validation(format!("book is not available {}",
book.id()).as_str(), Some("400".to_string())));
}
if book.is_restricted() && patron.is_regular() {
return Err(LibraryError::validation(format!("patron {} cannot hold restricted books {}",
patron.id(), book.id()).as_str(), Some("400".to_string())));
}
let checkout = CheckoutDto::from_patron_book(self.branch_id.as_str(), &patron, &book);
self.checkout_repository.create(&CheckoutEntity::from(&checkout)).await?;
let _ = self.events_publisher.publish(&DomainEvent::added(
"book_checkout", "checkout", checkout.checkout_id.as_str(), &HashMap::new(), &checkout.clone())?).await?;
Ok(checkout)
}The events_publisher publishes the domain events upon checking out a book. Similar events are published for other user-actions or domain changes.
7.5.4 Domain Services
The domain services define high-level business logic and each bounded context defines a layer for domain services such as:
pub(crate) trait CatalogService: Sync + Send {
async fn add_book(&self, book: &BookDto) -> LibraryResult<BookDto>;
async fn remove_book(&self, id: &str) -> LibraryResult<()>;
async fn update_book(&self, book: &BookDto) -> LibraryResult<BookDto>;
async fn find_book_by_id(&self, id: &str) -> LibraryResult<BookDto>;
async fn find_book_by_isbn(&self, isbn: &str) -> LibraryResult<Vec<BookDto>>;
}pub(crate) trait CheckoutService: Sync + Send {
async fn checkout(&self, patron_id: &str, book_id: &str) -> LibraryResult<CheckoutDto>;
async fn returned(&self, patron_id: &str, book_id: &str) -> LibraryResult<CheckoutDto>;
async fn query_overdue(&self, predicate: &HashMap<String, String>,
page: Option<&str>, page_size: usize) -> LibraryResult<PaginatedResult<CheckoutDto>>;
}pub(crate) trait HoldService: Sync + Send {
async fn hold(&self, patron_id: &str, book_id: &str) -> LibraryResult<HoldDto>;
async fn cancel(&self, patron_id: &str, book_id: &str) -> LibraryResult<HoldDto>;
async fn checkout(&self, patron_id: &str, book_id: &str) -> LibraryResult<HoldDto>;
async fn query_expired(&self, predicate: &HashMap<String, String>,
page: Option<&str>, page_size: usize) -> LibraryResult<PaginatedResult<HoldDto>>;
}7.5.5 Repositories
The library management application uses repository pattern to persist or query data, which can be implemented based on any supported implementation (such as DynamoDB). Also, it uses polymorphic associations for managing inheritance, e.g. parties DynamoDB table can store patrons, administrators and library branches. The repository implementation can be pointed to a local DynamoDB or AWS managed DynamoDB service, e.g.,
#[async_trait]
impl Repository<BookEntity> for DDBBookRepository {
async fn create(&self, entity: &BookEntity) -> LibraryResult<usize> {
let table_name: &str = self.table_name.as_ref();
let val = serde_json::to_value(entity)?;
self.client
.put_item()
.table_name(table_name)
.condition_expression("attribute_not_exists(book_id)")
.set_item(Some(parse_item(val)?))
.send()
.await.map(|_| 1).map_err(LibraryError::from)
}
async fn update(&self, entity: &BookEntity) -> LibraryResult<usize> {
let now = Utc::now().naive_utc();
let table_name: &str = self.table_name.as_ref();
self.client
.update_item()
.table_name(table_name)
.key("book_id", AttributeValue::S(entity.book_id.clone()))
.update_expression("SET version = :version, title = :title, book_status = :book_status, dewey_decimal_id = :dewey_decimal_id, restricted = :restricted, updated_at = :updated_at")
.expression_attribute_values(":old_version", AttributeValue::N(entity.version.to_string()))
.expression_attribute_values(":version", AttributeValue::N((entity.version + 1).to_string()))
.expression_attribute_values(":title", AttributeValue::S(entity.title.to_string()))
.expression_attribute_values(":book_status", AttributeValue::S(entity.book_status.to_string()))
.expression_attribute_values(":restricted", AttributeValue::Bool(entity.restricted))
.expression_attribute_values(":dewey_decimal_id", AttributeValue::S(entity.dewey_decimal_id.to_string()))
.expression_attribute_values(":updated_at", string_date(now))
.condition_expression("attribute_exists(version) AND version = :old_version")
.send()
.await.map(|_| 1).map_err(LibraryError::from)
}
...
}7.5.6 Factories
The library management application uses factories to create instance of repositories, event publishers and services based on different implementations, e.g.,
pub(crate) async fn create_checkout_repository(store: RepositoryStore) -> Box<dyn CheckoutRepository> {
match store {
RepositoryStore::DynamoDB => {
let client = build_db_client(store).await;
Box::new(DDBCheckoutRepository::new(client, "checkout", "checkout_ndx"))
}
RepositoryStore::LocalDynamoDB => {
let client = build_db_client(store).await;
let _ = create_table(&client, "checkout", "checkout_id", "checkout_status", "patron_id").await;
Box::new(DDBCheckoutRepository::new(client, "checkout", "checkout_ndx"))
}
}
}
pub(crate) async fn create_checkout_service(
config: &Configuration, store: RepositoryStore) -> Box<dyn CheckoutService> {
let checkout_repo = factory::create_checkout_repository(store).await;
let catalog_svc = create_catalog_service(config, store).await;
let patron_svc = create_patron_service(config, store).await;
let publisher = create_publisher(store.gateway_publisher()).await;
Box::new(CheckoutServiceImpl::new(config, checkout_repo,
patron_svc, catalog_svc, publisher))
}7.5.7 Data Transfer Objects
The library management application uses immutable data transfer objects when invoking a business service, a command or a method on controller so that these objects are free of side effects and can be safely shared with other modules in concurrent environment.
7.5.8 CQRS Pattern
The library management application uses command-query separation principle to bridge application services with the domain services. Each command handles a unique behavior implemented by the high-level modules for managing patrons, book-catalog, and checkout/hold behavior, e.g.,
#[derive(Debug, Deserialize)]
pub(crate) struct CheckoutBookCommandRequest {
patron_id: String,
book_id: String,
}
#[derive(Debug, Serialize)]
pub(crate) struct CheckoutBookCommandResponse {
checkout: CheckoutDto,
}
#[async_trait]
impl Command<CheckoutBookCommandRequest, CheckoutBookCommandResponse> for CheckoutBookCommand {
async fn execute(&self, req: CheckoutBookCommandRequest) -> Result<CheckoutBookCommandResponse, CommandError> {
self.checkout_service.checkout(req.patron_id.as_str(), req.book_id.as_str())
.await.map_err(CommandError::from).map(CheckoutBookCommandResponse::new)
}
}7.5.9 Application Services/Controller
The application services/controller layer defines remote APIs, which are built on top of AWS Lambda APIs, e.g.,
pub(crate) async fn checkout_book(
State(state): State<AppState>,
json: Json<Value>) -> Result<Json<CheckoutBookCommandResponse>, ServerError> {
let req: CheckoutBookCommandRequest = serde_json::from_value(json.0).map_err(json_to_server_error)?;
let svc = build_service(state).await;
let res = CheckoutBookCommand::new(svc).execute(req).await?;
Ok(Json(res))
}7.5.10 Bounded Context
As, the Bounded Context defines the boundaries of the domain model, the library system is defines bounded context for managing library members (patrons), managing books (catalog), checkout and hold operations. In addition each domain also decomposes other subdomains that reflect business process within the problem space.
7.5.11 Monads and Error Handling
The library management application uses Result monad for returning results from a service, command or controller so that caller can handle errors properly. In addition, it uses Option monad is used for defining any optional data properties so that the compiler can enforce all type checking.
7.5.12 Main
The high-level modules define a main module, which instantiates the API controllers for remote invocation. The AWS Lambda requires that Rust based Lambda functions are deployed with the binary executable, which is spawned by the Lambda runtime, e.g.,
#[tokio::main]
async fn main() -> Result<(), Error> {
setup_tracing();
let state = if DEV_MODE {
std::env::set_var("AWS_LAMBDA_FUNCTION_NAME", "_");
std::env::set_var("AWS_LAMBDA_FUNCTION_MEMORY_SIZE", "4096"); // 200MB
std::env::set_var("AWS_LAMBDA_FUNCTION_VERSION", "1");
std::env::set_var("AWS_LAMBDA_RUNTIME_API", "http://[::]:9000/.rt");
AppState::new("dev", RepositoryStore::LocalDynamoDB)
} else {
AppState::new("prod", RepositoryStore::DynamoDB)
};
let app = Router::new()
.route("/catalog", post(controller::add_book))
.route("/catalog/:id",
get(controller::find_book_by_id).delete(controller::remove_book))
.with_state(state);
run(app).await
}7.6 Code structure
Following tree structure shows the module and code structure for the library management application:
|--- books | |--- domain | | |--- model.rs | |--- domain.rs | |--- dto.rs | |--- factory.rs | |--- repository | | |--- ddb_book_repository.rs | |--- repository.rs |--- books.rs |--- catalog | |--- bin | | |--- main.rs | |--- command | | |--- add_book_cmd.rs | | |--- get_book_cmd.rs | | |--- remove_book_cmd.rs | | |--- update_book_cmd.rs | |--- command.rs | |--- controller.rs | |--- domain | | |--- service.rs | |--- domain.rs | |--- dto.rs | |--- factory.rs |--- catalog.rs |--- checkout | |--- bin | | |--- main.rs | |--- command | | |--- checkout_book_cmd.rs | | |--- return_book_cmd.rs | |--- command.rs | |--- controller.rs | |--- domain | | |--- model.rs | | |--- service.rs | |--- domain.rs | |--- dto.rs | |--- factory.rs | |--- repository | | |--- ddb_checkout_repository.rs | |--- repository.rs |--- checkout.rs |--- core | |--- command.rs | |--- controller.rs | |--- domain.rs | |--- events.rs | |--- library.rs | |--- repository.rs |--- core.rs |--- gateway | |--- ddb | | |--- publisher.rs | |--- ddb.rs | |--- events.rs | |--- factory.rs | |--- logs.rs | |--- sns | | |--- publisher.rs | |--- sns.rs |--- gateway.rs |--- hold | |--- bin | | |--- main.rs | |--- command | | |--- cancel_hold_book_cmd.rs | | |--- checkout_hold_book_cmd.rs | | |--- hold_book_cmd.rs | |--- command.rs | |--- controller.rs | |--- domain | | |--- model.rs | | |--- service.rs | |--- domain.rs | |--- dto.rs | |--- events.rs | |--- factory.rs | |--- repository | | |--- ddb_hold_repository.rs | |--- repository.rs |--- hold.rs |--- lib.rs |--- library.rs |--- main.rs |--- parties | |--- domain | | |--- model.rs | |--- domain.rs | |--- events.rs | |--- factory.rs | |--- repository | | |--- ddb_party_repository.rs | |--- repository.rs |--- parties.rs |--- patrons | |--- bin | | |--- main.rs | |--- command | | |--- add_patron_cmd.rs | | |--- get_patron_cmd.rs | | |--- remove_patron_cmd.rs | | |--- update_patron_cmd.rs | |--- command.rs | |--- controller.rs | |--- domain | | |--- service.rs | |--- domain.rs | |--- dto.rs | |--- factory.rs |--- patrons.rs |--- utils | |--- date.rs | |--- ddb.rs |--- utils.rs
7.7 Building and Testing
7.7.1 Start locally
docker-compose -f ddb-docker-compose.yaml up
7.7.2 Start Lambda locally
cargo lambda watch
7.7.3 Build
cargo build --release cargo lambda build --release
7.7.4 Testing catalog Lambdas
Add a book:
curl -H "Content-Type: application/json" http://localhost:9000/catalog -d '{"isbn": "123", "title": "my book"}'which would return something like:
{
"book": {
"dewey_decimal_id": "749",
"book_id": "a2b25506-2948-47bb-9c4a-cf9ad480c10b",
"version": 0,
"author_id": "623a01ca-8ba9-41cd-b8b6-85a5711f8453",
"publisher_id": "f0cff296-9f6e-4b25-95e1-a783661bf91f",
"language": "en",
"isbn": "123",
"title": "my book",
"book_status": "Available",
"restricted": false,
"published_at": "2023-05-09T20:55:56.073008+00:00",
"created_at": "2023-05-09T20:55:56.073027+00:00",
"updated_at": "2023-05-09T20:55:56.073027+00:00"
}
}Finding the book by id:
curl -H "Content-Type: application/json" http://localhost:9000/catalog/f58ef32a-6f24-4314-8782-c7ebcad0ab59
that returns
{
"book": {
"dewey_decimal_id": "220",
"book_id": "f58ef32a-6f24-4314-8782-c7ebcad0ab59",
"version": 0,
"author_id": "4c24b180-a146-410a-b68c-9d83c57adebc",
"publisher_id": "88b47029-cad1-443f-8d67-aaf13863e924",
"language": "en",
"isbn": "123",
"title": "my book",
"book_status": "Available",
"restricted": false,
"published_at": "2023-05-09T22:18:25.436359+00:00",
"created_at": "2023-05-09T22:18:25.436366+00:00",
"updated_at": "2023-05-09T22:18:25.436371+00:00"
}
}7.7.5 Testing patrons Lambdas
Add a patron:
curl -v -H "Content-Type: application/json" http://localhost:9000/patrons -d '{"email": "test-email@xyz.com"}'that returns:
{
"patron": {
"patron_id": "cf49007e-e7fa-42c3-ac56-e15b9530597e",
"version": 0,
"first_name": "",
"last_name": "",
"email": "test-email@xyz.com",
"under_13": false,
"group_roles": [],
"num_holds": 0,
"num_overdue": 0,
"home_phone": null,
"cell_phone": null,
"work_phone": null,
"street_address": null,
"city": null,
"zip_code": null,
"state": null,
"country": null,
"created_at": "2023-05-09T22:20:28.898831",
"updated_at": "2023-05-09T22:20:28.898833"
}
}Getting patron:
curl -H "Content-Type: application/json" http://localhost:9000/patrons/cf49007e-e7fa-42c3-ac56-e15b9530597e|jq '.'
that returns:
{
"patron": {
"patron_id": "cf49007e-e7fa-42c3-ac56-e15b9530597e",
"version": 0,
"first_name": "",
"last_name": "",
"email": "test-email@xyz.com",
"under_13": false,
"group_roles": [],
"num_holds": 0,
"num_overdue": 0,
"home_phone": "",
"cell_phone": "",
"work_phone": "",
"street_address": null,
"city": null,
"zip_code": null,
"state": null,
"country": null,
"created_at": "2023-05-09T22:21:35.142750",
"updated_at": "2023-05-09T22:21:35.142757"
}
}7.7.6 Checkout book Lambda
Checkout a book:
curl -v -H "Content-Type: application/json" http://localhost:9000/checkout -d '{"patron_id": "cf49007e-e7fa-42c3-ac56-e15b9530597e", "book_id": "f58ef32a-6f24-4314-8782-c7ebcad0ab59"}'that returns:
{
"checkout": {
"checkout_id": "4a7ea5c5-939d-4934-8715-071c7ab5bc71",
"version": 0,
"branch_id": "dev",
"book_id": "f58ef32a-6f24-4314-8782-c7ebcad0ab59",
"patron_id": "cf49007e-e7fa-42c3-ac56-e15b9530597e",
"checkout_status": "CheckedOut",
"checkout_at": "2023-05-09T22:36:55.162807+00:00",
"due_at": "2023-05-24T22:36:55.162808+00:00",
"returned_at": null,
"created_at": "2023-05-09T22:36:55.162812+00:00",
"updated_at": "2023-05-09T22:36:55.162812+00:00"
}
}Returning a book:
curl -v -H "Content-Type: application/json" http://localhost:9000/checkout/return -d '{"patron_id": "cf49007e-e7fa-42c3-ac56-e15b9530597e", "book_id": "f58ef32a-6f24-4314-8782-c7ebcad0ab59"}'that returns:
{
"checkout": {
"checkout_id": "6b432212-8136-45a5-a8c4-953da73ee24f",
"version": 0,
"branch_id": "dev",
"book_id": "f58ef32a-6f24-4314-8782-c7ebcad0ab59",
"patron_id": "cf49007e-e7fa-42c3-ac56-e15b9530597e",
"checkout_status": "Returned",
"checkout_at": "1970-01-01T00:00:00+00:00",
"due_at": "2023-05-09T22:36:59.145408+00:00",
"returned_at": "2023-05-09T22:36:59.145607",
"created_at": "2023-05-09T22:36:59.145415+00:00",
"updated_at": "2023-05-09T22:36:59.145421+00:00"
}
}7.7.7 Hold book Lambda
Hold a book:
curl -v -H "Content-Type: application/json" http://localhost:9000/hold -d '{"patron_id": "cf49007e-e7fa-42c3-ac56-e15b9530597e", "book_id": "f58ef32a-6f24-4314-8782-c7ebcad0ab59"}'that returns
{
"hold": {
"hold_id": "b6cbff12-fe0b-4be0-9566-5e221e52c8c5",
"version": 0,
"branch_id": "dev",
"book_id": "f58ef32a-6f24-4314-8782-c7ebcad0ab59",
"patron_id": "cf49007e-e7fa-42c3-ac56-e15b9530597e",
"hold_status": "OnHold",
"hold_at": "2023-05-09T22:38:52.905822+00:00",
"expires_at": "2023-05-24T22:38:52.905822+00:00",
"canceled_at": null,
"checked_out_at": null,
"created_at": "2023-05-09T22:38:52.905825+00:00",
"updated_at": "2023-05-09T22:38:52.905825+00:00"
}
}Canceling a hold:
curl -v -H "Content-Type: application/json" http://localhost:9000/hold/cancel -d '{"patron_id": "cf49007e-e7fa-42c3-ac56-e15b9530597e", "book_id": "f58ef32a-6f24-4314-8782-c7ebcad0ab59"}'that returns:
{
"hold": {
"hold_id": "b6cbff12-fe0b-4be0-9566-5e221e52c8c5",
"version": 0,
"branch_id": "dev",
"book_id": "f58ef32a-6f24-4314-8782-c7ebcad0ab59",
"patron_id": "cf49007e-e7fa-42c3-ac56-e15b9530597e",
"hold_status": "Canceled",
"hold_at": "2023-05-09T22:39:51.920045+00:00",
"expires_at": "2023-05-09T22:39:51.920052+00:00",
"canceled_at": "2023-05-09T22:39:51.920078",
"checked_out_at": null,
"created_at": "2023-05-09T22:39:51.920058+00:00",
"updated_at": "2023-05-09T22:39:51.920063+00:00"
}
}Checking out a hold book:
curl -v -H "Content-Type: application/json" http://localhost:9000/hold/checkout -d '{"patron_id": "cf49007e-e7fa-42c3-ac56-e15b9530597e", "book_id": "f58ef32a-6f24-4314-8782-c7ebcad0ab59"}'that returns:
{
"hold": {
"hold_id": "f5fdb835-5ea2-428d-af12-a81ffb1b3f35",
"version": 0,
"branch_id": "dev",
"book_id": "f58ef32a-6f24-4314-8782-c7ebcad0ab59",
"patron_id": "cf49007e-e7fa-42c3-ac56-e15b9530597e",
"hold_status": "CheckedOut",
"hold_at": "2023-05-09T22:40:54.705417+00:00",
"expires_at": "2023-05-09T22:40:54.705424+00:00",
"canceled_at": null,
"checked_out_at": "2023-05-09T22:40:54.705443",
"created_at": "2023-05-09T22:40:54.705430+00:00",
"updated_at": "2023-05-09T22:40:54.705435+00:00"
}
}8. Deployment and Infrastructure as a Code
In order to fully automate deployment, the library management system uses AWS CDK to build Dynamo DB tables, CloudWatch and AWS Lambda functions along with other security policies. You can deploy the infrastructure as follows:
8.1 Install CDK
npm install -g typescript npm install aws-cdk-lib npm install -g aws-cdk
8.2 Deploy
cd cdk cdk deploy
8.3 Destroy
If you need to remove all infrastructure, simply run:
cd cdk cdk destroy
9. Summary
A sample library management system demonstrates how to apply domain driven design and hexagonal/clean architecture to build microservices. It is implemented in Rust and uses AWS Dynamo DB, AWS SNS, AWS CloudWatch and AWS Lambda to build modern microservices. The sample domain-driven application also uses AWS CDK to manage infrastructure as a code so that you can deploy services consistently across all environments. You can download the sample application from https://github.com/bhatti/ddd-sample-microservice.
PS: The library management system is a sample application to showcase the domain-driven and hexagonal/clean architecture but you can read Building a Secured Family-friendly Password Manager and Building a Hybrid Authorization System for Granular Access Control for learning these concepts on a bit larger open source applications available at https://github.com/bhatti/PlexPass and https://github.com/bhatti/PlexAuthZ.