Skip to content
/ product-decoder Public

Product Decoder is designed to provide a seamless visual product recognition and metadata extraction experience. Simply upload a product photo, and instantly receive a wealth of structured information, including nutrition facts, price history, store availability, and more.

product-decoder-frontend.vercel.app
2 stars 0 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

WomB0ComB0/product-decoder

BranchesTags

Repository files navigation

Product Decoder

🚀 Unleash Product Insights: Visual Recognition for Nutrition, Price & More!

License Version Maintained Built with Bun TypeScript

Product Decoder is a cutting-edge monorepo application designed to provide a seamless visual product recognition and metadata extraction experience. Simply upload a product photo, and instantly receive a wealth of structured information, including nutrition facts, price history, store availability, and more.

🎥 Demo

See Product Decoder in action! Watch how easy it is to upload a product image and get instant, comprehensive insights:

2025-08-29.23-58-56.mov

Demo Highlights:

  • Intuitive drag-and-drop image upload
  • Real-time AI-powered product recognition
  • Instant display of nutrition facts, pricing, and availability
  • Seamless user experience with fast processing

📖 Table of Contents

🚀 Overview / Introduction

Product Decoder addresses the common challenge of quickly obtaining detailed information about physical products. In today's fast-paced world, consumers often need immediate access to data like nutritional values, pricing comparisons, or ingredient lists for health, budgeting, or ethical reasons. Manually searching for this information can be time-consuming and inefficient.

This application provides a simple, intuitive solution:

  • Purpose: To empower users with instant, comprehensive product insights directly from an image.
  • Goal: To simplify the process of gathering product data, making informed decisions easier for consumers, and providing a robust platform for data extraction.
  • Problem Solved: Eliminates the need for manual product searches by leveraging visual recognition and AI to automate data retrieval, reducing friction and improving access to critical product information.
  • Target Audience:
    • Health-conscious individuals looking for quick nutritional facts.
    • Budget shoppers comparing prices and store availability.
    • Anyone needing to quickly identify product details from an image.
    • Developers interested in a modern monorepo architecture for full-stack applications involving AI/image processing.

✨ Feature Highlights

Product Decoder offers a rich set of features designed for a seamless user experience and robust data processing.

  • Intuitive Image Uploads

    • ✅ Drag & drop functionality for effortless file submission.
    • ✅ Standard file selection dialog for broader compatibility.
    • ✅ Support for common image formats (JPEG, PNG, WEBP).

  • Advanced Image Analysis Pipeline

    • 🔍 Intelligent product recognition using AI models (details subject to backend implementation).
    • 🔍 Extraction of key product metadata (e.g., name, brand, category).
    • 🔍 Integration with external data sources for nutrition facts, price history, and store availability.
    • 💡 Tip: The analysis pipeline is designed to be extensible, allowing for future integration of more data providers.

  • Personalized User Dashboard

    • 🔒 Secure authentication powered by Clerk.
    • 📊 View and manage previously analyzed product scans.
    • 📈 Track product price history and availability over time.
    • ⭐ Save favorite products for quick access.

  • Modern Monorepo Architecture

    • 📦 Organized structure for frontend, backend, database, and shared packages.
    • ⚙️ Reusable code and components across different parts of the application.
    • 🚀 Optimized for performance and developer experience with Turbo and Bun.

  • Robust & Scalable Foundation

    • TypeScript-first codebase for type safety and maintainability.
    • Bun runtime for high-performance backend operations.
    • Next.js App Router for modern, server-rendered frontend experiences.
    • Prisma ORM for reliable database interactions.

🗺️ Architecture & Design

Product Decoder is built as a monorepo, organizing its various components into distinct, yet interconnected, packages. This approach enhances code sharing, consistency, and overall development efficiency.

High-Level Component Diagram

The following diagram illustrates the primary components of the Product Decoder system and their interactions.

