Organization Module Specification¶
Purpose¶
The organization module implements the Organization Domain inside the Spring Boot Modulith. It is the customer business root for Algosure and owns the durable organization context used by procurement, compliance, opportunity matching, bid preparation, contract delivery, marketplace participation, funding, learning, intelligence, analytics, and billing.
Owned Domain¶
Organization owns organization identity, legal and trading profile, directors, contacts, addresses, branches, departments, employees, services, products, capabilities, equipment, fleet assets, past projects, client references, certifications, licences, procurement preferences, Organization Intelligence Graph, and Organizational Memory boundaries.
Owned Aggregates¶
| Aggregate | Responsibility |
|---|---|
| Organization | Root aggregate for organization identity, lifecycle state, profile references, ownership rules, and governance metadata. |
| Organization Profile | Legal, trading, descriptive, contact, branch, department, and structural profile. |
| Capability Profile | Services, products, capabilities, certifications, licences, and evidence. |
| Resource Profile | Equipment, fleet assets, employees, and delivery capacity resources. |
| Experience Profile | Past projects and client references. |
| Procurement Preference Profile | Target sectors, regions, opportunity preferences, exclusions, and constraints. |
| Organization Intelligence Graph | Connected facts, relationships, inferred insights, and memory links with provenance. |
Owned Entities¶
Organization, Organization User, Director, Contact, Address, Branch, Department, Employee, Service, Product, Capability, Equipment, Fleet Asset, Past Project, Client Reference, Certification, and Licence.
Owned Value Objects¶
OrganizationId, RegistrationNumber, TaxNumber, VATNumber, EmailAddress, PhoneNumber, AddressDetails, GeographicCoverage, IndustryClassification, CapabilityEvidenceLevel, AIConfidenceScore, VerificationStatus, OrganizationStatus, Money, DateRange, and ContractValueRange.
Commands¶
| Command | Responsibility |
|---|---|
| RegisterOrganization | Create the organization root and initial lifecycle state. |
| CreateOrganizationProfile | Establish legal, trading, and operating profile data. |
| UpdateOrganizationProfile | Change organization-owned profile facts with audit metadata. |
| ActivateOrganization | Move organization to active when activation policy passes. |
| SuspendOrganization | Suspend organization participation after governed triggers. |
| ArchiveOrganization | Archive organization with retention context. |
| AddOrganizationUserAssociation | Record organization-side association to a user identity. |
| AddDirector | Add director record and verification state. |
| AddContact | Add business contact with purpose. |
| AddServiceOrProduct | Add service or product offering. |
| AddCapability | Add capability claim and evidence level. |
| VerifyCapability | Change capability verification state. |
| AddPastProject | Add experience evidence. |
| UpdateProcurementPreferences | Change matching preferences and constraints. |
| ReviewOrganizationAISuggestion | Accept, reject, or hold AI-enriched organization suggestion. |
| UpdateOrganizationMemoryBoundary | Update organization memory references with provenance. |
Queries¶
| Query | Responsibility |
|---|---|
| GetOrganizationProfile | Return governed organization profile read model. |
| GetOrganizationContext | Return domain-safe context for other modules and AIOS. |
| GetOrganizationUsers | Return organization-side user association summary. |
| GetCapabilities | Return capabilities, evidence level, and verification status. |
| GetResources | Return operating resources relevant to procurement and delivery. |
| GetExperience | Return past project and client reference summaries. |
| GetProcurementPreferences | Return matching preferences and exclusions. |
| GetOrganizationIntelligenceGraph | Return approved graph summary and provenance. |
| GetOrganizationalMemorySummary | Return memory boundary summary without leaking unrelated tenant data. |
Application Services¶
OrganizationProfileApplicationService, OrganizationLifecycleApplicationService, OrganizationUserApplicationService, CapabilityProfileApplicationService, ResourceProfileApplicationService, ExperienceProfileApplicationService, ProcurementPreferenceApplicationService, OrganizationIntelligenceApplicationService, and OrganizationMemoryApplicationService.
Domain Services¶
OrganizationActivationService, ProfileCompletenessService, CapabilityVerificationService, OrganizationSuspensionService, DataOwnershipService, CrossDomainReferenceService, and AISuggestionReviewService.
Policies¶
Organization Activation Policy, Profile Completeness Policy, Capability Verification Policy, AI Suggestion Review Policy, Organization Suspension Policy, Data Ownership Policy, and Cross-Domain Reference Policy.
Repositories¶
OrganizationRepository, OrganizationProfileRepository, CapabilityProfileRepository, ResourceProfileRepository, ExperienceProfileRepository, ProcurementPreferenceRepository, OrganizationIntelligenceGraphRepository, OrganizationMemoryRepository, and OrganizationAuditRepository. Repositories are private to organization.infrastructure.persistence.
Events Published¶
OrganizationRegistered, OrganizationProfileCreated, OrganizationProfileUpdated, OrganizationActivated, OrganizationSuspended, OrganizationArchived, OrganizationUserAdded, DirectorAdded, ServiceAdded, ProductAdded, CapabilityAdded, CapabilityVerified, EquipmentRegistered, FleetAssetRegistered, PastProjectAdded, ClientReferenceAdded, ProcurementPreferencesUpdated, OrganizationIntelligenceGraphUpdated, and OrganizationalMemoryUpdated.
Events Consumed¶
InvitationAccepted, MembershipActivated, MembershipSuspended, ComplianceProfileCreated, ProcurementReadinessScoreUpdated, ComplianceRiskIdentified, TenderMatchedToOrganization, TenderSaved, BidOutcomeCaptured, LessonsLearnedCaptured, SubscriptionSuspended, and AdministrativePolicyChanged. Consumed events update Organization-owned associations, summaries, or memory boundaries without taking ownership of publisher facts.
REST API Responsibility¶
The module owns API responsibilities for organization profile, organization users, directors, contacts, addresses, services, products, capabilities, resources, experience, procurement preferences, organization intelligence graph summaries, and organization memory summaries. It exposes governed read models for other modules and UI clients.
Database Ownership¶
Organization owns conceptual persistence for organizations, organization profiles, organization users, directors, contacts, addresses, services, products, capabilities, equipment, fleet assets, past projects, client references, procurement preferences, organization intelligence graph, organization memory, and organization audit logs.
Module Dependencies¶
Allowed dependencies are shared kernel identifiers, identity authorization context, compliance readiness events and read models, opportunity match events and read models, bid outcome events, billing account-status events, notification intents, analytics event consumption, and intelligence AI suggestion boundaries.
Forbidden Dependencies¶
Organization must not own credentials, sessions, permissions, compliance decisions, tender records, bid workspaces, billing entitlements, notification delivery records, analytics projections, or raw AI reasoning sessions. Other modules must not directly mutate Organization-owned tables or import Organization repositories and aggregates.
AIOS Interaction Boundary¶
AIOS may propose profile enrichments, capability classifications, procurement preferences, graph links, and memory updates through application services. Organization decides whether suggestions become canonical organization facts. AIOS must preserve confidence, source, model, timestamp, and tenant context.
Security And Tenant Rules¶
- Every organization-scoped command and query requires authenticated actor context and
OrganizationId. - Identity authorizes access; Organization owns the business facts returned or changed.
- Customer-supplied facts, verified facts, and AI-enriched suggestions must be distinguishable.
- Cross-tenant graph or memory leakage is forbidden.
- Sensitive personal or director data must be minimized and access-controlled.
Test Strategy¶
Tests must cover aggregate invariants, profile completeness, activation and suspension rules, capability verification, AI suggestion review, cross-domain reference validation, event publication, idempotent event consumption, tenant filtering, authorization enforcement at application service boundaries, repository ownership, and Spring Modulith dependency verification.
Future Microservice Extraction Notes¶
Organization is a likely future boundary because it is the tenant root and heavily reused. Extraction requires stable organization context APIs, event streams, read models for dependent modules, data ownership isolation, tenant-aware migration strategy, and replacement of in-process calls with contracts.
Mermaid Component Diagram¶
flowchart TD
Api[organization.api.rest]
App[organization.application.service]
Command[organization.application.command]
Query[organization.application.query]
Domain[organization.domain.model]
Policy[organization.domain.policy]
Repo[organization.infrastructure.persistence]
Messaging[organization.infrastructure.messaging]
Identity[identity authorization]
Compliance[compliance summaries]
Opportunity[opportunity matches]
Intelligence[intelligence suggestions]
Analytics[analytics projections]
Api --> App
App --> Command
App --> Query
App --> Domain
Domain --> Policy
App --> Repo
App --> Messaging
App --> Identity
App --> Compliance
App --> Opportunity
App --> Intelligence
Messaging --> Analytics