NudgeMyInvoice

NudgeMyInvoice uses AI to turn plain-English requests into validated, multi-currency PayPal invoice drafts—saving freelancers time while keeping humans in control of every financial action.

Comment

Inspiration

Freelancers and small business owners don't start businesses because they love preparing invoices, tracking billing records, or reminding customers about outstanding work.

Yet these administrative tasks consume valuable time that could be spent creating, serving customers, and growing a business.

We started with a simple question:

What if invoicing were as easy as describing the work you've completed?

That idea became NudgeMyInvoice.

But as we developed the application, we realized that generating invoices was only part of the problem. Freelancers also need help finding invoices, organizing follow-ups, reviewing financial information, and staying on top of their administrative workload.

That's when Nudgey, our friendly invoice companion, became an important part of the experience.

We wanted NudgeMyInvoice to feel less like another accounting tool and more like having a helpful assistant beside you—one that guides you through invoicing without taking control of your money.

Our guiding principle became:

AI prepares. Systems verify. Humans control.

Because when AI meets financial services, convenience should never come at the expense of security, accuracy, or accountability.

What it does

NudgeMyInvoice is an AI-powered invoicing companion that helps freelancers create, organize, and follow up on invoices while keeping financial actions under human control.

At the heart of the experience is Nudgey, a conversational companion designed to make invoicing less intimidating.

Instead of navigating multiple screens, users can ask Nudgey for help with supported invoice-related tasks.

Meet Nudgey — Your Invoice Companion

Nudgey provides a conversational entry point into NudgeMyInvoice.

Users can ask about saved invoices, search by customer or currency, check upcoming follow-up reminders, and initiate invoice creation.

When a supported creation request is recognized, Nudgey guides the user into the Invoice Composer with their request already prepared for review.

Nudgey combines deterministic intent recognition and authenticated application lookups with dedicated AI-powered features. It is intentionally not an unrestricted AI agent: it cannot independently execute financial transactions.

AI-Powered Invoice Creation

Users can describe their work in plain English.

For example:

Create an invoice for Northwind Studio for 20 hours of lead qualification at $60 per hour, due December 12, 2026.

OpenAI interprets the request and proposes structured invoice details, including customer information, line items, quantities, prices, currency, and due date.

The operator reviews and edits the proposal before saving.

Every invoice is validated, and the backend independently calculates monetary totals rather than trusting AI-generated arithmetic.

If AI parsing is unavailable, users can continue with manual entry.

A Complete Invoice Management Experience

NudgeMyInvoice also includes:

  • Multi-currency invoicing: Manage invoices in different currencies without misleading conversions or mixed-currency totals.
  • Invoice dashboard: Search, filter, and review saved invoices through an AG Grid-powered interface with per-currency analytics.
  • PayPal Sandbox integration: Create genuine PayPal Sandbox DRAFT invoices following explicit user confirmation.
  • PayPal draft synchronization: Manually import existing Sandbox drafts through a controlled, read-only integration and link verified matching records.
  • AI Nudge Queue: Generate professional payment follow-up suggestions for review, editing, approval, and manual use.
  • Local follow-up reminders: Organize upcoming follow-up activity without automatically contacting customers.
  • Human-controlled actions: Nudgey and OpenAI cannot independently send invoices, collect payments, issue refunds, or dispatch reminders.

The result is more than an AI invoice generator. It's a growing invoicing workspace with a helpful companion at its center.

How we built it

We designed NudgeMyInvoice as a modular, security-conscious application, combining modern web technologies, generative AI, and PayPal's Invoicing API.

Technology stack

  • Frontend: React, Vite, and TypeScript.
  • Backend: Node.js, Fastify, and TypeScript.
  • AI: OpenAI Responses API with structured output validation using Zod.
  • Financial integration: PayPal Invoicing REST API, restricted to the Sandbox environment.
  • Database: PostgreSQL with Drizzle ORM.
  • Analytics: AG Grid Community, with licensed AG Studio analytics developed and tested.
  • Hosting: Render web services and managed PostgreSQL.
  • Testing: Vitest, deterministic provider simulations, real PostgreSQL integration tests, and browser-based QA.
  • Development workflow: AI-assisted implementation, GitHub pull requests, focused code reviews, security audits, remediation, and human-controlled release decisions.

