PetraOS

The handoff is the hard part

Selling fuel is not one transaction in one screen. A commercial request moves between sales, customer qualification, contracts, finance, and logistics before an autotanque reaches its destination. Each team needs a different view of the same operation—and a clear reason to advance it or hold it.

PetraOS is the platform I built and recently deployed for PetroMex. I worked directly with the organization to understand its standard operating procedures and translate those handoffs into software. The intended users are commercial and operations staff, with separate customer and review surfaces.

The problem was not a missing dashboard. It was keeping a deal, its correspondence, approvals, documents, and delivery records connected as responsibility changed hands.

My contribution: discovery through deployment

As Technology Consultant & Product Builder, I own the translation from operating requirements into the product: direct SOP discovery, workflow and interface design, AI-assisted implementation, and deployment coordination. I use AI development tools throughout the build; this case study does not present their output as unaided engineering work.

PetroMex supplies the operating knowledge and business decisions. My role is to make those rules explicit, connect the relevant records, and expose exceptions in a form an operator can act on. A software check supports that responsibility; it does not replace the person approving the transaction.

One deal, eleven recorded stages

The implemented pipeline records inquiry, quotation, acceptance, qualification, contract preparation, signature, countersignature, invoicing, payment, fulfillment, and completion. Its source states are:

INQUIRY → QUOTED → ACCEPTED → QUALIFIED → CONTRACTED → SIGNED → COUNTERSIGNED → INVOICED → PAID → FULFILLMENT → COMPLETED

This is a shared vocabulary, not a claim that every sale follows an identical sequence. The stage validator permits forward skips and single-step reversals. It requires approved customer due diligence—KYC—for any target stage beyond qualification. It deliberately does not impose one global payment-before-fulfillment rule: domestic and vessel transactions have different operating terms.

Illustrative example, not customer data: a qualified deal for “Customer A” has KYC pending. Moving it to contract preparation is rejected. With KYC approved, that same transition is allowed. The accompanying demonstration reconstructs this rule locally; it does not access the private application or perform a real approval.

A product around the operating record

The Next.js application serves the operator portal and separate customer-facing workflows. API routes call shared business logic; Supabase provides database, authentication, and document storage. Deal records connect communications, quotes, contracts, trips, and events rather than requiring an operator to assemble that context manually.

The repository includes email ingestion and sending, Twilio WhatsApp integration, Anthropic SDK usage, PDF generation, and an electronic-signature integration. These are implementation findings—not confirmation that every provider is configured, live, or used in production. The product is deployed on Vercel; deployment of the application is distinct from commissioning every integration.

Fiscal-document handling also has explicit boundaries. The reviewed invoice-provider layer includes a mock implementation; this case does not claim verified live CFDI stamping. Carta Porte helpers assemble request fields and extract a fiscal UUID, but that extraction does not establish document authenticity or validate a digital signature.

Three decisions that matter beyond the interface

Enforce the rule where the change happens. Hiding a button is not an approval gate. KYC checks belong in the stage-validation logic and signing endpoint. The repository includes regression tests for pending, rejected, or missing approval, including a signing request made after qualification has changed.

Model legitimate exceptions without making every transition arbitrary. A rigid payment sequence would misrepresent different sales modes. The validator separates the shared KYC invariant from payment ordering, permits legitimate forward skips, and restricts backward movement to one stage at a time. Reopening a completed deal clears its resolution fields so an active case is not still represented as closed.

Separate identity from permission. Being signed in does not authorize someone to operate another workflow. Route tests distinguish operator/admin access from broker sessions and test token-to-deal binding for the relevant payment-confirmation route. That is narrower and more useful than claiming the whole application is “secure.”

Evidence—and what it does not prove

This case was checked against repository documentation, implementation, and selected test definitions on 2 October 2026. The reviewed tests include stage-transition-rules.test.js, contract-sign-kyc-gate.test.ts, resource-authz-routes.test.ts, auditLog.test.ts, invoiceProvider.test.ts, and carta-porte.test.js.

They specify behavior for workflow gates, authorization, audit payloads and failure responses, and fiscal-document helpers. Several use mocked services. Their presence is evidence of the intended regression checks—not a claim that the suite was executed for this case study, that live integrations passed, or that a compliance or security audit has been completed.

Deployed, with the next questions made explicit

The completed milestone is moving from direct operating discovery to a deployed application, confirmed in my current project record. Development continues. I am not publishing customer counts, transaction volume, savings, or reliability figures without an approved measurement source.

The next evaluation should measure handoff time, unresolved exceptions, document completeness, and the rate at which users need help to finish a workflow. Those are proposed measurements, not achieved results.

The product source is private. This public case exposes the workflow, decisions, and a synthetic rule demonstration without exposing customer records, credentials, or private repository access. The cinematic terminal is an editorial illustration of the domain, not a recording of the deployed product.