01 — Quick Reference

Group Models
Declarations CustomsDeclaration · DeclarationItem · CustomsDocument · CustomsTransmission · DeclarationAmendment
Decisions & Holds CustomsDecision · RegulatoryHold
Current Clearance ClearanceAssessment · CustomsClearanceCheck · CustomsException
Audit CustomsAudit
Profiles & Sources CustomsAuthority · ClearanceProfile · BrokerMandate · CustomsExternalSnapshot

Every model (15) — one line each

Model It records Key foreign keys
CustomsAuthority A customs authority (fictional) —
ClearanceProfile A movement type (IMPORT / EXPORT / TRANSIT / COASTAL), its mode (SIMULATION / LIVE), checks and validity CustomsAuthority
BrokerMandate A broker's mandate for a customer with the authority CustomsAuthority
CustomsDeclaration One declaration revision; the submitted revision is immutable ClearanceProfile, BrokerMandate, itself (previous)
DeclarationItem An item with its customs HS code (separate from the commercial class) CustomsDeclaration
CustomsDocument A supporting document with its content hash CustomsDeclaration
CustomsTransmission One send attempt; SIMULATED_SENT is transport success, not acceptance CustomsDeclaration
CustomsDecision An official result: recorded, verified by someone else, or quarantined CustomsDeclaration (optional)
RegulatoryHold A hold on a consignment, line or container scope; lifted only by the matching verified lift CustomsDeclaration, CustomsDecision (source, lift)
ClearanceAssessment The standing position of a scope at a manifest revision; versioned, immutable CustomsDeclaration, CustomsDecision
CustomsClearanceCheck The answer to one customs.check_clearance; append-only ClearanceAssessment
DeclarationAmendment A request, approval and application of an amendment (a new linked version) CustomsDeclaration (original, replacement)
CustomsException A control exception: clearance invalidated, refused check, rejected declaration, quarantined result CustomsDeclaration, RegulatoryHold
CustomsAudit Who did what, append-only CustomsDeclaration, RegulatoryHold
CustomsExternalSnapshot What other applications told us (effective cargo, issued documents): versioned, hashed —

Vocabularies

  • CustomsDeclaration.status: DRAFT · VALIDATED · APPROVED · SUBMITTED · ACCEPTED · REJECTED · CLEARED · HELD · SUPERSEDED (the pack's workflows.yaml)
  • RegulatoryHold.status: ACTIVE · LIFTED (the pack's workflows.yaml)
  • movement_type: IMPORT · EXPORT · TRANSIT · COASTAL; mode: SIMULATION · LIVE
  • CustomsDecision.decision_type: ACCEPTANCE · REJECTION · CLEARANCE · HOLD · REVOCATION · LIFT; status RECEIVED · VERIFIED · QUARANTINED · SUPERSEDED
  • ClearanceAssessment.outcome: CLEARED · NOT_REQUIRED · HELD · PENDING · UNKNOWN · STALE · REVOKED · REJECTED; requirement REQUIRED · NOT_REQUIRED · UNDETERMINED; status CURRENT · SUPERSEDED
  • CustomsTransmission.status: QUEUED · SIMULATED_SENT · FAILED · UNKNOWN_OUTCOME · RECONCILED

Messages (network member)
Commands accepted customs.check_clearance (from coast_10_release, orchestrator) · customs.simulate_decision (orchestrator, SIMULATION test harness) · customs.sweep_expired (orchestrator, scheduled)
Events published customs.clearance_changed (every new CURRENT assessment version) · customs.hold_changed (ACTIVE, LIFTED) · customs.clearance_checked (the answer to a check, key = check_idempotency_key) · customs.exception_raised · customs.exception_resolved
Events consumed manifest.effective_cargo · release.document_issued · assurance.action_requested

Run, seed, regenerate

python server/run.py coast_12_customs                    # http://localhost:5196
python -m codegen.cli all coast_12_customs               # regenerate models, controllers and JSON after a schema change
python -m codegen.cli seed coast_12_customs --reset      # reload the sample data
python -m codegen.cli integration coast_12_customs       # regenerate the integration package (handlers.py is never overwritten)
python scripts/build_diagram_viewer.py coast_12_customs  # rebuild the interactive diagram