Security is part of the architecture

One of our most important architectural decisions was to separate AI interpretation from financial authority.

OpenAI can propose invoice information, but it cannot directly execute PayPal operations.

The backend independently enforces authentication, authorization, data validation, exact monetary calculations, and permitted financial actions.

We implemented multiple safeguards:

1. Server-side authentication and authorization

Authenticated sessions, HttpOnly cookies, Origin and CSRF protection, and owner-scoped database operations prevent unauthorized requests from bypassing the application workflow.

2. Strict validation of AI-generated data

AI output is treated as untrusted input. Zod and domain validation check invoice structures, while monetary amounts are calculated using exact integer minor-unit arithmetic.

3. Protected provider credentials

OpenAI and PayPal credentials remain server-side and are never embedded in browser application code.

4. Restricted PayPal capabilities

PayPal integration is confined to approved Sandbox operations. Draft creation requires explicit confirmation, and the application does not implement autonomous invoice sending, payment capture, or refunds.

5. Durable financial-operation controls

Idempotency, concurrency safeguards, database-backed operation states, and read-back verification help prevent duplicate drafts and unsafe retries following uncertain provider responses.

6. Privacy-conscious AI integration

We minimize information sent to AI services where possible, constrain the facts supplied for AI nudge drafting, and exclude raw invoice descriptions and credentials from application audit records.

Invoice descriptions submitted for AI parsing may contain customer information and are transmitted to OpenAI for processing. Our objective is controlled, transparent data handling—not an unsupported claim that information never leaves the application.

AI-assisted development with independent review

Another defining aspect of this project is how we built it.

We used AI coding assistance to implement carefully scoped features, then subjected changes to separate technical review and security-focused audits.

Our process followed a recurring cycle:

Specification → AI-Assisted Implementation → Automated Tests → Independent Review → Remediation → Revalidation → Human Approval

Review findings were not simply dismissed to make a deadline.

For example, reviews identified issues involving pagination, concurrent database operations, ambiguous provider responses, and mobile interface behavior.

Each significant finding led to focused investigation, corrections, and regression testing.

This iterative process became an important part of the project's engineering discipline.

Challenges we ran into

1. Making AI-generated financial information trustworthy

Generative AI is useful for understanding natural language, but financial calculations demand deterministic correctness.

We separated AI extraction from authoritative calculations and added strict validation and human review before invoice persistence.

2. Preventing duplicate PayPal invoices

A network timeout does not necessarily mean a PayPal request failed. Repeating the operation blindly could create duplicate invoice drafts.

We implemented durable operation records, explicit state transitions, idempotency safeguards, and read-back verification to handle uncertain outcomes more safely.

3. Maintaining security across AI and payment boundaries

Financial workflows introduce sensitive information, external APIs, privileged operations, and opportunities for unauthorized actions.

We established server-enforced boundaries that prevent prompts or generated text from becoming financial authorization.

4. Building Nudgey without giving it excessive authority

Creating a conversational assistant was exciting, but we didn't want an unrestricted chatbot that could misinterpret requests and trigger financial operations.

We designed Nudgey around supported intents, authenticated lookups, safe handoffs, and explicit confirmation.

Nudgey can help users navigate financial tasks without pretending it knows payment statuses that have not been verified.

5. Handling real-world PayPal synchronization

PayPal invoice records can be incomplete, repeated across pages, or inconsistent with local data.

Our read-only synchronization needed bounded pagination, strict validation, duplicate-safe database updates, and conservative reconciliation.

When remote information cannot be verified, the system does not invent a matching local invoice.

6. Managing rigorous reviews under hackathon time constraints

Some of our biggest challenges came from findings uncovered after features appeared to be working.

Independent reviews identified edge cases involving concurrency, data integrity, and UI behavior that required additional development cycles.

When hosted CI became unavailable because of an external billing restriction, we documented manual validation evidence rather than falsely reporting that hosted checks had passed.

