alfredorueda/HexaStock

HexaStock is a portfolio management and stock trading application built on Hexagonal Architecture, supporting the creation of portfolios, cash management, and stock buying and selling with FIFO accounting. It exposes these capabilities via a REST API and persists data using either JPA (MySQL) or MongoDB, with configurable external adapters for real-time stock prices from providers like Alpha Vantage and Finnhub. The system enforces strict domain invariants, handles concurrency through optimistic locking with automatic retries, and includes comprehensive documentation and testing infrastructure to validate its behavior.

16 changes.

The project established its foundational structure and documentation while refactoring the codebase into a multi-module Maven architecture. This period involved removing legacy JPA, REST, and mock implementations to align with Hexagonal Architecture principles, alongside the removal of obsolete domain models and application services.

23 changes.

The project implemented a hexagonal architecture for the HexaStock application, establishing core domain models with FIFO accounting and separating concerns through specialized application services and ports. This structural work was supported by the creation of JPA and MongoDB persistence adapters, a REST API interface, and comprehensive test coverage including integration and contract tests. Concurrently, extensive documentation was produced, featuring tutorials, architectural diagrams, and materials for academic defense presentations.

The application now supports fetching real-time stock prices via two external providers, Alpha Vantage and Finnhub, selected through Spring profiles (alphaVantage, finhub). These adapters implement the StockPriceProviderPort, use Spring's RestClient for HTTP calls, include rate-limit throttling, and cache results in a 'stockPrices' cache. A MockFinhubStockPriceAdapter is also available via the mockfinhub profile to return random prices for testing. All adapters are located in the adapters-outbound-market module and include corresponding integration tests using WireMock.

adapters-outbound-market · high confidence

This location now contains canonical Gherkin feature files that define the expected business behavior for key use cases, including creating and listing portfolios, depositing and withdrawing funds, buying and selling stocks, retrieving holdings and transaction history, and settlement-aware selling with FIFO lot consumption. These .feature files serve as human-readable documentation and traceable references for Java tests via @SpecificationRef annotations, establishing a clear link from requirement to test to code without being executed by Cucumber themselves.

doc/features · high confidence

Introduced new documentation for the HexaStock demo, including an agenda (\Agenda.md\) that outlines the presentation structure and a detailed demo script (\DemoScript.MD\) explaining the application of Domain-Driven Design and Hexagonal Architecture. The materials cover key concepts such as rich domain models, port/adapter decoupling, and the specific FIFO stock-selling use case, along with references to embedded diagrams and testing strategies.

doc/demo · high confidence

The documentation now includes a set of PlantUML diagrams and their rendered SVGs for the 'defensa-placa-permanent-dsi-ports-sortida-hexagonal' presentation. These visuals illustrate the AGAUR scholarship evaluation process, contrasting a coupled 'before' state with a decoupled 'after' hexagonal architecture. The diagrams detail the functional flow, data interoperability with external services (PICA, AEAT, Cadastre), and the specific role of output ports and adapters in isolating technical details from the core domain logic.

doc/presentations/defensa-placa-permanent-dsi-ports-sortida-hexagonal/diagrams · high confidence

The presentation now includes a complete, reproducible analysis of senior software engineering job postings from July 2026. This addition provides the Python script (\analyze\_jobs.py\), raw data processing logic, and resulting CSV/JSON datasets used to evaluate the prevalence of socioemotional competencies in the market. It also includes the full Markdown report and CSS styling for the generated PDF, allowing users to verify the study's methodology and findings regarding communication, collaboration, and leadership requirements in senior roles.

doc/presentations/defensa-placa-permanent-dsi-ports-sortida-hexagonal/analysis · high confidence

The tutorial now includes a comprehensive set of reference diagrams in the \doc/tutorial/sellStocks/diagrams\ directory to explain the HexaStock sell-stocks feature. These assets include a Mermaid-based hexagonal architecture overview, PlantUML domain class and sequence diagrams illustrating the FIFO sell logic, and sequence diagrams detailing the application service orchestration, persistence adapter interactions, and error handling flows (such as invalid quantities and portfolio not found).

doc/tutorial/sellStocks/diagrams · high confidence

