Supporting Reference 5: Data Contracts

This page defines the configuration, JSON state, and schema contracts the automation depends on. Treat these contracts as production interfaces, not optional metadata.

Back to Step 0 Back to reference 4 Next reference: File reference

R5.1 Primary config contract: `amir2000_config.py`

Runtime behavior is driven by Python config blocks and environment overrides. There is no YAML source-of-truth layer.

PATHS - local staging, incoming, archive, and website-root mappings.
PUBLISH - remote base path, public URL base, table names, and publish options.
MYSQL / FTP_CONFIG - connectivity and credential contract for publish.
OLLAMA - local model endpoint, selected model, retries/timeouts.
WEBSITE_V2 - mapping to website storage roots and URL behavior.

R5.2 JSON state files in `data/`

File	Type	Contract role
`folder_map.json`	object	Folder key to display/title mapping contract.
`location_list.json`	array[string]	Location suggestion source for UI and normalization.
`autofix_dict.json`	object	Token correction map used in text cleanup.
`spellcheck_exceptions.json`	array[string]	Domain-specific allowlist to reduce false fixes.
`new_taxonomy_log.json`	array[object]	Append-style record of taxonomy additions.
`used_filenames.json`	array[string]	Global filename reservation ledger.
`ui_state.json`	object	UI/editor state persistence (layout and session context).
`prefill_qc_last.json`	object	Last prefill QC summary and flagged row identifiers.

R5.3 SQL schema contract sources

docs/review_queue.sql and data/init/review_queue.sql - queue schema contract.
docs/photos_info_revamp.sql and data/init/photos_info_revamp.sql - publish mirror schema contract.
data/init/*.sql is the bootstrap source used by init_db.py.

R5.4 Contract integrity rules

Treat used_filenames.json as critical state, not disposable cache.
Keep schema files and runtime code synchronized when adding/removing fields.
Preserve compatibility across staging, review, and uploader consumers for each field.
Avoid editing config/JSON contracts in ways that break published naming continuity.

R5.5 Change control checklist

Define contract change and impacted modules.
Update config/JSON/SQL source files consistently.
Run DB bootstrap and small end-to-end validation batch.
Confirm publish behavior and mirror sync are unaffected.
Update related documentation pages (Step 4 and Step 5 when relevant).

R5.6 Continuation path

Next reference: File reference Back to reference 4 Back to Step 0