graph TD
    A[User] --> B(Frontend - Next.js App)
    B --> C{API Gateway / Reverse Proxy}
    C --> D(Backend - Bun API)
    D --> E[External Services - AI/Data Providers]
    D --> F(Database - Prisma ORM)
    F --> G[Data Store - PostgreSQL/SQLite]

    subgraph Monorepo_Structure["Monorepo Structure"]
        B --- BPath["apps/frontend"]
        D --- DPath["apps/backend"]
        F --- FPath["packages/db"]
        H[Shared Utilities]
        H --- HPath["packages/shared"]
        B --> H
        D --> H
    end

    style A fill:#e0f7fa,stroke:#00796b,stroke-width:2px
    style B fill:#bbdefb,stroke:#2196f3,stroke-width:2px
    style C fill:#fff9c4,stroke:#ffeb3b,stroke-width:2px
    style D fill:#c8e6c9,stroke:#4caf50,stroke-width:2px
    style E fill:#f8bbd0,stroke:#e91e63,stroke-width:2px
    style F fill:#d7ccc8,stroke:#795548,stroke-width:2px
    style G fill:#f3e5f5,stroke:#9c27b0,stroke-width:2px
    style H fill:#ffecb3,stroke:#ffc107,stroke-width:2px
Loading

Explanation:

  • User: Interacts directly with the Frontend.
  • Frontend (Next.js App): The user interface, responsible for presenting data and handling user inputs like image uploads. It communicates with the Backend via API calls.
  • API Gateway / Reverse Proxy: Handles incoming requests, potentially routing them to the correct backend service and providing security (e.g., Vercel's edge functions, or a custom Nginx/Caddy setup).
  • Backend (Bun API): The core logic layer, handling API requests, orchestrating image analysis, interacting with external data sources, and managing database operations.
  • External Services (AI/Data Providers): Third-party APIs or internal microservices responsible for product recognition, OCR, nutrition data, pricing, etc.
  • Database (Prisma ORM): Provides an abstraction layer for interacting with the underlying data store, defining schemas, and managing migrations.
  • Data Store (PostgreSQL/SQLite): The actual persistent storage for product information, user data, and analysis results.

Module Responsibilities

The monorepo is structured into several key modules, each with distinct responsibilities:

  • apps/frontend (Next.js):
    • User Interface and User Experience.
    • Image upload and display logic.
    • Dashboard for authenticated users.
    • Handles client-side routing and data fetching.
    • Integrates Clerk for authentication UI.
  • apps/backend (Bun API):
    • RESTful API endpoints for image processing, data retrieval, and user interactions.
    • Orchestrates calls to AI/external data providers.
    • Handles server-side logic and business rules.
    • Serves as the main application server.
  • packages/db (Prisma):
    • Defines the database schema (schema.prisma).
    • Manages database migrations.
    • Provides the Prisma client for database interactions.
    • Includes seeding scripts for initial data.
  • packages/shared:
    • Contains common types, interfaces, and utility functions used across both frontend and backend.
    • Ensures type safety and consistency throughout the monorepo.
    • Includes configurations for common tools like Vitest.
  • packages/config-typescript:
    • Centralized TypeScript configurations to ensure consistent tsconfig.json settings across all projects (e.g., base.json, react-library.json, vite.json).
  • packages/logger:
    • A dedicated package for standardized logging across the monorepo, promoting consistent output and easier debugging.

Technology Stack

▶️ Getting Started

Follow these steps to get Product Decoder up and running on your local machine.

Prerequisites

Before you begin, ensure you have the following installed:

  • Bun: Recommended runtime and package manager.
    • Installation: Follow the instructions at bun.sh.
    • Version: ^1.1.0 (or latest stable)
    curl -fsSL https://bun.sh/install | bash
# or using npm
npm install -g bun
  • Git: For cloning the repository.
  • Node.js & npm/npx: (Optional) While Bun is preferred, some tooling or scripts might default to node or npx. Ensure you have a recent version installed (v18+ recommended).

Installation

  1. Clone the repository:

    git clone https://github.com/WomB0ComB0/product-decoder.git
cd product-decoder

  2. Install dependencies: From the root of the monorepo, use Bun to install all project dependencies. Turbo will optimize this process for workspaces.

    bun install

  3. Set up the database:

    • Development Database (SQLite): For local development, you can use SQLite. 
      cd packages/db
bun prisma migrate dev --name init
bun run seed
cd ../.. # Return to root
    • PostgreSQL (Production/Advanced Dev): If you prefer PostgreSQL locally, ensure you have a running instance and update your DATABASE_URL in the .env file (see Configuration). 
      # Example for PostgreSQL connection string
# DATABASE_URL="postgresql://user:password@localhost:5432/productdecoder"
cd packages/db
bun prisma migrate deploy # or migrate dev with a name for new changes
bun run seed
cd ../.. # Return to root

Configuration

Several applications in the monorepo expect environment variables or credential files.

  1. Copy example environment files:

    • From the project root, copy the .env.example to .env: 
      cp .env.example .env
    • For the backend app, copy its specific .env.example and credentials.json.example: 
      cp apps/backend/.env.example apps/backend/.env
cp apps/backend/credentials.json.example apps/backend/credentials.json
    • For the frontend app, copy its specific .env.example: 
      cp apps/frontend/.env.example apps/frontend/.env
    • For the db package, copy its specific .env.example: 
      cp packages/db/.env.example packages/db/.env

  2. Populate environment variables: Open the newly created .env and credentials.json files and fill in the required variables. Key variables often include:

    • DATABASE_URL (in packages/db/.env and apps/backend/.env)
    • CLERK_SECRET_KEY, NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY (in apps/frontend/.env)
    • API keys for external product data or AI services (in apps/backend/.env or apps/backend/credentials.json).
      • 💡 Tip: Refer to the respective *.env.example files for a complete list of variables.

Running the Application

Once dependencies are installed and configuration is set up, you can run the applications.

  1. Start the Frontend: Open a new terminal, navigate to the frontend directory, and start the development server:

    cd apps/frontend
bun run dev

    The frontend will typically be available at http://localhost:3000.

  2. Start the Backend: Open another terminal, navigate to the backend directory, and start the API server:

    cd apps/backend
bun run dev

    The backend API will typically be available at http://localhost:3001 (or the port specified in its .env).

    ⚠️ Important: Ensure both frontend and backend are running simultaneously for the application to function correctly.

(back to top)

📝 Usage & Workflows

Product Decoder is designed for straightforward interaction. Here's how to use it and understand its core workflows.

Core Workflow: Product Image Analysis

The primary use case for Product Decoder is to upload an image of a product and receive its decoded information.

  1. Access the Application: Navigate to the frontend in your web browser (e.g., http://localhost:3000).

  2. Upload Image:

    • Locate the image upload area on the homepage. This might be a drag-and-drop zone or a button labeled "Upload Image" / "Select File".
    • Drag & Drop: Drag a product image directly from your file explorer onto the designated area.
    • File Selection: Click the upload button to open a file dialog and select your image.

  3. Image Processing:

    • Once the image is uploaded, the frontend sends it to the backend.
    • The backend initiates an AI analysis pipeline to recognize the product and extract relevant data.
    • A loading indicator or progress bar will typically be shown during this process (AIAnalysisLoader.tsx).

  4. View Results:

    • After successful analysis, the application will display the extracted product information. This may include:
      • Product Name & Brand
      • Nutrition Facts
      • Price History
      • Store Availability
      • Ingredient Lists
      • Any other structured metadata.
sequenceDiagram
    participant User
    participant Frontend
    participant Backend
    participant ExternalAI as External AI/Data Providers
    participant Database

    User->>Frontend: Access Web App (e.g., `localhost:3000`)
    User->>Frontend: Upload Product Image (Drag & Drop / Select File)
    Frontend->>Backend: POST /api/v1/analyze-image (Image Data)
    Backend->>ExternalAI: Send Image for Recognition & Data Extraction
    ExternalAI-->>Backend: Return Raw Product Data (JSON)
    Backend->>Database: Store Raw & Processed Data
    Database-->>Backend: Confirmation
    Backend->>Backend: Process & Structure Data
    Backend-->>Frontend: Return Structured Product Data
    Frontend->>User: Display Product Information & Insights
Loading

Authenticated User Dashboard

For users who log in, Product Decoder provides a personalized dashboard experience:

  1. Login/Signup:

    • Use the "Login" or "Signup" links provided in the application UI (powered by Clerk).
    • After successful authentication, you will be redirected to your dashboard.

  2. Dashboard Features:

    • History: Access a history of all products you've previously analyzed.
    • Saved Items: View and manage products you've marked as favorites.
    • Trends: Potentially view trends in pricing or availability for frequently searched items.

CLI Commands

Here are some common commands you'll use when developing or running Product Decoder:

  • Install Dependencies (from root): 
    bun install
  • Run Frontend in Development Mode: 
    cd apps/frontend
bun run dev
  • Run Backend in Development Mode: 
    cd apps/backend
bun run dev
  • Build Frontend for Production: 
    cd apps/frontend
bun run build
  • Build Backend for Production: 
    cd apps/backend
bun run build
  • Run Database Migrations (e.g., packages/db): 
    cd packages/db
bun prisma migrate dev --name <migration_name> # For new migrations
bun prisma migrate deploy # For applying existing migrations
bun run seed # To seed the database
  • Run Tests (e.g., packages/shared): 
    cd packages/shared
bun test
# With coverage
bun test --coverage
  • Run Biome Linter/Formatter (from root): 
    bunx @biomejs/biome check --apply-unsafe .
bunx @biomejs/biome format --write .

(back to top)

🚧 Limitations, Known Issues & Future Roadmap

This section outlines the current state of the application, any known rough edges, and the exciting plans for its future.

Current Limitations

  • Image Quality Sensitivity: The accuracy of product recognition can be highly dependent on the quality, lighting, and angle of the uploaded image. Blurry or poorly lit images may yield inaccurate results.
  • Limited Product Database (Initial): The initial version might have a narrower scope of recognized products or rely on specific external data providers, meaning some niche products might not be found.
  • Performance on Large Volumes: While optimized, processing a very large number of high-resolution images simultaneously might strain resources, especially in development environments.
  • Authentication Scope: Clerk is integrated, but advanced features like role-based access control or multi-factor authentication might not be fully configured beyond basic user management.
  • Backend Scalability: The current backend setup using Bun is performant, but horizontal scaling considerations (e.g., load balancing, message queues for async tasks) would become critical for high-traffic production environments.

Known Issues

  • First-time Backend Startup Delay: Due to JIT compilation in Bun or initial database connection, the first API call to the backend might experience a slight delay.
  • Missing API Keys: The backend will not function without valid API keys for external services. Ensure apps/backend/.env and credentials.json are correctly populated.
  • CORS Issues: In certain development setups, CORS issues might arise between the frontend and backend if not properly configured (e.g., if running on different domains/ports without explicit CORS headers). The Vercel setup should mitigate this for deployments.

Future Roadmap & Planned Enhancements

We have exciting plans to expand the capabilities and improve the user experience of Product Decoder:

  • Advanced AI Integrations:
    • ✅ Integrate with more sophisticated OCR (Optical Character Recognition) services for better text extraction from product labels.
    • ✅ Explore advanced computer vision models for ingredient recognition and allergen identification.
  • Expanded Data Sources:
    • 🚀 Integrate with a wider array of public and commercial APIs for comprehensive price comparison across more retailers.
    • 🚀 Add support for region-specific product availability and regulatory information.
  • User Interaction & Experience:
    • ✨ Implement "compare product" functionality.
    • ✨ Add user reviews and ratings for products.
    • ✨ Improve error handling and user feedback during the analysis pipeline.
    • ✨ Mobile responsiveness enhancements and potentially native mobile app versions.
  • Monorepo Evolution:
    • ⚙️ Further optimize Turbo cache configurations for even faster CI/CD pipelines.
    • ⚙️ Explore integrating more shared UI components and design systems across apps.
  • Analytics & Insights:
    • 📊 Provide more in-depth historical data visualizations on the dashboard.
    • 📊 Implement trend analysis for product categories.
  • Community & Extensibility:
    • 🌐 Open-source some core AI models or provide guidelines for community contributions to product data.

Feature Requests

Have an idea for a new feature? We'd love to hear it!

  • Open an issue on GitHub with the label feature-request.
  • Clearly describe your idea and its potential benefits.

(back to top)

🤝 Contributing & Development Guidelines

We welcome contributions from the community! By following these guidelines, you can help us maintain a high-quality codebase and a collaborative environment.

How to Contribute

  1. Fork the repository: Start by forking the WomB0ComB0/product-decoder repository to your own GitHub account.
  2. Clone your fork: 
    git clone https://github.com/YOUR_GITHUB_USERNAME/product-decoder.git
cd product-decoder
  3. Install dependencies: Refer to the Installation section.
  4. Create a new branch: For each new feature or bug fix, create a new branch from main. 
    git checkout -b feature/your-feature-name-or-issue-id
  5. Make your changes: Implement your feature or fix the bug.
  6. Test your changes: Ensure your changes are well-tested (see Code Style, Linting & Testing).
  7. Commit your changes: Write clear and concise commit messages. 
    git commit -m "feat: Add new awesome feature"
# or
git commit -m "fix: Resolve critical bug in product analysis"
  8. Push your branch: 
    git push origin feature/your-feature-name-or-issue-id
  9. Open a Pull Request (PR):
    • Go to your fork on GitHub and open a PR to the main branch of the original repository.
    • Provide a descriptive title and detailed explanation of your changes.
    • Reference any related issues (e.g., Fixes #123, Closes #456).

Branching & Pull Request Guidelines

  • Branch Naming: Use feature/, bugfix/, chore/, or refactor/ prefixes (e.g., feature/dashboard-improvements, bugfix/image-upload-issue).
  • PR Titles: Use Conventional Commits for PR titles (e.g., feat(frontend): Implement drag and drop upload).
  • Description: Clearly explain what the PR does, why it's needed, and how it was tested.
  • Review: Be responsive to feedback during the review process.

Code Style, Linting & Testing

  • Code Style: We use Biome for formatting and linting. Before committing, ensure your code adheres to the defined style: 
    bunx @biomejs/biome check --apply-unsafe .
bunx @biomejs/biome format --write .
  • TypeScript: All new code should be written in TypeScript, ensuring strong typing and better maintainability.
  • Testing:
    • Unit Tests: Write unit tests for new features and bug fixes, primarily using Vitest (especially in packages/shared).
    • Integration Tests: For complex interactions between modules, consider integration tests.
    • E2E Tests: The apps/frontend directory includes setups for Cypress and Playwright for end-to-end testing of core user flows. Add or update these tests as needed.
    # Example: Run tests for a specific package
cd packages/shared && bun test
cd apps/frontend && bun cypress run # for Cypress

Development Setup

  • IDE: VS Code is recommended with the following extensions:
  • Bun Version Manager (if needed): While Bun is self-updating, bunenv can be used for managing multiple Bun versions.
  • Environment Variables: Double-check all .env and credentials.json files for correct values during development. Use console.log or a debugger to verify if needed.

(back to top)

📜 License, Credits & Contact

License

Product Decoder is distributed under the Apache License, Version 2.0.

Copyright 2025 Product Decoder

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

A copy of the full license text can be found in the LICENSE file at the root of the repository.

Acknowledgments

We are grateful to the creators and maintainers of the following open-source projects and services that make Product Decoder possible:

Maintainer & Contact

Product Decoder is currently maintained by WomB0ComB0.

For general inquiries, bug reports, or feature requests, please open an issue on the GitHub repository.

(back to top)

📚 Appendix

Changelog

View recent updates

v0.1.0 - Initial Release (YYYY-MM-DD)

  • Initial monorepo setup with Next.js frontend, Bun backend, Prisma DB.
  • Basic image upload and display.
  • Placeholder for AI analysis pipeline.
  • Clerk authentication integration for dashboard.
  • Comprehensive development environment setup with Bun, Turbo, Biome.

FAQ (Frequently Asked Questions)

Q: What is the recommended way to install dependencies?

A: We highly recommend using bun install from the root of the monorepo. Bun is optimized for monorepos and generally faster than npm or yarn.

Q: I'm getting an error about missing environment variables. What should I do?

A: Ensure you have copied all .env.example files to .env in the root, apps/frontend, apps/backend, and packages/db. Then, open these .env files and populate them with your specific keys (e.g., DATABASE_URL, CLERK_SECRET_KEY). Also check apps/backend/credentials.json.

Q: Can I use Node.js instead of Bun?

A: While Node.js is generally compatible, Bun is the recommended runtime and package manager for this project due to its performance benefits and specific ecosystem integrations (e.g., ElysiaJS). Some scripts might default to node or npx, but the core applications are intended to run with Bun.

Q: How do I run tests for a specific package?

A: Navigate into the package directory (e.g., cd packages/shared) and then run bun test. You can also run bun test --coverage to view test coverage reports.

Troubleshooting

Issue: Frontend isn't loading or showing "connection refused".

Solution:

  1. Check Backend: Ensure your backend (apps/backend) is running correctly without errors. The frontend relies on the backend API.
  2. API URL: Verify that the NEXT_PUBLIC_API_URL (or similar) environment variable in apps/frontend/.env points to the correct backend address (e.g., http://localhost:3001).
  3. Ports: Make sure no other applications are using ports 3000 (frontend) or 3001 (backend).
Issue: Image upload fails or "analysis error".

Solution:

  1. Backend Logs: Check the terminal where apps/backend is running for any error messages. This will often indicate issues with external API calls, invalid credentials, or processing failures.
  2. API Keys: Double-check that all required API keys for external AI/data services in apps/backend/.env and apps/backend/credentials.json are valid and correctly entered.
  3. Image Size/Format: Ensure the image you're uploading is a standard format (JPEG, PNG, WEBP) and not excessively large.
Issue: Database connection error.

Solution:

  1. DATABASE_URL: Verify the DATABASE_URL in packages/db/.env and apps/backend/.env is correct.
  2. Database Server: If using PostgreSQL, ensure your PostgreSQL server is running and accessible from your machine.
  3. Migrations: Run cd packages/db && bun prisma migrate dev --name init (for initial setup) or bun prisma migrate deploy to ensure your database schema is up-to-date.

API Reference

Detailed API documentation is planned for future releases. For now, you can explore the backend API routes by examining the apps/backend/src and apps/frontend/src/app/api/v1 directories.

  • apps/backend/src/app.ts: Defines the main ElysiaJS application.
  • apps/frontend/src/app/api/v1/[[...route]]/elysia.ts: This file sets up the ElysiaJS router for the frontend's API routes, giving insight into available endpoints.

(back to top)

About

Product Decoder is designed to provide a seamless visual product recognition and metadata extraction experience. Simply upload a product photo, and instantly receive a wealth of structured information, including nutrition facts, price history, store availability, and more.

product-decoder-frontend.vercel.app

Topics

typescript nextjs monorepo web-application image-recognition bun prisma tailwindcss

Resources

Readme

Security policy

Security policy
Activity

Stars

2 stars

Watchers

1 watching

Forks

0 forks
Report repository

Contributors 3

  •  
  •  
  •  

Languages