Skip to content

domain-model.md

Latest commit

 

History

History
100 lines (75 loc) · 2.35 KB

domain-model.md

File metadata and controls

100 lines (75 loc) · 2.35 KB

Domain Model

Core Entities

Reference Data

  • commodities
  • commodity_perishability_profiles

Commercial Actors

  • organizations
  • users
  • sellers
  • buyers
  • destinations
  • collection_points

Operational Inputs

  • lots
  • lot_events
  • buyer_bids
  • vehicles
  • vehicle_capacity_blocks
  • routes
  • route_snapshots
  • weather_snapshots
  • congestion_snapshots

Decision Trace

  • allocation_runs
  • allocation_decisions
  • decision_candidate_scores
  • reassignment_events
  • audit_logs

Key Relationships

  • One commodity can have many commodity_perishability_profiles.
  • One seller can declare many lots.
  • One buyer can own many destinations and many buyer_bids.
  • One destination can receive many bids and many congestion snapshots.
  • One lot participates in many candidate scores and may have zero or more reassignment events.
  • One allocation_run owns many candidate scores and many final decisions.

Important Modeling Choices

India-first geography

Each operational record carries India-relevant location fields:

  • state
  • district
  • tehsil or taluk when available
  • pin_code
  • latitude
  • longitude

This allows operation without a hard dependency on external GIS providers.

Trade units

  • quantity is normalized to kilograms internally,
  • prices are modeled in INR with explicit decimal precision,
  • reporting can render quintals or tonnes as needed.

Time

  • store timestamps in UTC,
  • render operator views in IST,
  • retain bid and unloading windows explicitly,
  • record freshness hard stops separately from soft viability thresholds.

Explainability

decision_candidate_scores is not an optional debug table. It is part of the product. It preserves:

  • candidates considered,
  • score components,
  • feasibility failures,
  • why a higher nominal bid lost,
  • what the winning margin was.

Minimal ER View

organizations -> users
organizations -> sellers -> lots -> lot_events
organizations -> buyers -> destinations
commodities -> commodity_perishability_profiles
buyers -> buyer_bids -> destinations
vehicles -> vehicle_capacity_blocks
routes -> route_snapshots
destinations -> congestion_snapshots
lots + buyer_bids + routes -> decision_candidate_scores -> allocation_decisions
allocation_decisions -> reassignment_events
all allocation-changing entities -> audit_logs