Sail JADA — Engineering Log

Technical work on sailjada.com and the JADA booking systems

```html

Managing Multi-Environment Proposal Documents: A Case Study in S3-Backed Dynamic Content Workflow

What Was Done

During this development session, we identified and corrected payment term inconsistencies across multiple proposal documents stored in an S3-backed content management system. The work involved:

  • Detecting payment term mismatches between local development copies and production S3 objects
  • Fixing contradictory refund/deposit language in two related proposal templates
  • Synchronizing corrected versions back to S3 with proper content-type headers
  • Updating a centralized task dashboard to reflect completed corrections
  • Coordinating asset rendering and preview distribution for stakeholder review

Technical Details: Document Inconsistency Detection

The core issue emerged when comparing two versions of a proposal document:

  • /Users/cb/Documents/repos/sites/queenofsandiego.com/proposals/jada-charter-proposal-sue.html (local development)
  • s3://queenofsandiego.com/proposals/jada-charter-proposal-ewing.html (production)

A grep-based search revealed the payment term inconsistency:

grep -n "deposit\|payment\|refund\|weather\|500\|balance" /Users/cb/Documents/repos/sites/queenofsandiego.com/proposals/jada-charter-proposal-sue.html

This surface-level text search uncovered a critical semantic conflict: the proposal contained both "Deposit held in all cases" language alongside conditional weather-related refund clauses. This creates ambiguity for clients and introduces legal risk.

The S3 production object had drifted further, containing deprecated payment terms ("50% deposit" without corresponding balance language). This divergence likely occurred because proposals are manually edited during sales cycles without a formal version control integration between the local repository and S3.

Infrastructure: S3 Content Synchronization Pattern

The correction workflow leveraged a direct S3 copy approach:

aws s3 cp s3://queenofsandiego.com/proposals/jada-charter-proposal-ewing.html /tmp/ewing-proposal.html --content-type text/html

After local validation and correction:

aws s3 cp /tmp/ewing-proposal.html s3://queenofsandiego.com/proposals/jada-charter-proposal-ewing.html --content-type text/html

The explicit --content-type text/html flag is critical here. S3 does not automatically detect MIME types on upload; without this parameter, browsers may render the HTML as plaintext or trigger unexpected download behavior. This is especially important when proposals are shared via direct S3 links that may lack web server header inference.

Key Decisions and Patterns

Why Direct S3 Copy Instead of Versioned Releases?

The current workflow uses direct S3 copies for rapid proposal updates, optimizing for sales velocity over formal versioning. However, this introduces risk:

  • No audit trail: S3 object versioning was not enabled, so prior versions are lost after overwrite
  • No rollback mechanism: If a corrected proposal introduces new errors, recovery requires manual restoration from local backups
  • Deployment-to-source drift: The local repository and S3 bucket become out-of-sync over time as sales teams manually edit documents directly in S3 or via different tools

Recommendation for next iteration: Enable S3 versioning on the proposals bucket and implement a Git-based source-of-truth workflow where proposals are committed to the repository, validated via CI/CD, and deployed to S3 via infrastructure-as-code tools (e.g., Terraform or CDK).

Why Grep Over Structured Parsing?

The initial detection used regex patterns rather than HTML parsing. This is a pragmatic but fragile approach:

grep -n "deposit\|payment\|refund\|weather" proposal.html

Strengths: Fast, works across any text content, requires no dependencies.

Weaknesses: Cannot detect semantic contradictions, misses comments or metadata, and produces false positives (e.g., matching "weather" in unrelated sections).

For production workflows, a better approach would parse the HTML DOM and check for conflicting statements using a structured rules engine or even LLM-based semantic analysis.

Dashboard Integration and State Management

After corrections were deployed, the centralized task dashboard was updated via a Python tool:

python3 /Users/cb/Documents/repos/tools/update_dashboard.py add-note t-f20bc5a4 --text "Payment terms fixed on both proposals. Sue and Ewing versions now consistent: 50% deposit + 50% balance."

This tool writes to a backend API that synchronizes state across the team's progress tracking system (hosted at https://progress.queenofsandiego.com/state.json). The dashboard maintains a single source of truth for task status, avoiding email chains and spreadsheet fragmentation.

The task reference t-f20bc5a4 is a unique identifier linked to a specific sales opportunity. This allows correlating proposal edits with CRM records and email blasts.

Preview Rendering and Asset Distribution

A secondary requirement involved rendering a Bob Dylan event email template for stakeholder review:

aws s3 cp /Users/cb/Documents/repos/sites/queenofsandiego.com/rady-shell-events/sites/bobdylan/index.html s3://queenofsandiego.com/preview/bobdylan-email-blast.html --content-type text/html

By uploading to a dedicated /preview/ prefix in S3 and relying on CloudFront caching, the email template becomes accessible via a shareable browser URL without requiring local build tools or email client rendering (which can be inconsistent).

The dashboard was updated with the preview link:

python3 /Users/cb/Documents/repos/tools/update_dashboard.py add-note t-cmo-blast --text "Preview is now live in your browser at https://queenofsandiego.com/preview/bobdylan-email-blast.html"

What's Next

  • Implement S3 versioning: Enable VersioningConfiguration on the proposals bucket to retain audit history
  • Establish CI/CD validation: Add HTML validation and payment term consistency checks to the deployment pipeline before S3 sync
  • Unify content authoring: Move away from manual S3 edits toward a single Git-based repository with automated deployments
  • Monitor divergence: Add periodic checks comparing local and S3 versions to catch drift early
  • Structured proposal format: Consider transitioning from HTML to a data-driven format (JSON-LD or structured YAML) with template-based rendering, enabling stronger validation

For Sergio and the engineering team: This pattern is common in early-stage sales-driven systems where velocity trumps formal process. As proposals grow in complexity and volume, the manual synchronization approach becomes unsustainable. The next iteration should treat proposals as versioned artifacts with immutable deployment records.