-
-
. Project Command Hub: Centralized workspace to manage projects, funding progress, and the complete BriefPay lifecycle.
-
BA Requirements Studio: Convert stakeholder conversations into structured business requirements with AI-assisted analysis and traceability
-
BRD Specification Book: Generate structured BRDs with SHA-256 integrity verification and stakeholder sign-offs.
-
Conditional Contract: Transform approved requirements into conditional agreements with defined obligations and execution milestones.
-
Pledge-If Campaign & AI Strategist: Enable conditional pledges and use AI-driven campaign insights to guide funding rounds.
-
AI Verification Matrix: Validate project deliverables against approved requirements using AI-powered verification criteria.
-
Payment Guardian: Validate PayPal balance proofs, allow legitimate payments, and block tampered transactions.
-
Public Immutable Ledger: Maintain transparent transaction records with immutable tracking and PayPal reconciliation.
-
AI Audit Trail: Track AI decisions and critical project actions through a transparent, traceable audit history.
BriefPay — Trust-First Collaborative Funding and Project Delivery
Inspiration
Small neighborhood businesses often need a shared digital product, such as a local tourism website for a coastal village like Velugu Cove. However, organizing multiple businesses to jointly hire a freelancer introduces four fundamental problems:
- The Cold-Start Coordination Problem: No business wants to contribute first and risk becoming the only party funding a project that others may abandon.
- Unstructured Requirements: Stakeholder meetings generate conflicting expectations, incomplete specifications, and ambiguous deliverables.
- Financial Trust and Accountability: Contributors need assurance about where pooled funds go, what happens when funding targets are missed, and how payments are handled when project plans change.
- Verification Asymmetry: Non-technical stakeholders cannot independently verify GitHub commits, deployed websites, or technical deliverables against agreed requirements. Freelancers also lack a neutral mechanism to demonstrate completion.
We built BriefPay to address these problems through conditional crowdfunding, AI-assisted requirements engineering, evidence-based delivery verification, and deterministic payment controls.
Its central innovation is a Pledge-If funding mechanism: contributors authorize PayPal payments without being charged immediately. Funds are captured only when the campaign reaches its agreed target and passes settlement checks.
Four cooperating AI agents support the project lifecycle, while deterministic business logic, cryptographic document fingerprints, and a single payment execution gateway enforce financial and operational rules.
What it does
BriefPay manages a collaborative project through an auditable lifecycle, from initial stakeholder discussions to freelancer payment and financial reconciliation.
1. AI-Powered Requirements Engineering (BA Studio)
Stakeholders upload meeting transcripts containing their expectations, ideas, and project requirements.
The Business Analyst (BA) Agent:
- Extracts functional and non-functional requirements from unstructured discussions.
- Evaluates completeness using a weighted, 10-dimension requirements rubric.
- Identifies conflicting expectations across stakeholders.
- Detects missing information and generates targeted clarification questions.
- Iteratively refines requirements until the deterministic scoring engine reaches a minimum threshold of 90/100.
The result is a structured requirements specification instead of an informal collection of stakeholder requests.
2. Business Requirements Document and Cryptographic Approval (BRD Lock)
The BA Agent transforms validated requirements into a structured Business Requirements Document (BRD).
Each requirement includes testable Given / When / Then acceptance criteria, allowing stakeholders and freelancers to agree on objectively verifiable outcomes.
Before proceeding:
- The BRD is fingerprinted using SHA-256.
- Every sponsor reviews and approves the exact document version.
- Any subsequent modification changes the document fingerprint and invalidates the previous approval state.
This creates a verifiable agreement about the expected project deliverables.
3. Conditional Freelancer Contract
A freelancer reviews the approved BRD fingerprint, agreed project budget, and delivery timeline before accepting the engagement.
The freelancer provides their PayPal payout email, and the contract is established with an explicit funding condition.
The engagement becomes effective only when the funding campaign successfully reaches its target and settlement is authorized.
This prevents freelancers from being committed to projects that never secure the required funding.
4. Pledge-If Funding Campaign and Campaign Strategist
BriefPay uses PayPal Orders v2 authorization flows to place payment holds instead of immediately charging contributors.
Campaign authorizations are capped at 72 hours to remain within PayPal's authorization honor period.
Two settlement outcomes are supported:
If the funding target is missed or the campaign is cancelled:
- Every active authorization is voided.
- Contributors are not charged.
- The total amount charged is $0.
If the funding target is reached:
- Authorized pledges are captured proportionally.
- Individual captures cannot exceed their original authorized amounts.
- Captured amounts must sum exactly to the agreed contract goal.
The settlement engine performs all calculations in integer cents to prevent floating-point rounding errors.
For a funding goal (G), authorized pledges (a_i), and captured amounts (c_i):
$$\sum_{i=1}^{n} c_i = G$$
Subject to:
$$0 \leq c_i \leq a_i$$
The Campaign Strategist complements this deterministic engine by:
- Forecasting campaign completion using a deterministic heuristic.
- Calculating deadlines and funding projections.
- Generating targeted WhatsApp outreach messages.
- Validating AI-generated wording against exact figures computed by the backend.
AI assists with communication and interpretation; it never determines financial settlement amounts.
5. Delivery Submission and AI-Assisted Verification
After completing the project, the freelancer submits:
- A public GitHub repository.
- The specific Git commit SHA.
- The deployed website URL.
BriefPay combines automated technical checks with its Verification Agent to evaluate the submitted deliverables against the locked BRD.
The verification process includes:
- Repository and commit verification.
- Live website accessibility and page inspection.
- SSRF-hardened URL validation.
- Screenshot and code evidence collection.
- Acceptance-criterion-level verification against the original requirements.
The Verification Agent reviews available evidence for each acceptance criterion and identifies missing, incomplete, or inconsistent deliverables.
Evidence is treated as untrusted input. Prompt-injection instructions embedded in screenshots, repository content, or submitted materials cannot override the verification instructions.
This gives non-technical stakeholders a structured way to evaluate delivery without needing to inspect source code themselves.
6. Payment Guardian and Controlled Payout Execution
BriefPay introduces a strict financial execution boundary through its Payment Guardian and MoneyExecutor architecture.
Every financial operation is first compiled into an immutable MoneyPlan. Supported operations include:
CAPTURE_PLEDGESRELEASE_HOLDSFREELANCER_PAYOUTREFUND_CAPTURED
Before execution, the Payment Guardian evaluates the proposed plan against 13 deterministic financial and security rules (G-01 to G-13).
The checks include:
- Authorization and capture consistency.
- Recipient verification.
- Payout amount validation.
- Duplicate capture prevention.
- Detection of unauthorized recipients.
- Detection of hidden financial operations.
- PayPal transaction reconciliation.
The Guardian also performs live verification using the APIMatic-generated paypal-server-sdk, including PayPal authorization, capture, and Transaction Search records.
An additional LLM-based risk review can escalate an otherwise allowed decision to HOLD, but cannot override a deterministic BLOCK.
Approved MoneyPlans are fingerprinted and require approval before reaching MoneyExecutor.
MoneyExecutor is the only component permitted to execute PayPal write operations. Automated AST-based and chokepoint tests enforce this architectural boundary, preventing routers, services, and AI agents from directly invoking payment write APIs.
This separates AI recommendations from actual financial execution.
7. Public Financial Ledger and AI Audit Trail
BriefPay provides transparent records of project funding, settlement, and AI activity.
The dashboard includes:
- An immutable financial ledger with transactions recorded in integer cents.
- PayPal Transaction Search reconciliation.
- Pledge and campaign status tracking.
- Guardian MoneyPlan decisions and execution status.
- BRD requirements and acceptance criteria.
- AI agent execution history and audit information.
Each AI invocation records its agent, model, prompt version, token usage, latency, and input hash.
The frontend uses AG Grid Community for interactive financial and audit tables, with formula-safe CSV exports.
This creates an auditable history of both financial decisions and AI-assisted operations.
How we built it
Architecture and Design Principles
BriefPay follows one core architectural principle:
AI perceives and proposes. Deterministic code computes and decides. Humans approve financial execution.
The system separates AI orchestration, business state management, financial calculations, and payment execution to prevent probabilistic model outputs from directly controlling money.
Backend
Built using:
- FastAPI
- Python
- SQLAlchemy 2
- Alembic
- Pydantic v2
- SQLite for local development
The backend uses separate state machines for ProjectService and CampaignService, keeping project progression independent from campaign funding and settlement.
Financial calculations are implemented in a dedicated settlement.py module using integer cents. Property-based tests using Hypothesis validate settlement invariants across different pledge combinations.
An in-process job runner and campaign clock handle:
- Long-running LLM operations.
- Webhook processing.
- 30-second PayPal polling fallbacks.
- Campaign deadline monitoring.
- Retryable background operations.
This design avoids requiring additional paid worker instances for the demonstration deployment.
PayPal Integration
PayPal integration uses the APIMatic-generated official paypal-server-sdk, with the APIMatic Context Plugin supporting implementation and API integration.
Integrated capabilities include:
- Orders v2.
- Payments v2.
- Transaction Search v1.
- Authorization and capture operations.
- Authorization voiding.
- Payouts v1 through a guarded
httpxclient. - Webhook signature verification.
A single MoneyExecutor component controls all PayPal write operations.
All financial operations use deterministic MoneyPlans, Guardian validation, idempotency keys, and reconciliation checks.
AI Agent Architecture
BriefPay uses four cooperating AI agents:
1. Business Analyst Agent
Processes stakeholder transcripts, extracts requirements, identifies conflicts, evaluates completeness, and generates structured BRDs.
2. Campaign Strategist Agent
Uses deterministic campaign calculations to produce funding forecasts, deadlines, and targeted stakeholder communication.
3. Verification Agent
Evaluates GitHub repositories, deployed websites, screenshots, and implementation evidence against BRD acceptance criteria.
4. Payment Guardian Agent
Reviews proposed financial operations, evaluates risk, and escalates suspicious plans for human review without overriding deterministic security decisions.
The AI integration uses a shared LLMAdapter built with google-genai for structured JSON generation and vision-based verification, with optional Groq text routing for BRD generation.
Pydantic validation enforces structured outputs, with corrective retries for invalid responses.
Untrusted evidence is explicitly wrapped using <untrusted> boundaries to reduce prompt-injection risks.
A hash-keyed Replay Mode provides deterministic AI responses for repeatable demonstrations and evaluation.
Frontend
Built using:
- Next.js 15
- React 19
- TypeScript
- Tailwind CSS
- AG Grid Community
The frontend uses Next.js static export (output: "export") with query-parameter routing and Bearer JWT authentication.
Interactive dashboards cover:
- Stakeholder requirements and BRD approvals.
- Campaign pledges and funding progress.
- Freelancer delivery submissions.
- Verification results.
- Guardian MoneyPlans.
- Public financial ledger.
- PayPal reconciliation.
- AI execution and audit history.
Direct browser uploads use signed Cloudinary uploads with metadata stripping, avoiding storage of image bytes in the application database.
Security and Reliability
Security controls are implemented at multiple layers:
- SHA-256 document fingerprinting for approval integrity.
- Deterministic financial settlement in integer cents.
- A single PayPal payment execution chokepoint.
- Static AST-based tests to prevent bypassing MoneyExecutor.
- Idempotent PayPal request identifiers.
- Webhook signature verification.
- SSRF-hardened delivery URL validation.
- Pydantic schema validation for AI-generated outputs.
- Prompt-injection-resistant evidence processing.
- Guardian rules for financial authorization and payout integrity.
The demonstration uses PayPal Sandbox (PAYPAL_ENV=sandbox) and fictional businesses.
Challenges We Ran Into
1. PayPal Authorization Honor Window
One of the most important design constraints was PayPal's authorization honor period.
Card and wallet authorization holds have a limited validity period, generally around three days. A conventional crowdfunding campaign that runs for several days or weeks cannot safely retain authorization holds throughout its entire duration.
We addressed this by:
- Restricting campaign authorization windows to a maximum of 72 hours.
- Introducing settlement safety margins.
- Implementing campaign deadlines and authorization expiry checks.
- Adding Guardian rules to prevent settlement using expired or invalid authorizations.
This required designing the campaign lifecycle around payment-provider constraints rather than treating payment authorization as indefinite escrow.
2. Preventing AI Hallucinations in Financial and Legal Decisions
AI-generated requirements, forecasts, verification results, and financial risk assessments must not introduce unsupported facts or override agreed business rules.
We addressed this by separating AI responsibilities from deterministic computation.
For example:
- BA scoring is computed by a deterministic rubric engine.
- Campaign projections are calculated in code.
- Strategist-generated numerical claims are checked against backend-computed facts.
- Verification decisions are evaluated against explicit acceptance criteria and available evidence.
- Guardian LLM reviews can only escalate an ALLOW decision to HOLD, never override a deterministic BLOCK.
This architecture allows AI to provide useful reasoning without granting it unrestricted authority over financial operations.
3. SQLite Write Contention and Webhook Race Conditions
Running background jobs and AI operations alongside SQLite transactions introduced write-lock contention.
One issue occurred when logging agent_runs through LLMAdapter._log while another transaction was still active.
We resolved this by committing the required pre-LLM state before invoking the logging operation.
We also implemented:
- Idempotent
PayPal-Request-Idkeys. - Retryable
NotReadywebhook handling. - Safer transaction boundaries.
- Duplicate-operation protection.
These changes improved reliability when asynchronous operations and webhook processing overlapped.
4. Operating Within Zero-Cost Infrastructure Constraints
We wanted the project to remain demonstrable without requiring paid message queues, dedicated background workers, or expensive database infrastructure.
This required:
- An in-process background job runner.
- Database-driven campaign deadline checks.
- Webhook processing with polling fallbacks.
- Replay fixtures for repeatable AI demonstrations.
- Static frontend export.
- Careful handling of long-running AI requests.
The result is an architecture designed to operate within constrained hosting environments while preserving the important financial and verification controls.
What We Learned and Measured
We backed the core business rules and security boundaries with automated unit, property-based, contract, mutation, and evaluation tests.
Evaluation results are documented in backend/tests/test_eval.py and docs/EVAL_RESULTS.md.
Payment Guardian: 8/8 Correct Decisions
All eight evaluated MoneyPlans received the expected decisions.
All five simulated financial tampering attacks were blocked deterministically:
- Recipient substitution.
- Inflated freelancer payout.
- Unauthorized additional recipient.
- Duplicate capture.
- Capture operation concealed inside a release plan.
These evaluations demonstrate that financial execution is protected by deterministic rules rather than relying on AI judgment alone.
BA Scoring Engine: 3/3 Correct Evaluations
The requirements evaluation tests behaved as expected:
- A good transcript progressed through clarification from 58 to 79 to 93.
- Missing requirements remained capped at 89.
- Conflicting specifications remained below the 90-point approval threshold until resolved.
This validates the clarification-driven requirements workflow.
Verification Aggregation: 10/10 Correct Decisions
All ten verification evaluation cases produced the expected results.
The evaluation covered:
- Fake screenshots.
- Missing repository evidence.
- Incomplete implementation evidence.
- Prompt-injection instructions embedded in submitted materials.
This validates the criterion-based evidence evaluation approach.
Campaign Strategist: 20/20 Expected Directional Outcomes
Twenty synthetic campaign scenarios produced the expected directional forecasting behavior.
The heuristic achieved a Brier score of 0.232, providing a quantitative evaluation of its probability forecasts.
Key Learnings
Building BriefPay reinforced several important engineering principles:
- AI-generated specifications become significantly more useful when paired with deterministic completeness checks and explicit acceptance criteria.
- Cryptographic document fingerprints make approval integrity independently verifiable.
- Payment authorization and payment capture must be treated as separate financial states.
- Financial calculations should use integer arithmetic rather than floating-point amounts.
- AI agents should not have direct access to financial execution capabilities.
- Evidence-based verification is more useful to non-technical stakeholders than simply asking an AI whether a project is complete.
- Provider constraints, hosting limitations, and webhook reliability must influence architecture from the beginning rather than being addressed at the end.
BriefPay demonstrates how AI agents, deterministic financial controls, and PayPal payment infrastructure can work together to make collaborative project funding more transparent, accountable, and verifiable.
Built for the PayPal AI Hackathon using PayPal Sandbox (PAYPAL_ENV=sandbox) and fictional demonstration businesses. No real-money transactions were performed.
Built With
- ag-grid
- alembic
- fastapi
- goggle-geminiai
- groqai
- nextjs
- paypalsandbox
- pydantic
- python
- react
- sqlalchemy
- sqlite
- tailwindcss
- typescript