Inspiration

When a client pays for a software milestone, “the work is complete” can mean different things to each side. The application may run, while test coverage falls below the agreed target, response times exceed the limit, or delivery documentation is missing.

The difficult question comes next: what amount should be paid, and how can both sides check that it is fair?

The answer often sits across a contract, test reports and scattered conversations. CovenantX brings those records together so a payment decision can be traced back to the requirements agreed before delivery.

What it does

CovenantX reviews software delivery evidence against contract terms and prepares a payment amount for client approval through PayPal Sandbox.

The workflow follows five steps:

  1. Agree on the milestone. The client records the price, acceptance criteria and deductions for missed requirements.
  2. Submit delivery evidence. The vendor uploads reports associated with the delivery commit.
  3. Inspect and review. The client checks the evidence source. Gemini then reviews each clause and supplies supporting quotations.
  4. Calculate and approve. The backend validates the findings, applies the agreed deductions and presents the amount for separate client approval.
  5. Complete Sandbox checkout. The integration creates a PayPal order for the approved amount, supports buyer approval and capture, and reconciles the provider’s response.

Consider a $5,000 milestone with an 85% coverage requirement and an agreed $500 deduction. If the report shows 78% coverage and the other clauses pass, CovenantX proposes $4,500. The client can inspect the failed clause and its evidence before approving payment.

The AI review directly affects whether a settlement can proceed. Missing evidence, contradictory findings or unresolved concerns place the proposal on hold. Contract rules determine the arithmetic, and the client retains final approval.

How we built it

The frontend uses Next.js, React and TypeScript. Its workspaces cover contracts, evidence, verification, settlement, disputes and payment operations. Users can compare review findings, explore hypothetical deductions and export an evidence passport containing the decision’s supporting records.

The backend uses Python, FastAPI and Pydantic for API operations and input validation. SQLAlchemy stores milestones and audit events, with SQLite used locally.

Report parsers extract measurements from Coverage.py JSON, k6 summaries, supported SARIF security reports, and text or Markdown documentation. Submissions retain their content hashes, delivery commit references and observation times.

We integrated Gemini through the Google GenAI SDK with two sequential review stages. The first maps evidence to contract clauses. The second receives those findings and checks for unsupported conclusions or contradictions. Both use the configured model, and their outputs are available for inspection.

The backend then checks exact quotations, measurement consistency and clause coverage. Settlement amounts use decimal arithmetic. Approval records a snapshot that ties the contract, evidence and decision to the payment request.

The PayPal Sandbox Orders integration uses that approved amount for checkout. Stored request identifiers, revision checks and order validation support consistent handling of repeated or interrupted actions.

Challenges we ran into

Making AI findings checkable. A convincing explanation alone cannot justify changing a payment. We required structured findings and exact quotations, then checked them against the submitted evidence. Reviewer disagreement and unsupported conclusions hold the proposal for inspection.

Keeping approval tied to the right delivery. Evidence can change while a milestone is being reviewed. We used commit references, locked contract rules and revision checks to keep each decision tied to the records the client actually reviewed.

Handling uncertain payment outcomes. A timeout can happen after a provider receives a request. We built explicit payment states and reconciliation around the existing order so uncertainty can be investigated before further payment actions.

Making the workflow easier to follow. Local walkthroughs exposed friction around role switching and evidence attestation. That showed us how much the experience depends on clearly identifying who should act next and what they need to do.

Accomplishments that we’re proud of

We connected contract terms, delivery evidence, review findings and payment approval in one inspectable workflow.

Our completed local fixture test moved a milestone through contract approval, evidence submission, attestation and review. It produced the expected $500 deduction and $4,500 proposed settlement, with supporting findings visible beside each clause.

We also implemented several details that matter when money is involved:

  • Separate approval of the contract, evidence and settlement.
  • Checks for stale evidence, mismatched commits and contradictory findings.
  • Payment request identifiers and provider reconciliation.
  • Dispute handling that requires fresh settlement approval.
  • An exportable evidence passport and searchable activity history.

The demonstrated walkthrough uses explicitly labeled simulated findings and blocks payment authorization. The Gemini and PayPal Sandbox adapters are implemented; their complete provider-backed review and capture flow is the next integration checkpoint.

What we learned

We learned that a payment decision needs a clear chain of responsibility. The contract defines the terms, the vendor supplies evidence, the client inspects its source, the model interprets it, and the backend checks the result before approval.

We also learned that different checks establish different things. A hash identifies content. A quotation supports a finding. An attestation records a person’s inspection. Keeping those distinctions visible makes the decision easier to understand and challenge.

Finally, building the payment flow made idempotency, revision control and reconciliation practical engineering concerns. They determine how the application behaves when users repeat an action, records change or a provider response is interrupted.

What’s next for CovenantX

Our immediate goal is to complete and record a genuine Gemini review followed by PayPal Sandbox buyer approval, capture and reconciliation.

We will then demonstrate the workflow with actual coverage, performance and security reports from a software delivery. Alongside that, we will simplify role switching and make the next required action more prominent throughout the interface.

Built With

Share this project:

Updates

Submission history