application-party-discovery

Sprint 3.69 Phase 1 item 3 — business-discovery composition module: Google Places search -> contact/domain enrichment -> human-reviewed staging, never auto-writing an Organization.

Tier	application
Role	unclassified (baselined)
Path	`crates/application/party-discovery`
Edition	2024
Targets	application_party_discovery, pg_forge_party_discovery
Public items	38 across 8 modules
Tests	24

What it is for

application-party-discovery — business-discovery composition module.

Sprint 3.69 Phase 1 item 3 (docs/planning/PARTY-DOSSIER-VAULT-ROADMAP.md). Composes four already-real crates (infrastructure-adapters-google-places, infrastructure-web-contact-extractor, infrastructure-web-domain-intel, domain-competitive-intel) into a search-and-enrich pipeline, staged for human review (discovery_run/discovery_candidate — Gate 1.5, unanimous). A candidate is NEVER an Organization until a human explicitly imports it via api::discovery_admin (item 4).

Money note: infrastructure_adapters_google_places::GooglePlacesClient::search_text makes a real, billed call. Nothing in this crate calls it automatically — pipeline::discover takes an already-constructed GooglePlacesClient the caller owns, and this crate's own test suite never constructs a real one. Use infrastructure_adapters_google_places::GooglePlacesClient::dry_run_estimate (pure, local, no network) to show the operator a cost estimate BEFORE calling discover — Gate 1.5 open question 5 (cost surfacing), still open at the UI layer.

Capabilities

`PartyDiscoveryModule`

application-party-discovery — business-discovery composition module.

Item
`pub struct PartyDiscoveryModule`
`PartyDiscoveryModule :: fn new() -> Self`
`PartyDiscoveryModule :: fn name(& self) -> & 'static str`
`PartyDiscoveryModule :: fn version(& self) -> & 'static str`
`PartyDiscoveryModule :: fn migrations(& self) -> Vec <MigrationSet>`
`PartyDiscoveryModule :: async fn migrate_pending(& self, pool : & PgPool) -> std::result::Result <u32, MigrationError>`
`PartyDiscoveryModule :: fn permission_codes(& self) -> Vec <String>`

`api (other)`

HTTP API routers for application-party-discovery.

Item
`fn admin_router <S>() -> Router <S> where S : Clone + Send + Sync + 'static, PgPool : FromRef <S>,`

`api::discovery_admin (other)`

Discovery-candidate admin REST router — the browse/review/decide half

Item
`pub const MAX_PAGE_SIZE: u32`
`pub const DEFAULT_PAGE_SIZE: u32`
`fn to_dto(c : & DiscoveryCandidate) -> DiscoveryCandidateDto`
`fn organization_from_candidate(c : & DiscoveryCandidate) -> Organization`
`fn clamp_paging(page : Option <u32>, page_size : Option <u32>) ->(u32, u32)`
`fn page_offset(page : u32, page_size : u32) -> i64`
`fn router <S>() -> Router <S> where S : Clone + Send + Sync + 'static, PgPool : FromRef <S>,`

`ListCandidatesQuery`

Discovery-candidate admin REST router — the browse/review/decide half

Item
`pub struct ListCandidatesQuery`

`TenantQuery`

Discovery-candidate admin REST router — the browse/review/decide half

Item
`pub struct TenantQuery`

`dedup (other)`

Entity resolution — Gate 1.5's precedence table (`docs/userstories/

Item
`fn normalize_domain(website_or_domain : & str) -> Option <String>`
`fn find_suspected_duplicate(existing : & DiscoveryCandidate, place_id : & str, domain : Option <& str>,) -> Option <Uuid>`

`DiscoveryError`

Error type for application-party-discovery.

Item
`pub enum DiscoveryError`

`CandidateStatus`

Discovery staging models — discovery_runs/discovery_candidates.

Item
`pub enum CandidateStatus`
`CandidateStatus :: fn as_str(& self) -> & 'static str`
`CandidateStatus :: fn parse(s : & str) -> Self`

`DiscoveryCandidate`

Discovery staging models — discovery_runs/discovery_candidates.

