> For the complete documentation index, see [llms.txt](https://alfredo-rueda-unsain.gitbook.io/alfredo-rueda-unsain-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://alfredo-rueda-unsain.gitbook.io/alfredo-rueda-unsain-docs/book-home.md). # 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](/alfredo-rueda-unsain-docs/reference-use-case/sell-stock-tutorial.md) * [HexaStock — Project Overview](/alfredo-rueda-unsain-docs/reference-use-case/hexastock-project-overview.md) — 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](/alfredo-rueda-unsain-docs/architecture-and-design/rich_vs_anemic_domain_model_tutorial.md) — Side-by-side architectural comparison using the sell flow, with failure mode demonstration. * [Dependency Inversion in Stock Selling](/alfredo-rueda-unsain-docs/architecture-and-design/dependency-inversion-stock-selling.md) — Full execution flow through ports and adapters, with testability and extensibility analysis. * [Concurrency Control: Pessimistic Locking and Optimistic Concurrency](/alfredo-rueda-unsain-docs/supporting-chapters/concurrency-pessimistic-locking.md) — Pessimistic locking (JPA/MySQL) and optimistic concurrency with retries (MongoDB), isolation levels, and race-condition tests. * [DDD Portfolio and Transactions](/alfredo-rueda-unsain-docs/architecture-and-design/ddd-portfolio-and-transactions.md) — Why Portfolio and Transaction are separate aggregates: consistency boundaries, invariants, and a decision matrix. * [Remove Lots with Zero Remaining Quantity](/alfredo-rueda-unsain-docs/architecture-and-design/remove-lots-with-zero-remaining-quantity-from-portfolio-aggregate.md) — Design decision on retaining or pruning fully consumed lots, with DDD-grounded analysis. * [Holdings Performance at Scale](/alfredo-rueda-unsain-docs/supporting-chapters/holdings-performance-at-scale.md) — Four reporting strategies from in-memory aggregation to CQRS read models. * [Watchlists & Market Sentinel](/alfredo-rueda-unsain-docs/supporting-chapters/watchlists-market-sentinel.md) — Automated market monitoring with CQRS and progressive domain model evolution. * [Lot Selection Strategies — DDD Hexagonal Exercise](/alfredo-rueda-unsain-docs/supporting-chapters/ddd-hexagonal-exercise.md) — 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](/alfredo-rueda-unsain-docs/technical-review/ddd-review-personal-investment-portfolio.md) — A structured assessment of the domain model, aggregate design, and hexagonal layer separation. *** ## API and Specifications * [Stock Portfolio API Specification](/alfredo-rueda-unsain-docs/specifications/stock-portfolio-api-specification.md) — 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. *** ## Reading Contract: Pedagogical Simplifications vs Production Refinements HexaStock is intentionally designed to serve two audiences at once: it is a working, tested codebase, and it is a teaching artefact for engineers learning Domain-Driven Design and Hexagonal Architecture. To keep that dual purpose honest, this book classifies design choices in three explicit categories. Readers should keep this classification in mind whenever a chapter discusses a "simplification" or a "future refinement". | Category | Examples in HexaStock | What it means in the book | | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | **Intentional pedagogical simplifications** — chosen to make the model legible; perfectly defensible at this scale | Loading the entire `Portfolio` aggregate on sell; recording transactions through application-service orchestration rather than domain events; single currency (USD); integer share quantities; no fees, taxes or margin | The current code is the right answer **for teaching**. A production team operating at very different scale would refine these. | | **Deliberate architectural choices** — production-quality decisions that are not simplifications | Two interchangeable persistence adapters (JPA pessimistic vs MongoDB optimistic + retry); separating `Portfolio` (state) from `Transaction` (history) into two aggregates; value objects (`Money`, `Price`, `Ticker`) instead of primitives; ArchUnit fitness tests | The current code is the right answer **in general**. These should be preserved or carried over to any production derivative. | | **Acknowledged future enhancements** — explicitly out of scope today, but discussed as roadmap | Domain events for transaction creation; CQRS read models for reporting at scale; promoting `Holding` to its own aggregate when sell invariants justify it; Flyway/Liquibase migrations replacing `ddl-auto` | Treated as legitimate next steps; the book explains the reasoning rather than implementing them today. | When the book uses the term **"production-grade"** without further qualification, it refers to *production-quality code* (typed, tested, layered, with enforced architectural boundaries) rather than to a *fully production-ready deployed system* (which would additionally require schema migrations, observability, capacity planning and operational tooling that are out of scope for this study). *** ## 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](/alfredo-rueda-unsain-docs/legal/license.md) page. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## 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, and the optional `goal` query parameter: ``` GET https://alfredo-rueda-unsain.gitbook.io/alfredo-rueda-unsain-docs/book-home.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.