Added shell scripts to automatically render PlantUML diagrams into SVG and PNG formats using Docker. The new \render-diagrams.sh\ script processes all \.puml\ and \.plantuml\ files in the repository, generating output images in sibling \Rendered/\ directories, while \render-diagram.sh\ provides a utility for rendering individual files.

scripts · high confidence

This location now contains the complete, canonical materials for the TecnoCampus DSI defense presentations, including a 20-minute lecture on hexagonal architecture output ports and a 10-minute trajectory defense. The entry introduces structured documentation (AGENTS.md, CLAUDE.md, README.md) that defines the source-of-truth files (canonical PPTX and Markdown scripts) and establishes strict workflows for generating derived artifacts like PDFs and DOCX exports via shell scripts. It also includes the functional case study documentation (cas-funcional-agaur-beca.md) detailing the AGAUR scholarship evaluation context, a final checklist (checklist.md) for institutional and technical rigor, and utility scripts for rendering PlantUML diagrams and managing LibreOffice headless conversions.

doc/presentations/defensa-placa-permanent-dsi-ports-sortida-hexagonal · high confidence

This change introduces the JPA-based persistence layer for the HexaStock application, enabling portfolios, holdings, lots, and transactions to be stored in a relational database (MySQL). It adds JPA entities (PortfolioJpaEntity, TransactionJpaEntity, etc.), Spring Data repositories, and mappers to translate between domain models and database records. The portfolio repository uses pessimistic locking to prevent concurrent modification issues and @BatchSize to optimize lazy-loading of holdings. Test infrastructure is included using Testcontainers to verify the adapter against a real MySQL instance.

adapters-outbound-persistence-jpa · high confidence

This change introduces the inbound REST adapter module, providing the HTTP interface for the application. It exposes endpoints for managing portfolios (create, retrieve, list, deposit, withdraw) and executing stock operations (buy, sell) via the new PortfolioRestController, as well as retrieving live stock prices via StockRestController. The adapter includes a global exception handler that maps domain exceptions to standardized RFC 7807 ProblemDetail responses and defines the necessary DTOs for request and response payloads. Comprehensive WebMvc slice tests are included to verify the controller logic and error handling.

adapters-inbound-rest · high confidence

This change introduces the foundational structure for the HexaStock project, including the Apache 2.0 license, a comprehensive README with setup instructions, and a GitBook-based documentation system (SUMMARY.md, .gitbook.yaml). It adds a CONTRIBUTING guide enforcing Hexagonal Architecture principles, CI/CD setup and walkthrough documents (CI\_SETUP.md, CI\_DISCIPLINE\_WALKTHROUGH.md, CI\_DEMO\_SCRIPT.md), and a .env.example file for configuring API keys and MongoDB connections. The repository also includes a docker-compose.yml with a MongoDB service for the \mongodb\ profile, a sonar-project.properties file for quality gate integration, and updated .gitignore rules to exclude local secrets and OS-specific files.

(repo-wide) · high confidence

Added the @RetryOnWriteConflict annotation to the application layer, allowing service methods to be automatically retried when concurrent write conflicts occur during persistence. This annotation is designed to work alongside @Transactional, requiring an infrastructure aspect to intercept calls and re-execute the entire use case (read, domain logic, write) in a new transaction upon conflict, up to a configurable number of attempts (defaulting to 3).

application/src/main/java/cat/gencat/agaur/hexastock/application/annotation · high confidence

A new MongoDB-based persistence adapter is now available when running with the 'mongodb' Spring profile. This adapter introduces document models for Portfolios, Holdings, Lots, and Transactions, along with the necessary mappers and Spring Data repositories to persist portfolio data. It implements optimistic locking on Portfolio documents to detect and prevent concurrent stale writes, ensuring data integrity during simultaneous updates.

adapters-outbound-persistence-mongodb · high confidence