Item
`pub struct DiscoveryCandidate`

`DiscoveryRun`

Discovery staging models — discovery_runs/discovery_candidates.

Item
`pub struct DiscoveryRun`
`DiscoveryRun :: fn new(tenant_id : Uuid, query_text : impl Into <String>) -> Self`

`pipeline (other)`

The composition pipeline: Places search -> per-result contact/domain

Item
`async fn discover(pool : & PgPool, tenant_id : Uuid, places_client : & GooglePlacesClient, contact_extractor : & ContactExtractor, domain_analyzer : & DomainIntelAnalyzer, http : & SafeHttpClient, request : & TextSearchRequest,) -> Result <Vec <DiscoveryCandidate>, DiscoveryError>`

`repo (other)`

Database access for discovery_runs/discovery_candidates. Every

Item
`async fn create_discovery_run(pool : & PgPool, run : & DiscoveryRun,) -> Result <DiscoveryRun, DiscoveryError>`
`async fn find_discovery_run_for_tenant(pool : & PgPool, tenant_id : Uuid, id : Uuid,) -> Result <Option <DiscoveryRun>, DiscoveryError>`
`async fn list_candidates_for_run(pool : & PgPool, tenant_id : Uuid, discovery_run_id : Uuid,) -> Result <Vec <DiscoveryCandidate>, DiscoveryError>`
`async fn find_candidates_by_domain_for_tenant(pool : & PgPool, tenant_id : Uuid, domain : & str,) -> Result <Vec <DiscoveryCandidate>, DiscoveryError>`
`async fn upsert_candidate_for_tenant(pool : & PgPool, tenant_id : Uuid, candidate : & DiscoveryCandidate,) -> Result <DiscoveryCandidate, DiscoveryError>`
`async fn list_candidates_page_for_tenant(pool : & PgPool, tenant_id : Uuid, status : Option <CandidateStatus>, discovery_run_id : Option <Uuid>, limit : i64, offset : i64,) -> Result <(Vec <DiscoveryCandidate>, i64), DiscoveryError>`
`async fn find_candidate_for_tenant(pool : & PgPool, tenant_id : Uuid, id : Uuid,) -> Result <Option <DiscoveryCandidate>, DiscoveryError>`
`async fn mark_candidate_imported_for_tenant(pool : & PgPool, tenant_id : Uuid, id : Uuid, organization_id : Uuid,) -> Result <DiscoveryCandidate, DiscoveryError>`
`async fn mark_candidate_rejected_for_tenant(pool : & PgPool, tenant_id : Uuid, id : Uuid,) -> Result <DiscoveryCandidate, DiscoveryError>`
`async fn mark_candidate_duplicate_for_tenant(pool : & PgPool, tenant_id : Uuid, id : Uuid, duplicate_of_candidate_id : Uuid,) -> Result <DiscoveryCandidate, DiscoveryError>`

`scoring (other)`

Candidate scoring — decoupled from the discovery pipeline.

Item
`fn score_candidate(candidate : & DiscoveryCandidate) -> Option <EntityClassification>`

How to use it

No examples/ target and no doctest in this crate's rustdoc. The tests listed under Verification are the closest executable usage.

Module structure

application_party_discovery

api
api::discovery_admin
dedup
error
models
pipeline
repo
scoring

flowchart TD
  n_application_party_discovery["application_party_discovery"]
  n_application_party_discovery --> n_api["api"]
  n_api --> n_api__discovery_admin["discovery_admin"]
  n_application_party_discovery --> n_dedup["dedup"]
  n_application_party_discovery --> n_error["error"]
  n_application_party_discovery --> n_models["models"]
  n_application_party_discovery --> n_pipeline["pipeline"]
  n_application_party_discovery --> n_repo["repo"]
  n_application_party_discovery --> n_scoring["scoring"]

Public surface

`crate root`

