The Story Behind Accordly
Inspiration
It often starts with a simple message from a client:
"Could we just add one more feature?"
Four seemingly harmless words that can gradually turn into additional deliverables, extra development hours, unexpected integrations, and extended deadlines.
For freelancers and small digital agencies, the problem isn't necessarily the additional work itself. It's what happens when that work falls outside the original agreement but never makes it into a formal change request, an approved price, or an invoice.
We saw an opportunity to solve this disconnect.
A service provider might have the original agreement in a PDF, the client's request in a messaging application, the revised estimate in a spreadsheet, approval in an email, and the eventual payment in a completely different platform. Each step exists, but the connection between them is often missing.
We wanted to connect the entire journey, from the original project scope to the final payment.
That idea became Accordly.
Our vision was to build an AI-powered scope-to-cash platform that helps freelancers and digital agencies understand scope changes, establish their commercial impact, obtain explicit client approval, and collect payments through PayPal.
Our guiding principle became:
From scope to payment. Every change accounted for.
How We Built It
Rather than building another project-management dashboard or a generic AI chatbot, we focused on one connected commercial workflow:
Agreement → Scope Analysis → Change Proposal → Client Approval → PayPal Invoice → Payment Reconciliation
- Turning Agreements into Structured Scope
Everything begins with the original project agreement.
A provider uploads an agreement, and Accordly uses AI to extract its important commercial details, including:
- Project objectives and deliverables.
- Explicit exclusions.
- Revision limits.
- Milestones and acceptance criteria.
- Timelines and payment terms.
- Ambiguities and missing information.
The extracted information is presented as a structured scope baseline. Importantly, the provider must review and confirm it before Accordly uses it for subsequent analysis.
- Giving Client Requests Context
This is where Accordly's scope intelligence comes in.
When a client submits a new request, our AI analysis pipeline compares it against the confirmed agreement baseline and relevant source passages.
Each request receives one of three classifications:
- IN_SCOPE: The request appears to be covered by the original agreement.
- OUT_OF_SCOPE: The agreement provides evidence that the request falls outside the agreed work.
- AMBIGUOUS: The available agreement evidence is insufficient to make a reliable determination.
Instead of returning an unexplained AI-generated verdict, Accordly provides supporting excerpts and reasoning so the provider can understand and review the assessment.
We deliberately designed the system to recognize uncertainty rather than force a confident answer when the agreement does not provide enough evidence.
- Turning Scope Changes into Commercial Proposals
Once a provider decides to proceed with a change, Accordly helps create a structured change proposal containing the additional deliverables, assumptions, pricing, and timeline impact.
One important architectural decision was to keep pricing deterministic.
AI can help interpret the work and draft descriptions, but it does not silently determine the final price. Fixed-price overrides, hourly calculations, and line-item totals are calculated by application logic using decimal-safe arithmetic.
The provider reviews and approves the proposal before it is shared with the client.
- Making Client Approval Part of the Workflow
Accordly generates a secure, shareable client review link.
Clients can inspect the proposed changes and accept or reject them without creating an account. Their decision is recorded against the exact proposal version, with a timestamp.
Proposal versions are preserved so that changes to a previously approved proposal do not silently rewrite the original approval record.
- Connecting Approval to Actual Payments with PayPal
We wanted the workflow to extend beyond generating an invoice-looking screen.
After the client accepts a proposal, the provider explicitly initiates PayPal invoice creation and sending through the PayPal Invoicing API.
Clients can then pay through PayPal Sandbox checkout.
Accordly receives relevant PayPal webhook events, verifies their signatures, prevents duplicate processing, and retrieves the authoritative invoice state from PayPal before updating its own financial records.
This ensures that the dashboard reflects reconciled payment information rather than simply trusting an incoming event or changing a status manually.
- Keeping Every Change Accountable
The dashboard brings the workflow together through features such as:
- Scope Drift Radar: Tracks proposed, approved, accepted, invoiced, collected, and outstanding change-order values.
- Visual Scope Comparison: Makes it easier to compare a new request against the original agreement and supporting evidence.
- Proposal Version Comparison: Shows what changed between proposal versions, including pricing and timeline differences.
- Agreement Health Check: Highlights missing or incomplete commercial terms.
- Project Timeline: Maintains a chronological record of important project and commercial events.
Together, these features make Accordly more than a document analyzer or invoice generator. They connect the decisions and financial actions that happen throughout a project's lifecycle.
Technology Stack
We combined modern web technologies, AI services, and payment infrastructure to build the application.
Layer| Technologies Frontend| Next.js 15, React 19, TypeScript Styling| Tailwind CSS Backend| Next.js API routes Database| PostgreSQL (Neon) ORM| Prisma Authentication| Better Auth, Google OAuth AI Integration| Groq, Google Gemini Payments| PayPal REST APIs, PayPal Invoicing Payment Events| PayPal Webhooks Testing| Vitest
The application uses a modular architecture to separate document processing, AI analysis, commercial workflows, payment operations, and webhook reconciliation.
What We Learned
Building Accordly taught us that integrating AI into a real business workflow requires much more than connecting an application to an LLM.
- AI Needs Evidence, Not Just Answers
A model can produce a convincing explanation while misunderstanding a contract clause. We learned to make source-grounded reasoning, structured output validation, and human review central to the workflow. An ambiguous agreement should produce an ambiguous result, not an invented certainty.
- AI and Deterministic Software Have Different Responsibilities
AI is useful for interpreting unstructured documents and understanding natural-language requests. However, financial calculations, permissions, approval states, and payment reconciliation require deterministic application logic.
Keeping these responsibilities separate made the system more predictable and reliable.
- Payment Integration Is a Lifecycle, Not an API Call
Creating an invoice is only one part of a payment integration. We had to account for invoice states, API failures, duplicate requests, webhook verification, event idempotency, and reconciliation against PayPal's actual invoice data.
- Human Approval Is an Important Part of Automation
We learned that a useful AI-assisted system does not need to automate every decision. In commercial workflows, keeping providers in control of classifications, pricing, proposals, and invoice creation is essential.
- Auditability Needs to Be Designed from the Beginning
Versioned proposals, secure client review links, timestamps, and project events are not merely additional features. They are what make the workflow traceable when someone needs to understand what was requested, approved, invoiced, and paid.
Challenges We Faced
The most interesting challenges were not simply getting individual features to work, but making them work together reliably.
Understanding Ambiguous Agreements
Real-world agreements are not always written in a way that makes scope boundaries obvious. A missing clause does not automatically mean that a request is excluded.
We had to design the analysis pipeline to distinguish explicit exclusions from missing information, preserve supporting excerpts, validate AI output, and allow human review.
Making AI Output Reliable
Structured AI responses can still contain malformed data, unsupported claims, or irrelevant citations. We addressed this through schema validation, citation checks, controlled classifications, and safeguards against instructions embedded in uploaded documents.
Preserving Commercial and Financial Integrity
We needed to ensure that an accepted proposal could not be silently modified, that AI could not alter final prices, and that repeated invoice actions would not create duplicate invoices.
We addressed these concerns through deterministic pricing, proposal versioning, explicit state transitions, and idempotent operations.
Handling PayPal Webhooks Correctly
One of the most important engineering challenges was making payment status trustworthy.
A webhook notification alone should not be treated as unquestionable proof of payment. We implemented signature verification, event deduplication, and server-side invoice retrieval to reconcile local records against PayPal's authoritative state.
We also had to work through Sandbox account and currency configuration issues to complete the payment demonstration.
Building a Complete Product Under Hackathon Constraints
We had to balance the complexity of AI document processing, authentication, database design, payment integration, and a polished user experience against a limited development timeline.
Our solution was to prioritize a complete end-to-end workflow over isolated features. We focused on making the core journey work first, then expanded the dashboard, comparison tools, project history, and overall experience.
What's Next?
Accordly is a working hackathon prototype built around PayPal Sandbox, not a production payment or legal-services platform.
There is still room to expand it with deeper integrations into the tools freelancers already use, broader document support, improved agreement analysis, and production-ready payment infrastructure.
But the central idea remains the same:
When the scope changes, the commercial agreement should keep up.
We built Accordly because additional work deserves to be visible, understood, approved, and accounted for.
And we hope it can help make that process a little easier for the people who build things for a living.
Accordly — From scope to payment. Every change accounted for.
Built With
- betterauth
- googleoauth
- groq
- neondb
- next.js
- paypal-restapis
- postgresql
- prisma
- react
- sandboxinvoicing
- tailwindcss
- typescript
- vitest
- webhooks