# Part Beacon — Data Model

## Brand architecture

**Part Beacon** is the parent service: a global parts aggregator and sourcing-intelligence platform. Helicopter/aviation parts remain the first vertical and proof market, but the brand is deliberately broad enough for industrial, marine, electronics, equipment, automotive, and other hard-to-find parts categories.


## 1. Wanted alert

```json
{
  "id": "wanted-20260506-001",
  "created_at": "ISO-8601",
  "part": "206-010-200",
  "model": "Bell 206",
  "component_family": "main rotor blade | gearbox | engine | avionics | core | unknown",
  "name": "company/contact",
  "contact": "email or phone",
  "urgency": "AOG / urgent | 30 days | 90 days | Opportunistic",
  "notify": "Email | SMS/call | Weekly digest",
  "notes": "free text",
  "ocr_text": "optional extracted text",
  "photo_ref": "private file reference",
  "extracted_tokens": ["206-010-200", "BELL 206"],
  "consent": true,
  "review_status": "new",
  "source": "partsace.acedata.ca wanted-parts alerts",
  "ip_hash": "privacy-preserving hash",
  "user_agent": "request UA"
}
```

## 2. Photo/OCR intake

```json
{
  "created_at": "ISO-8601",
  "id": "photo-20260506-001",
  "photo_ref": "private part-photos/file",
  "mime": "image/png",
  "original_name": "uploaded filename",
  "part": "user-entered or OCR-supported part clue",
  "model": "aircraft/model clue",
  "urgency": "urgency bucket",
  "contact": "contact clue",
  "notes": "user notes",
  "ocr_text": "raw OCR text",
  "extracted_tokens": ["normalized part/model/serial candidates"],
  "review_status": "new",
  "source": "partsace.acedata.ca part-photo OCR intake"
}
```

## 3. Supplier/source registry record

```json
{
  "id": "supplier-domain-example-com",
  "created_at": "ISO-8601",
  "last_seen_at": "ISO-8601",
  "domain": "example.com",
  "source_url_private": "private-only URL",
  "public_name": "source-safe supplier summary",
  "language": "de",
  "country_or_region": "Germany",
  "source_type": "supplier | broker | auction | dismantler | marketplace | directory | mro",
  "helicopter_relevance": ["Bell 206", "Robinson R44"],
  "inventory_categories": ["engine", "rotor blade", "gearbox", "avionics"],
  "credibility_score": 0.0,
  "credibility_notes": "why this source looks credible or risky",
  "public_safe": false,
  "review_status": "new"
}
```

## 4. Translated listing record

```json
{
  "id": "listing-20260506-001",
  "supplier_id": "supplier-domain-example-com",
  "source_language": "fr",
  "title_original": "Pièces d'hélicoptère Bell 206",
  "description_original": "raw source text excerpt",
  "title_en": "Bell 206 hard-to-find parts",
  "description_en": "English translation for internal/public-safe review",
  "aircraft_model": "Bell 206",
  "part_number": "unknown or extracted",
  "component_family": "engine | blade | gearbox | avionics | airframe | other",
  "price": {
    "amount": 50000,
    "currency": "EUR",
    "usd_estimate": 53700
  },
  "location": "France",
  "source_url_private": "private-only URL",
  "public_summary": "source-safe English listing summary",
  "public_safe": true,
  "verification_risk": "high | medium | low",
  "notes_private": "source-linked review notes"
}
```

## 5. Inventory listing

```json
{
  "Make": "Bell",
  "Model": "Bell 206 Allison 250 C18B Short Engine",
  "Inventory Type": "Aircraft | Part/Component",
  "Category": "Category A | Category B",
  "USD Price": 64995,
  "AUD Equivalent": 90487,
  "Location": "England, United Kingdom",
  "TTSN": "Component time not verified",
  "Verification Risk": "High verification",
  "Estimated Gross Arbitrage USD": null,
  "Arbitrage Label": "Parts spread TBD",
  "Notes": "review-safe notes",
  "Source": "private-only URL"
}
```

## 6. Match candidate

```json
{
  "id": "match-20260506-001",
  "wanted_id": "wanted-20260506-001",
  "listing_id": "listing-20260506-001",
  "supplier_id": "supplier-domain-example-com",
  "score": 85,
  "reasons": ["exact part token", "platform match", "credible supplier"],
  "risk_flags": ["documentation not verified"],
  "review_status": "candidate_match",
  "next_action": "human review required",
  "created_at": "ISO-8601",
  "updated_at": "ISO-8601"
}
```

## 7. RFQ packet

```json
{
  "id": "rfq-20260506-001",
  "match_id": "match-20260506-001",
  "status": "draft_only",
  "recipient_private": "supplier email or form URL",
  "subject": "RFQ: Bell 206 part 206-010-200",
  "body_draft": "approval-gated message body",
  "attachments_private": ["photo ref", "OCR excerpt"],
  "approval_required": true,
  "approved_by_simon_at": null,
  "sent_at": null
}
```

## 8. Public vs private fields

Public output may include:

- `title_en`;
- `description_en` if source-safe;
- aircraft/model;
- component family;
- general location;
- price/value estimate;
- public summary;
- verification risk.

Public output must exclude:

- `source_url_private`;
- seller contact details;
- buyer contact details;
- private notes;
- photo refs;
- RFQ recipient;
- raw source-linked notes.


## 9. Subscription signup

```json
{
  "created_at": "ISO-8601",
  "id": "sub-20260506-001",
  "plan": "Free weekly inventory list | Daily inventory subscription | Part sourcing subscription",
  "name": "company/contact",
  "contact": "email or phone",
  "payment_preference": "Canadian dollars | Bitcoin | Decide later",
  "notes": "watched aircraft/parts/regions",
  "launch_offer": "three_months_free",
  "billing_status": "free_trial_no_payment_due",
  "currency_options": ["CAD", "BTC"],
  "selected_btc_address_last4": "4zsg",
  "selected_btc_address_private": "private/account-gated full BTC destination",
  "source": "partsace.acedata.ca subscription signup",
  "ip_hash": "privacy-preserving hash",
  "user_agent": "request UA"
}
```

Public pages may mention that CAD and Bitcoin are supported, but must not publish full BTC destination details.

## Photo-to-watchlist functionality

Part Beacon supports a core workflow: user uploads a photo of a part, tag, plate, box, invoice, or component card; browser OCR extracts likely part/model/serial tokens; the user confirms or edits the extracted text; then the record is stored as a private watched-parts item. The OCR result is an identification aid only and must not be treated as verified part identity, certification, condition, or airworthiness.

Backend records are split into:
- private photo/OCR intake for the uploaded image and extracted tokens;
- private wanted-parts/watchlist record for monitoring and future match notification.