Item	What it is
`pub struct PartyDiscoveryModule`	—
`PartyDiscoveryModule :: fn new() -> Self`	—
`PartyDiscoveryModule :: fn name(& self) -> & 'static str`	—
`PartyDiscoveryModule :: fn version(& self) -> & 'static str`	—
`PartyDiscoveryModule :: fn migrations(& self) -> Vec <MigrationSet>`	—
`PartyDiscoveryModule :: async fn migrate_pending(& self, pool : & PgPool) -> std::result::Result <u32, MigrationError>`	—
`PartyDiscoveryModule :: fn permission_codes(& self) -> Vec <String>`	—

`api`

Item	What it is
`fn admin_router <S>() -> Router <S> where S : Clone + Send + Sync + 'static, PgPool : FromRef <S>,`	Admin router

`api::discovery_admin`

Item	What it is
`pub const MAX_PAGE_SIZE: u32`	—
`pub const DEFAULT_PAGE_SIZE: u32`	—
`pub struct ListCandidatesQuery`	—
`pub struct TenantQuery`	—
`fn to_dto(c : & DiscoveryCandidate) -> DiscoveryCandidateDto`	Project a candidate onto the wire DTO.
`fn organization_from_candidate(c : & DiscoveryCandidate) -> Organization`	Build the Organization a candidate imports as — pure, unit-tested without a database.
`fn clamp_paging(page : Option <u32>, page_size : Option <u32>) ->(u32, u32)`	Clamp caller-supplied paging into a served range.
`fn page_offset(page : u32, page_size : u32) -> i64`	—
`fn router <S>() -> Router <S> where S : Clone + Send + Sync + 'static, PgPool : FromRef <S>,`	Discovery admin router

`dedup`

Item	What it is
`fn normalize_domain(website_or_domain : & str) -> Option <String>`	Lowercased registrable-ish domain (scheme/path/query stripped, `www.` prefix stripped) for a website URL or bare domain string
`fn find_suspected_duplicate(existing : & DiscoveryCandidate, place_id : & str, domain : Option <& str>,) -> Option <Uuid>`	Given a new candidate's `(place_id, domain)` and the tenant's existing candidates, return the id of an existing candidate this one is a probable duplicate of — or `None` if there's no strong match

`error`

Item	What it is
`pub enum DiscoveryError`	—

`models`

Item	What it is
`pub struct DiscoveryRun`	One Places-search invocation.
`DiscoveryRun :: fn new(tenant_id : Uuid, query_text : impl Into <String>) -> Self`	—
`pub enum CandidateStatus`	Entity-resolution status — Gate 1.5's precedence table (`docs/userstories/ sprint-3.69.1-party-discovery.md` §"Open questions" item 3): a candidate starts `Pending`; only a human reviewer moves it to `Imported` (`linked_organization_id` set), `Rejected`, or `Duplicate` (`duplicate_of_candidate_id` set) — the pipeline itself never auto-merges.
`CandidateStatus :: fn as_str(& self) -> & 'static str`	—
`CandidateStatus :: fn parse(s : & str) -> Self`	—
`pub struct DiscoveryCandidate`	A discovered business, staged for human review

`pipeline`

Item	What it is
`async fn discover(pool : & PgPool, tenant_id : Uuid, places_client : & GooglePlacesClient, contact_extractor : & ContactExtractor, domain_analyzer : & DomainIntelAnalyzer, http : & SafeHttpClient, request : & TextSearchRequest,) -> Result <Vec <DiscoveryCandidate>, DiscoveryError>`	Run one discovery: create a `discovery_run` row, call Places (billed — see the module doc), enrich each result (landing-page-only), and stage each as a `discovery_candidate` — applying Gate 1.5's entity-resolution precedence (exact Place ID = re-observation/upsert, same domain + different Place ID = flagged for human review, never auto-merged)

`repo`