This change introduces the definitive, printed oral scripts and supporting materials for the two main parts of the defense presentation. It adds \materials-orals-canonics-10-minuts-trajectoria.md\, which provides a structured 10-minute narrative for the professional, academic, and scientific trajectory (including speaker notes and an annex for Q&A), and \materials-orals-canonics-20-minuts.md\, which details the 20-minute master class on designing output ports in hexagonal architecture (explicitly marking the live demo as optional). It also includes \recordatori-millores-diapositives.md\ and \resum-decisions-trajectoria-10-minuts.md\ to document design decisions, such as the optional status of the demo and the curricular alignment arguments for the trajectory section.

doc/presentations/defensa-placa-permanent-dsi-ports-sortida-hexagonal/output · high confidence

A new tutorial has been added to the documentation that uses the HexaStock application to demonstrate the architectural trade-offs between Rich and Anemic Domain Models. The tutorial walks through a settlement-aware FIFO selling feature, showing how business rules are implemented in both styles. It includes a detailed Markdown guide explaining the financial context (T+2 settlement, lot reservation, fees, FIFO) and provides PlantUML-generated architecture and sequence diagrams to visualize the structural differences, specifically highlighting how the Anemic model duplicates logic in the service layer while the Rich model encapsulates it in domain entities.

doc/tutorial/richVsAnemicDomainModel · high confidence

The portfolio reporting tutorial now includes detailed documentation and sequence diagrams for the current in-memory aggregation approach (Approach A) and a proposed database-powered query side approach (Approach B). The new 'Holdings Performance at Scale' guide explains the O(T) single-pass algorithm, the rationale for avoiding parallel streams, and the memory/GC implications of BigDecimal allocations. The Approach B diagram illustrates a CQRS-style read model using SQL GROUP BY aggregation to reduce application memory footprint, introducing a new \HoldingsPerformanceQueryPort\.

doc/tutorial/portfolioReporting · high confidence

The watchlists tutorial documentation has been significantly enriched with a new architectural review of the Market Sentinel notification algorithm, detailing its CQRS placement, hexagonal architecture boundaries, and scalability trade-offs. The tutorial itself has been restructured into a progressive learning path (Levels 1–5) covering price thresholds, ladder alerts, percentage changes, contextual filters, and fatigue prevention. Additionally, the documentation now includes auto-rendered PlantUML sequence diagrams illustrating the CQRS read/write paths, market sentinel detection, and watchlist command flows, replacing manual inline diagrams.

doc/tutorial/watchlists · high confidence

The application-finhub.properties and application-mock.properties configuration files have been removed from the resources directory. This eliminates the ability to activate the 'finhub' or 'mock' Spring profiles via these specific property files, likely simplifying the configuration landscape or removing obsolete environment-specific setups.

src/main/resources · high confidence

The JPA-specific implementations for portfolio and transaction persistence (JpaPortfolioRepository and JpaTransactionRepository) have been removed from the codebase. This eliminates the direct JPA adapter layer for these entities, indicating a shift away from this specific persistence implementation or a consolidation of the data access strategy.

src/main/java/cat/gencat/agaur/hexastock/adapter/out/persistence/jpa/repository · high confidence

The JPA Spring Data repository interfaces for Portfolio and Transaction entities have been removed from the persistence adapter layer. This eliminates the automatic Spring Data JPA implementations for querying portfolios with pessimistic locking and retrieving transactions by portfolio ID, indicating a shift away from this specific repository-based persistence strategy.

src/main/java/cat/gencat/agaur/hexastock/adapter/out/persistence/jpa/springDataRepository · high confidence

The JPA adapter layer in the persistence mapper package has been removed, specifically deleting the HoldingMapper, LotMapper, PortfolioMapper, and TransactionMapper classes, along with the TransactionJpaEntity. This eliminates the code responsible for converting between JPA entities and domain models for holdings, lots, portfolios, and transactions within this specific adapter location.

src/main/java/cat/gencat/agaur/hexastock/adapter/out/persistence/jpa/mapper · high confidence

The application service classes GetStockPriceService, PortfolioManagmentService, PortfolioStockOperationsService, and TransactionService have been removed from the codebase. These classes previously implemented use cases for fetching stock prices, managing portfolio deposits/withdrawals, executing stock buy/sell operations, and retrieving transaction history. Their removal indicates a structural change to the application layer, likely shifting this logic to a different architectural component or implementation strategy.

