Opportunity Module Specification

Purpose

The opportunity module implements the Opportunity Domain inside the Spring Boot Modulith. It owns tender discovery, source management, tender indexing, documents, requirements, deadlines, briefings, eligibility, qualification, matching, recommendations, saved tenders, watchlists, bid/no-bid recommendation, win probability estimate, and tender risk assessment.

Owned Domain

Opportunity owns tender records, public and private tender source configuration, tender lifecycle state, tender document metadata, captured tender requirements, briefing sessions, deadlines, matches, qualification assessments, recommendation records, saved opportunities, watchlists, and tender risk assessments.

Owned Aggregates

Aggregate	Responsibility
Tender Opportunity	Root aggregate for tender facts, source, status, documents, deadlines, and briefing sessions.
Tender Source	Source identity, source type, reliability, and ingestion rules.
Tender Index	Searchable structured representation, indexed fields, extracted requirements, and document references.
Opportunity Match	Match between organization and tender with score, reasons, inputs, and status.
Qualification Assessment	Eligibility, fit, effort, risk, and readiness analysis.
Recommendation Record	Bid/no-bid recommendation, rationale, confidence, and win probability estimate.
Watchlist	Customer monitoring criteria, saved filters, and alert state.
Saved Opportunity	Customer saved tender pipeline state, notes, priority, and follow-up state.

Owned Entities

Tender Opportunity, Tender Source, Tender Document, Tender Requirement, Briefing Session, Tender Deadline, Tender Match, Qualification Assessment, Recommendation Record, Saved Opportunity, and Watchlist.

Owned Value Objects

TenderOpportunityId, TenderSourceType, TenderReferenceNumber, TenderCategory, TenderRegion, TenderDeadlineType, TenderDeadlineDate, MatchScore, QualificationStatus, RecommendationDecision, WinProbabilityEstimate, TenderRiskLevel, SavedOpportunityPriority, and WatchlistCriteria.

Commands

Command	Responsibility
RegisterTenderSource	Add an approved tender source configuration.
DiscoverTender	Create tender opportunity from source or manual intake.
DeduplicateTender	Link or reject duplicate tender discovery.
AddTenderDocument	Register tender document metadata and storage reference.
CaptureTenderRequirement	Record requirement while preserving source context.
TrackBriefingSession	Record briefing date, method, and attendance requirement.
TrackTenderDeadline	Record submission, briefing, clarification, or other deadline.
IndexTender	Update structured searchable tender representation.
MatchTenderToOrganization	Create or update organization-specific match record.
CompleteQualificationAssessment	Record eligibility, fit, effort, risk, and readiness analysis.
CreateBidNoBidRecommendation	Create recommendation record and win probability estimate.
SaveTenderOpportunity	Save opportunity into a customer pipeline.
CreateWatchlist	Create monitoring criteria for a customer.
AssessTenderRisk	Record risk level and causes.

Queries

Query	Responsibility
GetTenderSource	Return source configuration summary.
GetTenderOpportunity	Return tender opportunity read model and lifecycle state.
SearchTenderOpportunities	Search indexed tender records.
GetTenderDocuments	Return tender document metadata and indexing state.
GetTenderRequirements	Return captured requirements and source references.
GetTenderDeadlines	Return deadline and briefing timeline.
GetOrganizationMatches	Return matches for an organization.
GetQualificationAssessment	Return eligibility, fit, effort, readiness, and risk factors.
GetRecommendationRecord	Return bid/no-bid recommendation and rationale.
GetSavedOpportunities	Return customer saved tender pipeline.
GetWatchlists	Return monitoring criteria and status.

Application Services

TenderSourceApplicationService, TenderDiscoveryApplicationService, TenderIndexingApplicationService, TenderDocumentApplicationService, TenderRequirementApplicationService, DeadlineApplicationService, TenderMatchingApplicationService, QualificationApplicationService, RecommendationApplicationService, SavedOpportunityApplicationService, WatchlistApplicationService, and TenderRiskApplicationService.

Domain Services

TenderSourceIntakeService, TenderDeduplicationService, TenderIndexingService, TenderMatchingService, DeadlineRiskService, BriefingRequirementService, QualificationService, RecommendationService, WatchlistAlertService, and TenderRiskAssessmentService.

Policies

Tender Source Intake Policy, Tender Deduplication Policy, Tender Indexing Policy, Tender Matching Policy, Deadline Risk Policy, Briefing Requirement Policy, Qualification Policy, Recommendation Policy, and Watchlist Alert Policy.

