-
-
Product view
Inspiration
A shopping list is not the same as a working setup.
That idea became the starting point for BundleGraph. Someone starting a two-person podcast might ask an AI assistant for microphones, headphones, and an audio interface within a budget. The recommendations can look convincing individually while failing as a system: the interface might not have enough microphone inputs, a required cable could be missing, or the headphone connections might not support the requested monitoring setup.
We wanted to answer a more useful question:
“Can you help me build a complete setup that actually works together and explain why?”
We were also interested in what happens after a recommendation. If a component becomes unavailable, replacing it should not silently break compatibility, exceed the budget, or carry an old approval over to a different plan.
BundleGraph treats equipment planning as a dependency problem, not just a product-search problem.
What it does
BundleGraph turns a natural-language podcast request into a structured, explainable equipment plan.
A user can describe a setup such as:
“Two people recording on a USB-C laptop, with a $600 budget, separate headphones, and all the necessary cables.”
The application then guides them through five stages:
- Describe the setup.
- Review and explicitly confirm the requirements.
- Compare equipment bundles, costs, compatibility findings, and evidence.
- Review and approve an exact stored plan version.
- Inspect execution information and explore replacements when something changes.
The compatibility engine checks the relationships between microphones, audio interfaces, cables, laptop connectors, and monitoring requirements. It distinguishes compatible, incompatible, and unknown outcomes rather than treating missing specifications as proof that something works.
When an item becomes unavailable, the replanner proposes replacements while preserving confirmed constraints and locked components. It explains what was added, removed, or retained, and material changes require renewed approval.
How we built it
We separated BundleGraph into three connected layers.
AI-assisted interpretation and deterministic planning
AI helps translate a free-form request into a draft of structured requirements. A Groq-backed extraction adapter is available when configured, and its output is validated with Pydantic.
The AI does not confirm requirements or decide whether equipment is compatible. The user confirms the requirements, and deterministic Python rules evaluate the equipment.
A bounded search selects candidate bundles from a normalized catalog. Results include quantities, cost details, compatibility findings, and evidence references. A dependency graph makes the connections inspectable instead of hiding the reasoning behind a recommendation.
Authoritative application and payment boundaries
FastAPI and PostgreSQL provide the application layer for requirement drafts, confirmed inputs, catalog snapshots, ownership, plans, evidence, approvals, and payment-operation records.
Approvals bind to stored plan versions and amounts. Replacement application uses server-generated proposal references and authoritative state rather than trusting a replacement object supplied by the browser.
PayPal Sandbox support provides a controlled environment for payment integration. Payment amounts and merchant allocations come from persisted plans, not editable browser values. The backend also includes idempotency and webhook-verification mechanisms to handle repeated requests and asynchronous provider events.
Production payment execution remains deliberately blocked.
Guided frontend and reproducible demo
We built the interface with React, TypeScript, and Vite, using React Flow for the dependency graph, AG Grid for equipment details, and Motion for restrained interaction transitions.
The repository includes synthetic equipment data, offline demonstrations and evaluation, PostgreSQL migrations, Docker Compose, pytest, Playwright, and GitHub Actions. This lets reviewers explore the project without needing private provider credentials.
Challenges we faced
Keeping AI interpretation separate from authority
A plausible interpretation is not necessarily the user's intent, and a valid JSON response is not proof that a recommendation is correct.
We had to keep clear boundaries between extracted drafts, explicit confirmation, compatibility evaluation, plan approval, and payment execution. Each stage needed its own evidence and prerequisites.
Representing uncertainty honestly
Missing product specifications, unknown shipping costs, and unavailable delivery evidence are easy to hide behind defaults.
We chose to make those gaps visible. Unknown costs do not become zero, missing evidence does not become compatibility, and a recording target date does not become a delivery promise.
That made the interface and backend more demanding to build, but it also made the results more trustworthy.
Replanning without changing the agreement
Replacing one component can affect cables, inputs, monitoring, cost, and approval validity.
We designed recovery around structured changes rather than silently editing a shopping cart. A replacement must be checked against authoritative inputs, and an updated plan must not inherit approval that applied to a different version.
Making payment state understandable
Plan approval, payment authorization, capture, and fulfillment are different events.
We worked to preserve those distinctions in both the application model and the interface. A generated approval URL is not proof of a completed payment, and a simulated execution is not a real purchase.
Balancing technical depth with usability
Our early interface exposed too much infrastructure terminology. We refactored it into a guided workspace that prioritizes the user's next decision while keeping evidence, identifiers, and diagnostics available when needed.
What we learned
Our biggest lesson was that reliable AI applications need explicit boundaries around what the model is allowed to do.
AI is useful for translating intent into a draft. Deterministic validation, authoritative records, and user confirmation are better suited to deciding whether a plan can be trusted and acted upon.
We also learned that:
- Compatibility belongs to the complete system, not just individual products.
- Evidence needs provenance and context, not merely a link.
- Idempotency means safely repeating the same operation, not accepting a reused identifier for different inputs.
- Recovery is a core product behavior, not just an error message.
- Clear interface language is part of correctness: users should know what is confirmed, what is uncertain, and what has actually happened.
Accomplishments we're proud of
- Building an end-to-end path from a natural-language request to an explainable, versioned equipment plan.
- Keeping AI interpretation separate from compatibility and approval decisions.
- Making accessory quantities and connection dependencies part of planning.
- Producing structured replacement proposals instead of silently substituting equipment.
- Preserving clear boundaries between synthetic demonstrations, authoritative application state, and payment testing.
- Providing a reproducible project that reviewers can run without private credentials.
Current scope and limitations
The current verified planning domain focuses on two-person podcast setups.
The equipment catalog, prices, merchants, and fixture evidence are synthetic and explicitly labeled. The public hosted demo runs in fixture mode; the Docker Compose runbook provides the PostgreSQL-backed authoritative workflow.
PayPal Sandbox integration is available for controlled testing, but fixture mode makes no payment-provider calls. Production purchasing is not enabled.
Optional discovery, evidence-retrieval, and research adapters are extension points not claims that every provider is connected or running in the public demo.
What's next
Our next step is to connect reviewed equipment data and strengthen evidence coverage while preserving the same fail-closed behavior.
We also want to expand supported recording configurations, improve the clarity of connection explanations, and make replacement comparisons easier to evaluate.
The goal is not simply to recommend more products. It is to help people understand and trust the complete setup they are choosing.
BundleGraph: Great gear. Better together.
Built With
- ag
- compose
- docker
- fastapi
- flow
- github
- grid
- groq
- motion
- paypal
- playwright
- postgresql
- pydantic
- pytest
- python
- react
- typescript
- vite
