wyndham-ARR/.project-docs/20-architecture/module-map.md

Module Map

Path	Responsibility	Notes
arr_web/auth.py	Login credential verification and bounded attempt ledger	Environment-owned single-operator identity; dependency-free constant-time comparison; no secret logging
arr_web/programmatic.py	Upload-to-terminal coordinator	Registers the validated browser basename separately from canonical source.xml; no remote/model transport
arr_web/booking_uploads.py, booking_ingestion/excel.py	Authenticated Booking source upload and bounded raw XLSX parsing	Parser 2.0 reads Tour Code plus exact โรงแรม, latest-row cancellations and extracted room items with review state; coordinator/backend route contracts target drafts
booking_ingestion/excel_postgres.py	Earlier direct Booking full-source import/activation path	Its one-item immediate-accept implementation does not represent parser 2.0 review and must not be treated as the completed review repository
booking_ingestion/excel_review.py, booking_ingestion/excel_review_postgres.py	Editable extraction drafts and atomic reviewed-source activation	Single-operator repository uses advisory locking and a zero-pending gate; real PostgreSQL transaction/rollback acceptance passes; actor/reason/revision history is not implemented
arr_web/processing_runtime.py	PostgreSQL + OSS + processor composition	Active production processing composition
arr_processing/local.py	Bounded subprocess and output manifest extraction	Never exposes stdout/stderr
arr_processing/policy.py	Frozen processor/rule identity	Neutral, reusable loader
arr_ingestion/validation.py	Strict artifact/result validation	Runs validate_daily.py on success
arr_ingestion/postgres.py	Atomic Finance commit and lifecycle state	Four retries only for transient SQLSTATEs
arr_storage/aliyun_oss_v2.py	Encrypted/unversioned OSS adapter	Writes all objects private
arr_web/downloads.py	OSS daily + controlled local report download routing	Rechecks metadata, size and SHA-256
arr_web/job_trace.py	Programmatic persisted-fact trace	No external trace store
arr_web/app.py, arr_web/repository.py, arr_web/company_jobs.py	Authenticated portal routes plus public H5 aggregate routes, paged history reads and read-only history-month discovery	Default-deny login gate protects the desktop/API/download surface; purpose-built /api/public/h5/* exposes only sanitized aggregate metrics; daily/monthly counts and rows share a repeatable-read snapshot; /api/history-months merges daily/monthly database counts with company job-state counts; company totals/slices share one lock
arr_web/server.py	Standard-library HTTP transport	Dispatches GET/POST/PATCH/DELETE with one bounded body reader; real socket tests cover review update/delete and missing/oversized lengths
arr_web/static/login.html, login.css, login.js	Responsive ARR login gateway	Labeled form, password visibility, generic inline failures, safe desktop/H5 return target and reduced-motion support
arr_web/static/app.js, arr_web/static/h5.js	Authenticated desktop and anonymous-capable H5 client state, rendering and polling	Desktop daily/monthly/company histories own independent viewing-month state and default to the latest non-empty month; company generation month remains separate. H5 reads only public aggregate endpoints and may retain optional logout for an authenticated session. Desktop also includes 50-row Booking draft review/edit, the draft's validated uploaded filename below the review title, individual/all-visible selection, count-aware in-page delete confirmation and activation; company generation keeps the fixed five-company context beside the page title, a four-card upload/period setup row, cumulative CO display labels, short centered period actions and an in-page generation confirmation dialog; session-expiry redirect and CSRF logout remain shared; monthly versions auto-refresh the selected viewing month every four seconds
monthly_reports/worker.py	Dedicated outbox consumer	Lease/reclaim, retry/dead-letter, success acknowledgement after activation
monthly_reports/repository.py	Monthly snapshot and publication repository	Derives scope from ARRIVAL; persists metadata/lineage/artifact identities
monthly_reports/xlsx/build_workbook.mjs	Monthly XLSX builder and reopen validator	Exact row-relative TOTAL PRICE formulas only in column S
monthly_reports/, company_reports/, channel_analytics/	Downstream reports/BI	Consume accepted Finance facts
database/012_monthly_report_publication.sql	Additive metadata-only publication schema	Applied after immutable 008–011 baseline
database/014_booking_current_source_batch.sql	Booking full-workbook current-source pointer and view scoping	Formally applied on 2026-07-31; batch 1 remains selected
database/015_booking_excel_review_drafts.sql	Item-level Booking extraction draft state	Formally applied and empty; basic latest-state review only, with no actor/reason/revision history and no DB-enforced zero-pending activation
compose.yaml, deploy/	Web-login + Caddy-HTTPS template and worker deployment boundary	Requires Web credentials for the desktop/operational surface; public H5 aggregate routes and /healthz remain anonymously reachable; no MCP port/domain/service
tests/test_arr_programmatic.py	Real success/failure vertical slices	Primary ARR2.0 acceptance proof

Historical ARR1 compatibility modules and migrations remain for audit/tests but are not imported, installed or deployed by the active ARR2.0 entrypoint.

Last Updated

2026-08-02