Item	What it is
`async fn create_discovery_run(pool : & PgPool, run : & DiscoveryRun,) -> Result <DiscoveryRun, DiscoveryError>`	Insert a discovery run
`async fn find_discovery_run_for_tenant(pool : & PgPool, tenant_id : Uuid, id : Uuid,) -> Result <Option <DiscoveryRun>, DiscoveryError>`	Find a discovery run by id, tenant-scoped
`async fn list_candidates_for_run(pool : & PgPool, tenant_id : Uuid, discovery_run_id : Uuid,) -> Result <Vec <DiscoveryCandidate>, DiscoveryError>`	All (non-paginated — a discovery run's candidate count is bounded by `max_result_count` on the Places request, never open-ended) candidates for a run, tenant-scoped
`async fn find_candidates_by_domain_for_tenant(pool : & PgPool, tenant_id : Uuid, domain : & str,) -> Result <Vec <DiscoveryCandidate>, DiscoveryError>`	Candidates sharing `domain`, across ALL of the tenant's discovery runs — Gate 1.5's dedup concern spans runs ("re-discover the same business across multiple searches"), so the pipeline's duplicate check queries this instead of loading the whole tenant's candidate history into memory
`async fn upsert_candidate_for_tenant(pool : & PgPool, tenant_id : Uuid, candidate : & DiscoveryCandidate,) -> Result <DiscoveryCandidate, DiscoveryError>`	Insert a NEW candidate, or update the existing row if `(tenant_id, google_place_id)` already exists (Gate 1.5: an exact Place ID match is the SAME listing re-observed, not a new candidate — see `crate::dedup`'s module doc)
`async fn list_candidates_page_for_tenant(pool : & PgPool, tenant_id : Uuid, status : Option <CandidateStatus>, discovery_run_id : Option <Uuid>, limit : i64, offset : i64,) -> Result <(Vec <DiscoveryCandidate>, i64), DiscoveryError>`	One page of a tenant's candidates, optionally filtered by status and/or discovery run — "browsable with various options" (operator, sprint-3.69 item 4)
`async fn find_candidate_for_tenant(pool : & PgPool, tenant_id : Uuid, id : Uuid,) -> Result <Option <DiscoveryCandidate>, DiscoveryError>`	Find a candidate by id, tenant-scoped
`async fn mark_candidate_imported_for_tenant(pool : & PgPool, tenant_id : Uuid, id : Uuid, organization_id : Uuid,) -> Result <DiscoveryCandidate, DiscoveryError>`	Move a `Pending` candidate to `Imported`, linking the newly-created Organization
`async fn mark_candidate_rejected_for_tenant(pool : & PgPool, tenant_id : Uuid, id : Uuid,) -> Result <DiscoveryCandidate, DiscoveryError>`	Move a `Pending` candidate to `Rejected`
`async fn mark_candidate_duplicate_for_tenant(pool : & PgPool, tenant_id : Uuid, id : Uuid, duplicate_of_candidate_id : Uuid,) -> Result <DiscoveryCandidate, DiscoveryError>`	Move a `Pending` candidate to `Duplicate`, recording which existing candidate it duplicates

`scoring`

Item	What it is
`fn score_candidate(candidate : & DiscoveryCandidate) -> Option <EntityClassification>`	Score an already-staged candidate

Re-exports. Exported here, defined elsewhere.

Export	Defined in
`DiscoveryError`	`error::DiscoveryError`
`discover`	`pipeline::discover`
`{CandidateStatus,DiscoveryCandidate,DiscoveryRun}`	`models::{CandidateStatus,DiscoveryCandidate,DiscoveryRun}`

Boundary

Reaches into domain, foundation, identity, infrastructure, platform.

Shares tier application with 120 other crates: application-agreements, application-ai, application-analytics, application-approvals, application-assessments, application-audit-log, application-auth, application-billing, … (120 total).

_What this crate deliberately does NOT own is a judgment. No committed registry records one for it, so none is stated here._

Where it sits

Tier (ontology)	`application`
Architectural role (taxonomy)	`unclassified (baselined)`
Location	`crates/application/party-discovery`
Vocabulary in force (lexicon)	`current`

Tier flow. Which tiers this crate's own edges cross.

flowchart LR
  n_application["application"] --> n_domain["domain"]
  n_application["application"] --> n_foundation["foundation"]
  n_application["application"] --> n_identity["identity"]
  n_application["application"] --> n_infrastructure["infrastructure"]
  n_application["application"] --> n_platform["platform"]

Dependencies

Runtime, in this workspace.

Crate	Tier	Optional	Only on
`application-core`	application	no	always
`domain-competitive-intel`	domain	no	always
`domain-contact`	domain	no	always
`foundation-web-analysis`	foundation	no	always
`identity-parties`	identity	no	always
`infrastructure-adapters-google-places`	infrastructure	no	always
`infrastructure-fetcher`	infrastructure	no	always
`infrastructure-html-text`	infrastructure	no	always
`infrastructure-web-contact-extractor`	infrastructure	no	always
`infrastructure-web-domain-intel`	infrastructure	no	always
`platform-dto`	platform	no	always

Runtime, from outside the workspace.

Crate	Requirement	Features	Optional	Only on
`async-trait`	`^0.1`	—	no	always
`axum`	`^0.7`	`multipart`	no	always
`chrono`	`^0.4`	`serde`	no	always
`serde`	`^1`	`derive`	no	always
`serde_json`	`^1`	—	no	always
`sqlx`	`^0.8`	`runtime-tokio`, `postgres`, `chrono`, `uuid`, `json`	no	always
`thiserror`	`^2`	—	no	always
`tracing`	`^0.1`	—	no	always
`url`	`^2`	—	no	always
`uuid`	`^1`	`v4`, `v7`, `serde`, `js`	no	always

Development, in this workspace.

Crate	Tier	Optional	Only on
`application-engine`	application	no	always
`application-parties`	application	no	always

Development, from outside the workspace.

Crate	Requirement	Features	Optional	Only on
`tokio`	`^1`	`full`	no	always
`tower`	`^0.5`	—	no	always

Build. None.

Depended on by. Nothing in this workspace.

Signal flow — what reaches this crate, and what it reaches.

flowchart LR
  SELF["application-party-discovery"]
  SELF -->|development| n_application_engine["application-engine"]
  SELF -->|development| n_application_parties["application-parties"]
  SELF -->|runtime| n_application_core["application-core"]
  SELF -->|runtime| n_domain_competitive_intel["domain-competitive-intel"]
  SELF -->|runtime| n_domain_contact["domain-contact"]
  SELF -->|runtime| n_foundation_web_analysis["foundation-web-analysis"]
  SELF -->|runtime| n_identity_parties["identity-parties"]
  SELF -->|runtime| n_infrastructure_adapters_google_places["infrastructure-adapters-google-places"]
  SELF -->|runtime| n_infrastructure_fetcher["infrastructure-fetcher"]
  SELF -->|runtime| n_infrastructure_html_text["infrastructure-html-text"]
  SELF -->|runtime| n_infrastructure_web_contact_extractor["infrastructure-web-contact-extractor"]
  SELF -->|runtime| n_infrastructure_web_domain_intel["infrastructure-web-domain-intel"]
  SELF -->|runtime| n_platform_dto["platform-dto"]
  classDef self fill:#1f883d,stroke:#1f883d,color:#fff;
  class SELF self;

Feature flags

No Cargo features are defined: every capability is unconditional, so no consumer can receive a half-wired crate.

Targets

Kind	Name	Source
lib	`application_party_discovery`	`src/lib.rs`
test	`pg_forge_party_discovery`	`tests/pg_forge_party_discovery.rs`

Error model

Error type	Named by
`DiscoveryError`	`create_discovery_run`, `discover`, `find_candidate_for_tenant`, `find_candidates_by_domain_for_tenant`, `find_discovery_run_for_tenant`, `list_candidates_for_run`, … (11 total)

Operational characteristics

Property	Evidence
async public surface	yes
async runtime	none detected
database access	yes
network I/O	yes
unsafe code	none detected
environment variables	yes

No unsafe block, unsafe fn, unsafe impl or unsafe trait was found by the parser anywhere in this crate's source.

Configuration

Variable	Read in
`CARGO_PKG_VERSION`	`src/lib.rs`

No workspace crate depends on this one.

Verification

Kind	Count
Unit tests	18
Integration tests	6
Examples	0
Doctests	0

Evidence by module. How often each public module is named by something executable.

Module	Tests	Examples	Consumers
`crate root`	1	0	0
`api`	1	0	0
`api::discovery_admin`	9	0	0
`dedup`	2	0	0
`error`	1	0	0
`models`	3	0	0
`pipeline`	1	0	0
`repo`	10	0	0
`scoring`	1	0	0

What the tests establish, by name:

an_already_decided_candidate_cannot_be_decided_again — tests/pg_forge_party_discovery.rs
create_discovery_run_stores_the_query_and_location_bias — tests/pg_forge_party_discovery.rs
find_candidates_by_domain_scopes_to_the_tenant_and_domain — tests/pg_forge_party_discovery.rs
list_candidates_page_for_tenant_filters_by_status — tests/pg_forge_party_discovery.rs
mark_candidate_imported_sets_the_link_and_status — tests/pg_forge_party_discovery.rs
upsert_candidate_updates_in_place_on_the_same_place_id_not_a_new_row — tests/pg_forge_party_discovery.rs
caller_correctable_errors_still_name_the_problem — src/api/discovery_admin.rs
every_route_refuses_a_request_with_no_tenant — src/api/discovery_admin.rs
organization_from_candidate_carries_the_discovered_fields — src/api/discovery_admin.rs
paging_is_clamped_into_a_servable_range — src/api/discovery_admin.rs
the_paths_are_mounted — src/api/discovery_admin.rs
to_dto_nulls_blank_optional_columns — src/api/discovery_admin.rs
a_blank_website_normalizes_to_none — src/dedup.rs
accepts_a_bare_domain_with_no_scheme — src/dedup.rs
an_empty_existing_list_never_matches — src/dedup.rs
an_unparseable_string_normalizes_to_none — src/dedup.rs
no_domain_match_is_not_flagged — src/dedup.rs
same_domain_different_place_id_is_flagged — src/dedup.rs
same_place_id_is_never_flagged_as_a_duplicate_of_itself — src/dedup.rs
strips_scheme_path_and_www — src/dedup.rs
subdomains_are_preserved_only_www_is_stripped — src/dedup.rs
two_candidates_with_no_website_never_match_each_other — src/dedup.rs
malformed_stored_place_data_degrades_to_unscored_not_a_panic — src/scoring.rs
scores_a_candidate_from_its_stored_place_data — src/scoring.rs

Documentation coverage

Measure	Documented	Total
Public items with rustdoc	22	38
Public modules with a `//!` block	8	8

pie showData
    title Public items with rustdoc
    "Documented" : 22
    "No rustdoc detected" : 16

Metrics

Metric	Value
Rust source files	9
Source lines	1553
Code lines	1209
Public API items	38
Public modules	8
Tests	24
Examples	0
Cargo features	0
Direct runtime dependencies	21
Workspace reverse dependencies	0

pie showData
    title Public API by kind
    "constant" : 2
    "enum" : 2
    "function" : 20
    "method" : 9
    "struct" : 5

pie showData
    title Rust source composition
    "Code" : 1209
    "Blank or comment" : 344

Generation

Rendered by tools-corpus corpus readme from repository evidence alone, renderer schema 2, lexicon current. No model, network service or database was consulted. Regenerate with tools-corpus corpus readme --write; verify with --check.

What it is for

Capabilities

PartyDiscoveryModule

api (other)

api::discovery_admin (other)

ListCandidatesQuery

TenantQuery

dedup (other)

DiscoveryError

CandidateStatus

DiscoveryCandidate

DiscoveryRun

pipeline (other)

repo (other)

scoring (other)

How to use it

Module structure

Public surface

Boundary

Where it sits

Dependencies

Feature flags

Targets

Error model

Operational characteristics

Configuration

Related capabilities

Verification

Documentation coverage

Metrics

Generation

`PartyDiscoveryModule`

`api (other)`

`api::discovery_admin (other)`

`ListCandidatesQuery`

`TenantQuery`

`dedup (other)`

`DiscoveryError`

`CandidateStatus`

`DiscoveryCandidate`

`DiscoveryRun`

`pipeline (other)`

`repo (other)`

`scoring (other)`