# BOOK-HOME *A technical book on Domain-Driven Design, Hexagonal Architecture, and Specification-Driven Development in a financial domain.* *** This documentation is organised as a book-style technical journey through a working financial portfolio system. HexaStock serves as a concrete architectural case study — built with Java 21, Spring Boot 3, and Maven — where every design decision is grounded in real code, executable specifications, and automated tests. The central narrative follows a single use case, **selling stocks**, through every architectural layer: from Gherkin specification to REST controller, through application service orchestration, into the aggregate root's FIFO lot-consumption algorithm, and back as a structured financial result. The goal is to show how Domain-Driven Design and Hexagonal Architecture function not as abstract principles but as engineering disciplines applied under realistic constraints. Every chapter in this book is directly backed by a robust, working open-source project. The full source code is publicly available at [github.com/alfredorueda/HexaStock](https://github.com/alfredorueda/HexaStock). Readers are encouraged to clone the repository and explore the codebase alongside the text — the repository [README](https://github.com/alfredorueda/HexaStock#readme) provides the practical information needed to build and run the system locally. *** ## Start Here The primary entry point to this book is the sell-stock architectural study. It traces the full engineering workflow — specification, domain modelling, hexagonal structure, persistence, error handling, integration testing — applied to one use case from end to end. * [Sell Stock Deep Dive — Reference Use Case](https://alfredo-rueda-unsain.gitbook.io/alfredo-rueda-unsain-docs/reference-use-case/sell-stock-tutorial) * [HexaStock — Project Overview](https://alfredo-rueda-unsain.gitbook.io/alfredo-rueda-unsain-docs/reference-use-case/hexastock-project-overview) — System overview, architectural identity, Maven module structure, and domain package organisation. *** ## Supporting Chapters These chapters deepen specific themes introduced in the main study. * [Rich vs Anemic Domain Model](https://alfredo-rueda-unsain.gitbook.io/alfredo-rueda-unsain-docs/architecture-and-design/rich_vs_anemic_domain_model_tutorial) — Side-by-side architectural comparison using the sell flow, with failure mode demonstration. * [Dependency Inversion in Stock Selling](https://alfredo-rueda-unsain.gitbook.io/alfredo-rueda-unsain-docs/architecture-and-design/dependency-inversion-stock-selling) — Full execution flow through ports and adapters, with testability and extensibility analysis. * [Concurrency Control with Pessimistic and Optimistic Locking](https://alfredo-rueda-unsain.gitbook.io/alfredo-rueda-unsain-docs/supporting-chapters/concurrency-pessimistic-locking) — Locking strategies, isolation levels, race condition tests, and Java 21 virtual thread considerations. * [DDD Portfolio and Transactions](https://alfredo-rueda-unsain.gitbook.io/alfredo-rueda-unsain-docs/architecture-and-design/ddd-portfolio-and-transactions) — Why Portfolio and Transaction are separate aggregates: consistency boundaries, invariants, and a decision matrix. * [Remove Lots with Zero Remaining Quantity](https://alfredo-rueda-unsain.gitbook.io/alfredo-rueda-unsain-docs/architecture-and-design/remove-lots-with-zero-remaining-quantity-from-portfolio-aggregate) — Design decision on retaining or pruning fully consumed lots, with DDD-grounded analysis. * [Holdings Performance at Scale](https://alfredo-rueda-unsain.gitbook.io/alfredo-rueda-unsain-docs/supporting-chapters/holdings-performance-at-scale) — Four reporting strategies from in-memory aggregation to CQRS read models. * [Watchlists & Market Sentinel](https://alfredo-rueda-unsain.gitbook.io/alfredo-rueda-unsain-docs/supporting-chapters/watchlists-market-sentinel) — Automated market monitoring with CQRS and progressive domain model evolution. * [Lot Selection Strategies — DDD Hexagonal Exercise](https://alfredo-rueda-unsain.gitbook.io/alfredo-rueda-unsain-docs/supporting-chapters/ddd-hexagonal-exercise) — Extending beyond FIFO with Strategy pattern and hexagonal structure. *** ## Featured: Specification-Driven Development with AI > How structurally precise specifications — Gherkin, UML, OpenAPI, ADRs — enable high-quality AI-assisted implementation. This chapter analyses a real consulting case where the HexaStock codebase was built using specification-driven AI-assisted development, and examines the conditions under which this approach meets production engineering standards. * [Specification-Driven Development with AI](https://alfredo-rueda-unsain.gitbook.io/alfredo-rueda-unsain-docs/supporting-chapters/specification-driven-development-with-ai) *** ## Technical Review * [AI-Assisted Architectural Review — DDD and Hexagonal Architecture](https://alfredo-rueda-unsain.gitbook.io/alfredo-rueda-unsain-docs/technical-review/ddd-review-personal-investment-portfolio) — A structured assessment of the domain model, aggregate design, and hexagonal layer separation. *** ## API and Specifications * [Stock Portfolio API Specification](https://alfredo-rueda-unsain.gitbook.io/alfredo-rueda-unsain-docs/specifications/stock-portfolio-api-specification) — Complete REST API for all 10 use cases, RFC 7807 error contract, domain model, and exception mapping. * [Gherkin Feature Files](https://github.com/alfredorueda/HexaStock/blob/main/doc/features/sell-stocks.feature) — Fifteen executable behavioural specifications covering the full system. *** ## License This project uses a dual-license model. * **Source code** is licensed under [Apache License 2.0](https://github.com/alfredorueda/HexaStock/blob/main/LICENSE/README.md). * **Book and editorial written content** are licensed under [CC BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0/). [![License: CC BY-NC 4.0](https://licensebuttons.net/l/by-nc/4.0/88x31.png)](https://creativecommons.org/licenses/by-nc/4.0/) This book and its editorial written content are licensed under the Creative Commons Attribution-NonCommercial 4.0 International License (CC BY-NC 4.0). You are welcome to read, share, and adapt this material for non-commercial purposes, provided that appropriate credit is given. For commercial use, including commercial training, paid courses, corporate programs, commercial publishing, or reuse within paid products or services, prior permission is required. This dual-license approach is intentional: the software remains open source under Apache 2.0, while the book is shared openly for learning and non-commercial educational use under Creative Commons. The full licensing details are available on the [Licensing](https://alfredo-rueda-unsain.gitbook.io/alfredo-rueda-unsain-docs/legal/license) page. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://alfredo-rueda-unsain.gitbook.io/alfredo-rueda-unsain-docs/book-home.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.