Repositories

TenderSourceRepository, TenderOpportunityRepository, TenderDocumentRepository, TenderRequirementRepository, TenderIndexRepository, TenderDeadlineRepository, TenderMatchRepository, QualificationAssessmentRepository, RecommendationRecordRepository, SavedOpportunityRepository, WatchlistRepository, TenderRiskRepository, and OpportunityAuditRepository.

Events Published

TenderSourceRegistered, TenderDiscovered, TenderIndexed, TenderDocumentAdded, TenderRequirementCaptured, BriefingSessionTracked, TenderDeadlineTracked, TenderMatchedToOrganization, QualificationAssessmentCompleted, BidNoBidRecommendationCreated, TenderRiskAssessed, TenderSaved, and WatchlistCreated.

Events Consumed

OrganizationProfileUpdated, ProcurementPreferencesUpdated, CapabilityVerified, ProcurementReadinessScoreUpdated, ComplianceRiskIdentified, AISuggestionAccepted, TenderWorkspaceCreated, BidSubmitted, BidOutcomeCaptured, IntegrationTenderSourceChanged, and AdministrativePolicyChanged. Consumed events refresh matches, recommendations, and watchlist outputs without owning publisher facts.

REST API Responsibility

The module owns API responsibilities for tender sources, tender opportunity records, tender documents, tender requirements, briefing sessions, deadlines, matching, qualification, recommendations, watchlists, saved opportunities, and tender risk views. It does not define final endpoint specifications in this work order.

Database Ownership

Opportunity owns conceptual persistence for tender sources, tender opportunities, tender documents, tender requirements, briefing sessions, tender deadlines, tender indexes, opportunity matches, qualification assessments, recommendation records, saved opportunities, watchlists, tender risk assessments, and opportunity audit logs.

Module Dependencies

Allowed dependencies are shared kernel identifiers, identity authorization context, organization profile and preference read models, compliance readiness and risk summaries, intelligence analysis and extraction suggestions, notification deadline and watchlist triggers, analytics projections, and integration source ingestion adapters.

Forbidden Dependencies

Opportunity must not mutate Organization profile, Compliance readiness, Bid workspace, Contract delivery, Billing entitlement, Notification delivery, Analytics projection, or raw Intelligence memory records. It must not create proposal content or submission packages.

AIOS Interaction Boundary

AIOS may assist with tender extraction, summarization, classification, matching reasons, qualification factors, risk explanations, and recommendation support. Opportunity owns the resulting tender records, matches, qualification assessments, and recommendation records after governed acceptance.

Security And Tenant Rules

• Public tender discovery may be platform-scoped; saved tenders, matches, watchlists, and recommendations are tenant-scoped.
• Organization-specific matching requires authorized OrganizationId context.
• Source metadata and document provenance must be preserved.
• Customer notes, priorities, and recommendation outcomes must not leak across tenants.
• Recommendation decisions are decision-support records, not automatic bid creation.

Test Strategy

Tests must cover source intake, deduplication, document metadata, requirement capture, deadline timezone handling, matching, qualification, recommendation, watchlist behavior, saved opportunities, event publication, idempotent consumption, tenant filtering, AIOS suggestion acceptance boundaries, and Spring Modulith dependency verification.

Future Microservice Extraction Notes

Opportunity is a strong future extraction candidate because tender aggregation and search can scale independently. Extraction requires source ingestion contracts, search index contracts, event delivery to Compliance and Bid, tenant-aware saved opportunity storage, and stable APIs for matching and recommendation reads.

Mermaid Component Diagram

flowchart TD
    Api[opportunity.api.rest]
    App[opportunity.application.service]
    Command[opportunity.application.command]
    Query[opportunity.application.query]
    Domain[opportunity.domain.model]
    Policy[opportunity.domain.policy]
    Repo[opportunity.infrastructure.persistence]
    Integration[opportunity.infrastructure.integration]
    Messaging[opportunity.infrastructure.messaging]
    Search[search index]
    Organization[organization context]
    Compliance[compliance readiness]
    Intelligence[intelligence analysis]
    Notification[notification triggers]
    Bid[bid workspace signal]

    Api --> App
    App --> Command
    App --> Query
    App --> Domain
    Domain --> Policy
    App --> Repo
    App --> Integration
    App --> Search
    App --> Messaging
    App --> Organization
    App --> Compliance
    App --> Intelligence
    Messaging --> Notification
    Messaging --> Bid