Marketplace Module Specification¶

Purpose¶

The marketplace module implements the Marketplace Domain inside the Spring Boot Modulith. It owns provider listing, discovery, category browsing, search sessions, marketplace matching, recommendation display, verification display, quote request workflow, support request workflow, and listing visibility.

Owned Domain¶

Marketplace owns marketplace workflow and display state. It references Supplier, Funding, Organization, Contract, and Intelligence records but does not own their source facts, performance records, funding application state, customer profile facts, contract delivery state, or AI reasoning sessions.

Owned Aggregates¶

Aggregate	Responsibility
Marketplace Listing	Root aggregate for provider display, listing content, category links, status, and visibility.
Provider Category Catalogue	Category hierarchy and browsing metadata.
Marketplace Search Session	Query, filters, result context, and search interaction record.
Marketplace Match	Match score, reasons, and recommendation display context.
Quote Request Workflow	Request lifecycle, provider targets, state, and response references.
Support Request Workflow	Provider support request type, participants, state, and outcome.
Marketplace Visibility Control	Listing publication rules, visibility status, and display conditions.

Owned Entities¶

Marketplace Listing, Marketplace Provider, Provider Category, Search Session, Search Result, Marketplace Match, Quote Request, Support Request, Verification Display, and Recommendation Display.

Owned Value Objects¶

MarketplaceListingId, MarketplaceProviderType, ListingStatus, VisibilityStatus, ProviderCategoryCode, SearchFilter, MatchScore, RequestStatus, VerificationDisplayStatus, and RecommendationDisplayReason.

Commands¶

Command	Responsibility
CreateMarketplaceListing	Create provider listing workflow record.
PublishMarketplaceListing	Make listing visible after policy checks.
SuspendMarketplaceListing	Remove or limit display due to governance issue.
CreateProviderCategory	Add category to governed catalogue.
UpdateListingVisibility	Change listing visibility state.
UpdateVerificationDisplay	Update displayed verification signal reference.
RecordMarketplaceSearch	Capture search session, filters, and context.
CreateMarketplaceMatch	Record match between customer need and listing.
DisplayRecommendation	Record provider recommendation shown to customer.
CreateQuoteRequest	Start quote request workflow.
RecordQuoteRequestResponse	Record provider response state.
CreateSupportRequest	Start provider support request workflow.

Queries¶

Query	Responsibility
GetMarketplaceListing	Return listing and display state.
BrowseProviderCategories	Return category hierarchy and visible listings.
SearchMarketplace	Return search results using governed filters.
GetMarketplaceMatches	Return customer-specific matches and reasons.
GetVerificationDisplay	Return displayed verification signal references.
GetRecommendationDisplays	Return shown recommendations and display rationale.
GetQuoteRequests	Return quote request workflow state.
GetSupportRequests	Return support request workflow state.

Application Services¶

MarketplaceListingApplicationService, ProviderCategoryApplicationService, MarketplaceSearchApplicationService, MarketplaceMatchingApplicationService, VisibilityApplicationService, VerificationDisplayApplicationService, RecommendationDisplayApplicationService, QuoteRequestApplicationService, and SupportRequestApplicationService.

Domain Services¶

ListingPublicationService, CategoryGovernanceService, VisibilityService, VerificationDisplayService, MarketplaceMatchingService, RecommendationDisplayService, QuoteRequestService, SupportRequestService, and ListingSuspensionService.

Policies¶

Listing Publication Policy, Category Governance Policy, Visibility Policy, Verification Display Policy, Marketplace Matching Policy, Recommendation Display Policy, Quote Request Policy, Support Request Policy, and Listing Suspension Policy.

Repositories¶

MarketplaceListingRepository, MarketplaceProviderRepository, ProviderCategoryRepository, SearchSessionRepository, SearchResultRepository, MarketplaceMatchRepository, ListingVisibilityRepository, VerificationDisplayRepository, QuoteRequestRepository, SupportRequestRepository, RecommendationDisplayRepository, and MarketplaceAuditRepository.

Events Published¶

MarketplaceListingCreated, MarketplaceListingPublished, MarketplaceListingSuspended, ProviderCategoryCreated, MarketplaceSearchPerformed, MarketplaceMatchCreated, RecommendationDisplayed, QuoteRequestCreated, QuoteRequestResponded, SupportRequestCreated, and VerificationDisplayUpdated.

Events Consumed¶

SupplierProfileCreated, SupplierProfileUpdated, SupplierCapabilityAdded, SupplierTrustUpdated, FundingRecommendationCreated, FundingApplicationStatusChanged, OrganizationProfileUpdated, ProcurementPreferencesUpdated, ContractWorkspaceCreated, AIRecommendationProduced, and AdministrativePolicyChanged.

REST API Responsibility¶

The module owns API responsibilities for marketplace listings, provider categories, search, listing visibility, verification display, matching, quote requests, support requests, and recommendation displays. Final endpoint specifications are deferred.

Database Ownership¶

Marketplace owns conceptual persistence for marketplace listings, marketplace providers, provider categories, search sessions, search results, marketplace matches, listing visibility, verification displays, quote requests, support requests, recommendation displays, and marketplace audit logs.

Module Dependencies¶

Allowed dependencies are shared kernel identifiers, identity authorization context, organization customer context, supplier profile/trust signals, funding partner and recommendation signals, contract support request context, notification workflow triggers, analytics projections, and intelligence recommendation boundaries.

Forbidden Dependencies¶

Marketplace must not mutate Supplier performance or trust facts, Funding products or applications, Organization profile facts, Contract delivery records, Intelligence reasoning sessions, Notification delivery records, or Analytics projections. Verification display must not become verification ownership.

AIOS Interaction Boundary¶

AIOS may recommend providers, explain marketplace matches, rank listings, and propose support workflows. Marketplace decides whether recommendations are displayed and records display state with source references.

Security And Tenant Rules¶

Public listing visibility must respect provider publication and suspension state.
Customer searches, matches, quote requests, support requests, and recommendation displays are tenant-scoped.
Verification and trust signals must preserve source-domain provenance.
Quote and support workflows require authorized organization context.
Marketplace display must not leak private supplier relationship notes, funding applications, or contract details.

Test Strategy¶

Tests must cover listing publication, category governance, visibility changes, verification display, matching, recommendation display, quote requests, support requests, listing suspension, event publication, idempotent event consumption, tenant filtering, authorization, and Spring Modulith boundaries.

Future Microservice Extraction Notes¶

Marketplace can be extracted when discovery/search workflows require independent scaling. Extraction requires stable listing APIs, search contracts, quote request events, provider signal read models, and strict separation from Supplier and Funding source stores.

Mermaid Component Diagram¶

flowchart TD
    Api[marketplace.api.rest]
    App[marketplace.application.service]
    Command[marketplace.application.command]
    Query[marketplace.application.query]
    Domain[marketplace.domain.model]
    Policy[marketplace.domain.policy]
    Repo[marketplace.infrastructure.persistence]
    Search[marketplace search index]
    Messaging[marketplace.infrastructure.messaging]
    Supplier[supplier signals]
    Funding[funding partners]
    Organization[organization context]
    Intelligence[intelligence recommendations]
    Notification[notification triggers]

    Api --> App
    App --> Command
    App --> Query
    App --> Domain
    Domain --> Policy
    App --> Repo
    App --> Search
    App --> Messaging
    App --> Supplier
    App --> Funding
    App --> Organization
    App --> Intelligence
    Messaging --> Notification