Repository Docs & Knowledge Base

Consolidated Spensara documentation repository (722 Markdown & architecture documents in ../repository)

Built Word Documents (.docx): Spensara Overview (.docx) Capability Assessment (.docx) Brink POS Ingestion Analysis (.docx) The Borg Ingestion Architecture (.docx)

Branches (328)

Branch-specific documentation across extract-raw-xml, feature-fleet-import, kds_cdc_improvments, life-cycle, and tenat-admin.

branches/life-cycle/etl/docs/features/ETL/epics/06-source-adapter-brink-pos-api/poc-checklist.md 4,891 bytes · Updated Oct 23, 2026 10:44 AM EDT

Raw File

Brink POS API PoC Checklist

Purpose

Track the minimum implementation work needed to prove the Brink POS API pull PoC end to end.

Completion Criteria

The PoC is complete when one tenant-location can be pulled from Brink, raw payloads are preserved, the agreed staging subset is loaded, and the first curated tables are populated without advancing checkpoints on failure.

Checklist

1. Foundation and configuration

[ ] Confirm one tenant can be mapped to one Brink location and endpoint stack.
[ ] Decide the Brink adapter implementation approach for the PoC:
generated SOAP clients, or
thin hand-written SOAP client
[ ] Define the minimum Brink configuration set:
server base
AccessToken
LocationToken
tenant/location identifier
enabled streams
[ ] Ensure secrets are not written to logs or raw payload metadata.

2. Raw pull proof

[ ] Prove Sales2.GetOrders can be called successfully.
[ ] Prove Kitchen.GetOrderBumpTimes can be called successfully.
[ ] Prove Kitchen.GetOrderItemBumpTimes can be called successfully.
[ ] Prove Settings2.GetLastModifiedTime can be called successfully.
[ ] Prove at least the required settings lookup calls can be called successfully:
items
modifier groups
destinations
taxes
tenders
employees
kitchen queues

3. Raw payload capture

[ ] Save raw SOAP responses to S3 under the tenant/source prefix.
[ ] Record the main raw S3 path on IngestionBatch when practical.
[ ] Ensure failed pulls still preserve the raw payload or error artifact.

4. Metadata and checkpointing

[ ] Reuse existing IngestionBatch for Brink stream runs.
[ ] Reuse existing IngestionCheckpoint for Brink watermarks.
[ ] Implement checkpoint keys for the PoC:
location:{location_key}:orders:modified-time
location:{location_key}:order-bumps:bump-time
location:{location_key}:item-bumps:bump-time
location:{location_key}:settings:last-modified
[ ] Ensure checkpoints advance only after successful end-to-end completion.
[ ] Ensure failed runs do not advance checkpoints.

5. Structured logging

[ ] Log one structured event per Brink call with:
tenant_id
batch_id
source_type
service_name
operation_name
endpoint_url
request_window_start
request_window_end
result_code
status
raw_response_s3_path
[ ] Verify logs are sufficient to diagnose a failed call without inspecting code.

6. Staging schema

[ ] Add the Brink staging bootstrap location under tenant SQL bootstrap.
[ ] Create PoC staging tables:
staging.brink_orders
staging.brink_order_entries
staging.brink_order_entry_modifiers
staging.brink_order_taxes
staging.brink_order_entry_taxes
staging.brink_order_payments
staging.brink_order_payment_details
staging.brink_items
staging.brink_modifier_groups
staging.brink_modifier_group_items
staging.brink_destinations
staging.brink_tables
staging.brink_kitchen_queues
staging.brink_taxes
staging.brink_tenders
staging.brink_employees
staging.brink_order_bump_times
staging.brink_order_item_bump_times
[ ] Ensure each staging table preserves ETL metadata columns:
_etl_batch_id
_etl_source_type
_etl_ingested_at

7. Source-to-staging normalization

[ ] Map GetOrders responses into Brink order staging tables.
[ ] Map settings responses into Brink lookup staging tables.
[ ] Map kitchen bump responses into Brink kitchen staging tables.
[ ] Preserve stable join keys between orders, entries, payments, and bump events.

8. Curated publication

[ ] Implement curated mapping for the first agreed supported tables:
curated.kitchen_item_status_events
curated.kitchen_order_items
curated.kitchen_orders
curated.pos_transaction_items
curated.pos_transactions
curated.pos_transaction_tenders
curated.pos_tables
curated.pos_tenders
curated.pos_catalog_items
curated.pos_modifiers
[ ] Keep optional curated targets out unless mapping stays simple:
curated.pos_orders
curated.pos_order_items
curated.pos_menu_items

9. Failure behavior

[ ] Confirm transport failures mark the batch failed.
[ ] Confirm Brink business failures (ResultCode != 0) mark the batch failed.
[ ] Confirm failed runs do not publish partial curated state as successful output.
[ ] Confirm failed runs do not advance checkpoints.

10. Exit review

[ ] Validate that one tenant-location can run end to end.
[ ] Validate that raw S3 capture, batch metadata, and checkpoints are all visible.
[ ] Validate that the first curated outputs are queryable.
[ ] Document known gaps that remain intentionally out of PoC scope.