src/main/java/cat/gencat/agaur/hexastock/application/service · high confidence

The domain model classes in the \cat.gencat.agaur.hexastock.model\ package have been removed from the codebase. This includes the \Holding\, \Lot\, \Portfolio\, \Transaction\, \StockPrice\, \Ticker\, \Money\, and \SellResult\ classes, as well as the \EntityExistsException\. These files are now deleted, meaning the domain entities and value objects that previously managed portfolio holdings, stock lots, transactions, and monetary values are no longer present in this module.

src/main/java/cat/gencat/agaur/hexastock/model · high confidence

The legacy REST API implementation in the \adapter/in\ package has been removed. This includes the deletion of \PortfolioRestController\, \StockRestController\, \ExceptionHandlingAdvice\, and \StockPriceDTO\. Consequently, the previous HTTP endpoints for managing portfolios (create, deposit, withdraw, buy, sell, get transactions) and fetching stock prices, along with the custom exception-to-plain-text error mapping, are no longer available via this adapter layer.

src/main/java/cat/gencat/agaur/hexastock/adapter/in · high confidence

The application port layer has been cleaned up by removing several obsolete interfaces and exception classes. Specifically, the \GetStockPriceUseCase\, \PortfolioManagmentUseCase\, \PortfolioStockOperationsUseCase\, and \TransactionUseCase\ interfaces have been deleted, along with their corresponding output ports (\PortfolioPort\, \StockPriceProviderPort\, \TransactionPort\) and unused exceptions (\ConflictQuantityException\, \InvalidQuantityException\, \PortfolioNotFoundException\). This change simplifies the hexagonal architecture by eliminating unused contracts, likely as part of a broader refactoring to consolidate portfolio and transaction handling.

src/main/java/cat/gencat/agaur/hexastock/application/port · high confidence

The adapter layer in \src/main/java/cat/gencat/agaur/hexastock/adapter/in/webmodel\ has removed seven data transfer objects: \CreatePortfolioDTO\, \DepositRequestDTO\, \PurchaseDTO\, \SaleRequestDTO\, \SaleResponseDTO\, \TransactionDTO\, and \WithdrawalRequestDTO\. These classes, which previously handled input and output serialization for portfolio and transaction operations, are no longer present in the codebase.

src/main/java/cat/gencat/agaur/hexastock/adapter/in/webmodel · high confidence

The mock implementation for the stock price provider (MockStockPriceAdapter) has been removed from the demo adapter layer. This eliminates the component that previously supplied simulated stock prices for specific tickers when the 'mock' profile was active, meaning the system no longer supports this specific in-memory simulation method for fetching stock data.

src/main/java/cat/gencat/agaur/hexastock/adapter/out/demo · high confidence

The FinnhubStockPriceAdapter class has been removed from the codebase. This change eliminates the previous implementation which contained a hardcoded Finnhub API token and threw generic RuntimeExceptions on failure, thereby removing a security risk and unused code from the REST adapter layer.

src/main/java/cat/gencat/agaur/hexastock/adapter/out/rest · high confidence

The application layer's service implementations have been split from a monolithic structure into distinct, single-responsibility services: CashManagementService (deposits/withdrawals), PortfolioLifecycleService (create/retrieve/list portfolios), PortfolioStockOperationsService (buy/sell stock with FIFO accounting), ReportingService (holdings performance), GetStockPriceService, and TransactionService (transaction history). All services now use Jakarta EE's @Transactional annotation instead of Spring's, and critical write operations (cash management and stock trading) are protected by a custom @RetryOnWriteConflict annotation to handle optimistic locking conflicts.

application/src/main/java/cat/gencat/agaur/hexastock/application/service · high confidence

The documentation has been consolidated into the \doc/\ directory, featuring a new \BOOK-HOME.md\ landing page that outlines the HexaStock technical book structure, including the dual-license model (Apache 2.0 for code, CC BY-NC 4.0 for content). A new \ACKNOWLEDGEMENTS.md\ file has been added to recognize contributors and institutional support. The API documentation is now supported by a formal \openapi.yaml\ specification and a \HexaStock.postman\_collection.json\ file for easier testing. Additionally, several design decision documents have been added or updated, including detailed guides on DDD aggregate separation (Portfolio vs. Transaction), handling zero-quantity lots, and MongoDB optimistic locking strategies.