We learned that responsible AI-assisted development requires patience, verification, and clear human accountability—even during a hackathon.

Accomplishments that we're proud of

We're proud that NudgeMyInvoice evolved from a simple AI invoice generator into a functional, security-conscious invoicing companion.

Our key accomplishments include:

  • Creating Nudgey, a branded conversational companion that connects invoice lookups, creation guidance, and follow-up workflows.
  • Integrating OpenAI for structured invoice extraction and AI-assisted payment-nudge drafting.
  • Building a real PayPal Sandbox integration with authenticated, human-confirmed draft creation and durable verification safeguards.
  • Adding PayPal draft synchronization with safe imports, deduplication, and conservative local-record matching.
  • Delivering an interactive invoice dashboard with search, filtering, multi-currency visibility, and AG Grid integration.
  • Implementing extensive automated testing, including hundreds of unit, integration, security, and browser-focused tests across development cycles.
  • Completing bounded real-provider verification for OpenAI parsing and PayPal Sandbox drafting, separately from simulated-provider test evidence.
  • Using iterative independent reviews to uncover and remediate non-obvious financial and security risks.

One example was our PayPal synchronization implementation, which underwent multiple review-and-remediation cycles to address pagination completeness, atomic database updates, and audit-failure handling.

Another was the combined judge-release work, where an initial partial review led to additional mobile QA and focused revalidation.

These experiences reinforced our belief that AI-assisted development can be both fast and disciplined when verification remains a core part of the process.

Our proudest accomplishment isn't the number of features or pull requests. It's the security and accountability built into the workflow.

What we learned

Building NudgeMyInvoice taught us lessons that extend beyond invoicing.

AI should reduce effort without removing responsibility.

AI can understand requests and prepare useful information, but consequential financial actions need verified data and human authorization.

Security should be designed into the product from the beginning.

Authentication, data isolation, validation, idempotency, and privacy controls are architectural decisions—not features to bolt on after launch.

Financial correctness is more important than a convincing demonstration.

A beautiful interface means little if the application can duplicate invoices, miscalculate amounts, or misrepresent payment status.

AI assistants need clear boundaries.

Nudgey is most useful when it helps people complete tasks safely, acknowledges limitations, and hands off to controlled workflows when appropriate.

Independent auditing improves AI-assisted development.

Coding agents can accelerate implementation. Separate reviews help challenge assumptions, uncover edge cases, and produce stronger systems.

Human oversight is a design advantage.

Our goal was never to replace financial judgment with an autonomous agent. It was to make financial administration easier while preserving user trust.

What's next for NudgeMyInvoice

The hackathon helped us establish a working foundation. Our next goal is to evolve NudgeMyInvoice into a practical invoicing companion for freelancers and small businesses.

Our priorities include:

1. Make Nudgey more conversational

Expand supported natural-language requests, improve clarification of missing invoice information, and make the experience easier for people who don't use predefined commands.

2. Strengthen the invoice lifecycle

Build on the current dashboard, draft management, and PayPal synchronization capabilities with clearer invoice states and richer workflow visibility.

3. Add verified payment-status integration

Introduce properly authenticated and verified PayPal webhook handling and reconciliation so the application can distinguish actual payment activity from invoice draft states.

4. Explore human-approved sending

Extend beyond Sandbox draft creation only after implementing the necessary authorization, privacy, operational, and payment-safety controls.

5. Improve proactive invoice assistance

Expand Nudgey's follow-up guidance and AI-assisted communication while maintaining explicit human review and control over anything sent to a customer.

6. Prepare for broader adoption

Continue accessibility testing, security hardening, operational monitoring, privacy reviews, and deployment improvements before supporting real business financial activity.

Longer term, we envision Nudgey becoming a dependable AI companion that helps independent professionals spend less time managing paperwork and more time building their businesses.

NudgeMyInvoice isn't about giving AI control over financial decisions. It's about giving people an intelligent assistant that makes financial administration easier, safer, and more manageable.

Less invoicing. More earning. Always in control.

Built With

Share this project:

Updates

Submission history