Carisam · Sprint Closeout · Source documents
Back to closeout page

DOCUMENT 06

Technical brief (for an engineer)

Written for an engineer to read. Not for Lance.

CARISAM Technical Brief for Steve Dakh

Context

CARISAM Caribbean Sourcing is a relationship-driven construction materials sourcing and export business serving Caribbean projects.

The business works because Lance has deep vendor knowledge, product judgment, shipping experience, and customer trust. The problem was that the workflow was trapped across email, text, WhatsApp, PDFs, spreadsheets, memory, phone calls, and informal notes.

The first sprint identified quote turnaround as the highest-value workflow and shipped a live working app for it inside the contracted window.

What is already live

Fast Quote Lane — https://carisam-quote-lane.skippi.ai/

A real authenticated web application, in production today. Stack:

- Backend: Python stdlib HTTP server + SQLite. Single-file server.py (~700 lines). Threaded request handler. Bound to 127.0.0.1:8788. - Storage: SQLite at /var/lib/carisam-quote-lane/data.db. WAL mode, foreign keys on. 7 tables (customers, vendors, quotes, quote_items, rfqs, vendor_responses, vendor_response_items). - Auth: Shared password for Lance and Jim, HMAC-SHA256 signed cookie session (30-day TTL). Vendors use unguessable per-RFQ tokens (secrets.token_urlsafe(24)) — no account needed. - Frontend: Single-file SPA, vanilla JS, hash routing, brand-matched (Newsreader + Inter Tight + JetBrains Mono). - Vendor response page: Server-rendered HTML (not SPA) for zero-friction mobile vendor experience. - Deployment: systemd DynamicUser=yes + StateDirectory=carisam-quote-lane + full hardening (NoNewPrivileges, ProtectSystem=strict, MemoryDenyWriteExecute, RestrictAddressFamilies=AF_INET AF_INET6). nginx proxy for /api/ and /vendor/. Let's Encrypt TLS auto-renewed.

What it does today:

  1. Internal quote intake (inline customer create).
  2. Line-item entry.
  3. Supplier RFQ creation with per-vendor unique token.
  4. Server-rendered vendor response form, no account.
  5. Side-by-side comparison view across responses.
  6. Decision capture (margin %, customer sell total, decision notes).
  7. Pro-forma CSV export with sell prices computed from vendor totals × margin.

Source: web-projects/carisam-quote-lane-service/server.py and web-projects/carisam-quote-lane/index.html.

Phase 2 — what we want Steve to lead

The app is in production but Phase 2 turns it from quote-side coverage into the durable order-to-closeout operating system, with the integrations and hardening that come from a senior engineering eye.

Phase 2 features (priority order)

  1. Customer quote output — branded PDF. Polished pro-forma PDF in CARISAM's existing layout, with letterhead and terms.
  2. Order conversion. Accepted quotes become order records with customer PO, vendor PO, deposit, balance due, vendor payment status, production status, shipping path, booking number, closeout.
  3. Email integration. Outbound RFQ email send (SMTP via Postmark/Resend); inbound reply capture attached to RFQ.
  4. PDF / email extraction. Parse vendor PDF quotes and unstructured email replies into the comparison form, with confidence scoring and human review.
  5. Multi-user + audit. Replace shared password with per-user auth. Audit log on every quote.

Architecture questions for Steve

  1. Stay on the current stack? Python stdlib + SQLite + Hetzner has shipped fast and works well at single-user-pair scale. As Jim and Lance both work the system, and as orders, payments, shipping attach — do we stay on this stack, or move pieces to managed services?
  2. Email service. Postmark vs Resend vs roll-our-own SMTP. Inbound reply parsing approach.
  3. PDF generation. WeasyPrint (Python) vs headless Chromium (Playwright) vs external API. Need to match CARISAM's exact pro-forma layout pixel-for-pixel.
  4. Per-user auth. Roll our own with the existing HMAC session approach, or use Clerk / Auth0 / Lucia for Phase 2.
  5. Backup / DR. SQLite backup cadence and offsite. The DB is the system of record.
  6. Monitoring. Uptime, error alerting, slow-query detection.
  7. PDF / email extraction stack. Self-hosted (e.g. Marker, MinerU) vs API (e.g. Reducto, LlamaParse, GPT-4o). The data is sensitive (customer pricing, vendor margins), so API choice matters.

Risks to manage in Phase 2

  1. Overbuilding before real CARISAM workload proves the data model. Two weeks of Lance + Jim usage first.
  2. Treating PDF / email extraction as authoritative without human review.
  3. Email integration creating a parallel inbox that diverges from Lance's existing mailbox.
  4. Authentication friction for Lance and Jim. Whatever replaces the shared password should be at least as fast to use.
  5. Adding steps that slow Lance down. Every Phase 2 feature should make the workflow shorter, not longer.

What Brandon needs from Steve

  1. Phase 2 architecture review and stack decisions on the seven questions above.
  2. Engineering rigor on the existing app — security review, performance check, error handling holes.
  3. Build estimate for Phase 2 features so we can scope a fixed-fee proposal for Lance.
  4. Recommendation on what to harden first vs. what to build next.
  5. Pair on the customer-quote PDF since that's the most visible Phase 2 deliverable.

Repo / handoff

- Backend: web-projects/carisam-quote-lane-service/server.py - systemd unit: web-projects/carisam-quote-lane-service/carisam-quote-lane.service - Frontend SPA: web-projects/carisam-quote-lane/index.html - Live host: root@37.27.218.20 (Hetzner). Service: carisam-quote-lane.service. State dir: /var/lib/carisam-quote-lane/. - Sprint package and proposal: Projects/carisam-claude-code-package-2026-05-14_1755/