doc · high confidence

The domain layer has been reorganized into distinct business packages (market, money, portfolio, transaction) and now enforces stricter type safety and financial invariants. Monetary values are handled by dedicated value objects (Money, Price, ShareQuantity) that validate positivity, normalize to two decimal places, and prevent primitive obsession. Portfolio operations now use a robust FIFO (First-In-First-Out) accounting method via the Holding and Lot entities, ensuring accurate cost basis and profit/loss calculations. New domain exceptions (InvalidAmountException, InvalidQuantityException, ConflictQuantityException) provide clear error semantics for invalid operations, and a new HoldingPerformanceCalculator enables efficient, single-pass performance metrics for holdings.

domain/src/main · high confidence

The application now automatically retries operations that fail due to MongoDB optimistic locking conflicts or concurrency issues, using a new aspect that wraps use-case methods annotated with @RetryOnWriteConflict. This change is part of a broader reorganization that introduces a bootstrap composition root (SpringAppConfig) to wire application services and use cases, and moves the main application class to the bootstrap module to serve as the central composition root for the hexagonal architecture.

bootstrap/src/main/java · high confidence

The application now supports switching between JPA and MongoDB persistence layers via Spring profiles. Activating the 'jpa' profile excludes all MongoDB auto-configurations to prevent connection errors, while the 'mongodb' profile excludes relational (JDBC/JPA) auto-configurations. Configuration values for database credentials, API keys (Finhub, Alpha Vantage), and cache settings are now externalized via environment variables with safe defaults, improving security and local development flexibility.

bootstrap/src/main/resources · high confidence

The application layer's driving and output ports have been reorganized to follow the Interface Segregation Principle, replacing the monolithic PortfolioManagementUseCase with focused interfaces: PortfolioLifecycleUseCase (creation and retrieval), CashManagementUseCase (deposits and withdrawals), PortfolioStockOperationsUseCase (buying and selling shares), ReportingUseCase, and TransactionUseCase. Additionally, new output ports (PortfolioPort, StockPriceProviderPort, TransactionPort) and a new application-layer exception (PortfolioNotFoundException) have been introduced to better abstract persistence and external data sources.

application/src/main/java/cat/gencat/agaur/hexastock/application/port · high confidence

Added application-layer unit and contract tests for core services and persistence ports; Added comprehensive integration tests and test infrastructure for portfolio operations and optimistic locking; Added domain unit tests and specification traceability annotations; Removal of legacy unit and integration tests.

The HexaStock build has been refactored from a single monolithic module into a seven-module Maven project (domain, application, adapters-inbound-rest, adapters-outbound-persistence-jpa, adapters-outbound-persistence-mongodb, adapters-outbound-market, and bootstrap) with the root POM now acting as a parent. This change centralizes dependency management via a BOM for Testcontainers (1.21.4) and defines specific versions for libraries such as SpringDoc OpenAPI (2.8.5), MySQL Connector/J (8.2.0), and Rest-Assured (5.4.0). It also standardizes build tooling by configuring JaCoCo for code coverage, Surefire for unit tests, and the Failsafe plugin for integration tests across all submodules.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 68 → 63 (-5.0)
• Rubric changed (rubric-2026.08.19 → rubric-2026.09.15) — scores are not directly comparable.

• Code Health 99 → 96 (-3.1)
• Architecture 100 → 75 (-24.9)
• Maturity 86 → 90 (+3.3)
• Readiness 55 → 57 (+1.8)
• Security 70 → 96 (+26.0)
• Domain Modelling 85 → 54 (-30.7)

• Coverage not included — suite not readable by the collector
• Dependency hygiene not measured — dependency manifest found but not parsed for hygiene
• Duplicated block (6 lines × 2) (adapters-outbound-persistence-jpa/src/main/java/cat/gencat/agaur/hexastock/adapter/out/persistence/jpa/mapper/TransactionMapper.java)
• Duplicated block (6 lines × 2) (adapters-outbound-persistence-mongodb/src/main/java/cat/gencat/agaur/hexastock/adapter/out/persistence/mongodb/mapper/TransactionDocumentMapper.java)
• Duplicated block (7 lines × 2) (adapters-inbound-rest/src/main/java/cat/gencat/agaur/hexastock/adapter/in/webmodel/TransactionDTO.java)
• Duplicated block (8 lines × 2) (domain/src/main/java/cat/gencat/agaur/hexastock/model/transaction/PurchaseTransaction.java)
• Duplicated block (9 lines × 2) (domain/src/main/java/cat/gencat/agaur/hexastock/model/portfolio/Lot.java)
• Further sole-owners (lower concentration)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• No exposed public API
• Off-boarding risk: anonymized user #1
• Scanner failed to run — not a clean result
• Test reliability not included
• The README mentions the book but does not link to it, so readers must infer the book exists from the presence of the title and the SonarQube quality badges. (README.md)

• ADR not followed: ADR-009: Use Testcontainers for integration tests instead of H2 (doc/architecture/adr/ADR-009-testcontainers-for-integration-tests.md)
• Dependency hygiene PARTLY measured — Maven/Gradle declarations read, no dependency graph resolved
• Documentation: no installation or build instructions (README.md)
• Documentation: no licence statement
• Documentation: no project overview (README.md)
• Documentation: no usage examples (README.md)
• Duplicated block (6 lines × 2) (adapters-outbound-persistence-jpa/src/main/java/cat/gencat/agaur/hexastock/adapter/out/persistence/jpa/mapper/TransactionMapper.java)
• Duplicated block (6 lines × 2) (adapters-outbound-persistence-mongodb/src/main/java/cat/gencat/agaur/hexastock/adapter/out/persistence/mongodb/mapper/TransactionDocumentMapper.java)
• Duplicated block (7 lines × 2) (adapters-inbound-rest/src/main/java/cat/gencat/agaur/hexastock/adapter/in/webmodel/TransactionDTO.java)
• Duplicated block (7 lines × 2) (adapters-outbound-persistence-jpa/src/main/java/cat/gencat/agaur/hexastock/adapter/out/persistence/jpa/entity/LotJpaEntity.java)
• Duplicated block (9 lines × 2) (adapters-outbound-persistence-jpa/src/main/java/cat/gencat/agaur/hexastock/adapter/out/persistence/jpa/mapper/LotMapper.java)
• Duplicated block (9 lines × 2) (adapters-outbound-persistence-jpa/src/main/java/cat/gencat/agaur/hexastock/adapter/out/persistence/jpa/mapper/LotMapper.java)
• Duplicated block (9 lines × 2) (domain/src/main/java/cat/gencat/agaur/hexastock/model/transaction/DepositTransaction.java)
• Duplicated block (9 lines × 2) (domain/src/main/java/cat/gencat/agaur/hexastock/model/transaction/PurchaseTransaction.java)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• Medium IaC: WD-COMPOSE-0002 (docker-compose.yml)
• Medium IaC: WD-COMPOSE-0002 (docker-compose.yml)
• …and 83 more

• 11 commits — 9 feature/other, 2 fixes

• (root) — 10 commits
• sell-stocks-domain-kata/docs — 1 commit

• fix: Fix PDF cover title alignment (was left-aligned, should be centered) (#38)
• fix: Fix missing diagram text in CI_DISCIPLINE_WALKTHROUGH.pdf (#35)
• change: Add PDF bookmarks (outline/table of contents) to the CI handout PDFs (#41)
• change: Add PDF versions of CI_DEMO_SCRIPT.md and CI_DISCIPLINE_WALKTHROUGH.md (#34)
• change: Add section 9: why a passing check isn't the whole guarantee (#39)
• change: Demo: break the build on purpose (#33)
• change: Document the CI discipline on main, with verified evidence (#31)
• change: Ignore more OS cruft; document the accidental-direct-commit case (#40)
• change: Note the staged-pipeline split as a deliberately deferred future improvement (#32)
• change: Restyle PDFs: recover the original handout aesthetic (#37)
• change: Tell students to fork before cloning (#36)

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

alfredorueda/HexaStock was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.