{"id":51503578,"url":"https://github.com/najahaja/mitchells-fruit-limited","last_synced_at":"2026-07-07T22:01:26.406Z","repository":{"id":360327335,"uuid":"1247695477","full_name":"najahaja/Mitchells-fruit-limited","owner":"najahaja","description":"AI Voice Agent Platform: FastAPI + React + Neon PostgreSQL + Retell AI","archived":false,"fork":false,"pushed_at":"2026-06-29T13:50:33.000Z","size":15771,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-29T15:25:16.488Z","etag":null,"topics":["e-commerce","fastapi","full-stack","pos-integration","psotgresql","react","retell-ai","voice-ai"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/najahaja.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-23T16:51:24.000Z","updated_at":"2026-06-29T13:50:55.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/najahaja/Mitchells-fruit-limited","commit_stats":null,"previous_names":["najahaja/mitchells-fruit-limited"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/najahaja/Mitchells-fruit-limited","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/najahaja%2FMitchells-fruit-limited","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/najahaja%2FMitchells-fruit-limited/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/najahaja%2FMitchells-fruit-limited/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/najahaja%2FMitchells-fruit-limited/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/najahaja","download_url":"https://codeload.github.com/najahaja/Mitchells-fruit-limited/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/najahaja%2FMitchells-fruit-limited/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35243953,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-07T02:00:07.222Z","response_time":90,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["e-commerce","fastapi","full-stack","pos-integration","psotgresql","react","retell-ai","voice-ai"],"created_at":"2026-07-07T22:01:25.628Z","updated_at":"2026-07-07T22:01:26.396Z","avatar_url":"https://github.com/najahaja.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Mitchell's Fruit Farms — Voice AI Sales Agent Platform\n\nA unified, full-stack platform that integrates a **Retell AI Voice Agent** with a serverless **Neon PostgreSQL Database** (with optional **POS System** integration) to automate inbound customer calls, B2B wholesale orders, international export inquiries, customer complaint logging, customer feedback, and callback requests for **Mitchell's Fruit Farms** (a historic and trusted food manufacturer in Pakistan since 1933).\n\n---\n\n## 📖 Project Overview\n\nThis repository consists of two main components:\n1. **`backend` (FastAPI Backend)**: Serves as the central API orchestrator. It manages database persistence, processes Retell AI webhook life cycle events (e.g., call completion, live state retrieval), auto-extracts order items and customer feedback from natural conversation transcripts, and maintains a product catalog. It operates seamlessly using a serverless **Neon PostgreSQL** database; integration with POS is entirely optional (when keys are configured, it syncs catalog items and pushes orders to POS with warehouse printing).\n2. **`frontend` (React + JavaScript Frontend)**: An admin dashboard portal designed to monitor call logs, play call recordings, read transcripts, review and edit order drafts, manage products/menu items, configure the voice agent settings, and view customer feedback.\n\n---\n\n## 🛠️ Tech Stack\n\n### Backend (`backend`)\n- **Framework**: FastAPI (Asynchronous Python)\n- **Database ORM**: SQLAlchemy 2.0 (Asyncio) with `asyncpg`\n- **Database**: PostgreSQL (Serverless via **Neon**)\n- **Migration \u0026 Schema Setup**: Automatic DDL migrations integrated directly into the application lifespan\n- **Voice Agent Gateway**: Retell AI REST API \u0026 Webhooks\n- **POS \u0026 Print Engine**: POS Merchant API (Optional)\n- **Auth**: JWT Bearer Tokens with `python-jose` and `passlib` for password hashing\n\n### Frontend (`frontend`)\n- **Runtime \u0026 Bundler**: React 19 + JavaScript + Vite\n- **Styling**: Tailwind CSS v4 with modern CSS configurations\n- **Icons**: Lucide React\n- **Routing**: React Router DOM v7\n- **HTTP Client**: Axios with interceptors for JWT injection\n\n---\n\n## 📂 Project Architecture\n\n```\nMitchell's/\n├── backend/                                 # FastAPI Backend Service\n│   ├── main.py                              # Application entry point with Lifespan \u0026 background tasks\n│   ├── requirements.txt                     # Backend python dependencies\n│   ├── retell_agent_config.json             # Pre-configured Retell Agent Conversation Graph\n│   ├── src/\n│   │   ├── api/                             # API Routers (auth, retell, menu, settings, prompts, outbound)\n│   │   ├── services/                        # Integrations (POS API client, Retell API client, Callback Scheduler)\n│   │   └── utils/                           # Core utilities (DB schemas, parsing logic, seed scripts)\n│   └── .env                                 # Backend configuration (ignored by Git)\n│\n├── frontend/                                # React + JavaScript Admin Portal\n│   ├── package.json                         # Node dependencies \u0026 npm scripts\n│   ├── index.html                           # Single page application entry point\n│   ├── src/\n│   │   ├── api/                             # Axios clients and API request modules\n│   │   ├── components/                      # Common UI components (Navbar, Modal, Loader)\n│   │   ├── pages/                           # Views (Login, Dashboard Overview, CallLogs, Menu, Settings, Outbound)\n│   │   └── App.jsx                          # App Routing and Private Route Guards\n│   └── .env                                 # Frontend base URL config (ignored by Git)\n```\n\n---\n\n## ⚙️ Key Features\n\n### 🎙️ 1. Retell AI Voice Agent Integration (\"Alex\")\n- Built using Retell's **Conversation Flow** engine. The agent responds to caller types programmatically (Consumer Inquiries, B2B Trade, Exports, Complaints, Callback requests).\n- **Dynamic Context Injection**: During inbound webhooks, the system queries the database to inject dynamic context, including:\n  - Custom user parameters (returning caller name, returning status).\n  - Business hours validation (verifying if warehouse/corporate operations are open in `Asia/Karachi` timezone).\n  - A serialized, up-to-date **Product Catalog** with pricing and active promotions.\n\n### 💳 2. Optional POS Sync \u0026 Atomic Order Processing\n- **Inventory Syncing (Optional)**: If configured, a background task runs every 5 minutes, fetching items from POS inventory API, filtering out internal/service SKUs (e.g., print-service, test-cards), and updating the local menu.\n- **Automated Order Creation (Optional)**: If POS is configured, the system submits line items to POS using the Atomic Orders endpoint, converting currency representations from float dollars to cents.\n- **Auto-Printing (Optional)**: Triggers physical printer events via POS print endpoints on order placement or manual reprint requests.\n- **Database Fallback**: If POS API credentials are omitted, the application runs fully and stores order drafts and the product catalog locally in the Neon PostgreSQL database.\n\n### 📝 3. Webhook, Parsing Engine \u0026 Feedback Loop\n- Automatically processes the `call_ended` and `call_analyzed` webhooks.\n- **Order Parsing**: Features a **Natural Language Processing Regex Parser** (`auto_extract_order_items`) that parses free-text conversation summaries to match items against the database, extracting numbers/quantities written before or after item names, resolving plural/singular variants, and drafting orders.\n- **Customer Feedback extraction**: Captures detailed customer feedback and 1-5 ratings natively through Retell's post-call analysis variables and stores them alongside the call logs.\n\n### 📞 4. Outbound Auto-Dialer \u0026 Callback Scheduler\n- **Background Scheduler**: A FastAPI background task (`start_recall_scheduler`) automatically checks the database every minute for any scheduled callbacks that are due.\n- **Retell Dispatcher**: Automatically initiates outbound phone calls to customers using Retell's outbound APIs, matching them with the appropriate outbound agent context.\n\n### 📊 5. Admin Management Dashboard\n- **Live Monitoring \u0026 Logs**: Allows listening to call recordings, reading full transcripts, and filtering call logs by status or order booking success. View gold-highlighted customer feedback cards and transcript analysis.\n- **Draft Review \u0026 Order Placement**: Enables agents to edit drafted orders extracted from calls and manually submit them to POS.\n- **Outbound Campaigns**: Create outbound dialing lists and trigger mass phone calls.\n- **Dynamic Configuration**: UI interface to modify business hours, timezone, greetings, and Retell voice parameters (temperature, speed, interruption sensitivity).\n- **Reporting Analytics**: Visual breakdown of calls/orders over time, repeat callers, and user sentiment.\n\n---\n\n## 🚀 Installation \u0026 Setup\n\n### Prerequisites\n- Python 3.10+\n- Node.js 18+\n- PostgreSQL Database\n\n---\n\n### 1. Database Setup (Neon PostgreSQL)\n\nWe use **Neon** (a serverless PostgreSQL platform) for our database. \n\n1. Sign up/Log in at [Neon](https://neon.tech/).\n2. Create a new project and database (e.g., `mitchells_db`).\n3. Copy the connection string from the Neon dashboard. It should look like this:\n   `postgresql://alex:password@ep-cool-fog-123456.us-east-2.aws.neon.tech/mitchells_db?sslmode=require`\n4. Add `+asyncpg` to the connection protocol when setting up your `DATABASE_URL` environment variable (e.g., `postgresql+asyncpg://alex:...`).\n\n---\n\n### 2. Backend Installation (`backend`)\n\n1. Navigate to the backend directory:\n   ```bash\n   cd backend\n   ```\n2. Create and activate a Python virtual environment:\n   ```bash\n   python -m venv .venv\n   # Windows:\n   .venv\\Scripts\\activate\n   # macOS/Linux:\n   source .venv/bin/activate\n   ```\n3. Install dependencies:\n   ```bash\n   pip install -r requirements.txt\n   ```\n4. Configure Environment Variables:\n   Create a `.env` file based on `.env.example`:\n   ```ini\n   # Database: Use your Neon PostgreSQL connection string (append +asyncpg to postgresql)\n   DATABASE_URL=postgresql+asyncpg://alex:password@ep-cool-fog-123456.us-east-2.aws.neon.tech/mitchells_db?sslmode=require\n   SECRET_KEY=your_super_secret_jwt_key\n   ALGORITHM=HS256\n   ACCESS_TOKEN_EXPIRE_MINUTES=200\n   REFRESH_TOKEN_EXPIRE_DAYS=7\n\n   RETELL_API_KEY=your_retell_api_key_here\n   RETELL_WEBHOOK_SECRET=your_retell_webhook_secret_here\n   RETELL_AGENT_ID=your_retell_agent_id_here\n   RETELL_CONVERSATION_FLOW_ID=your_retell_flow_id_here\n\n   CORS_ORIGINS=*\n\n   # POS Settings (Optional - leave empty or delete if not using POS API)\n   CLOVER_API_TOKEN=your_pos_token_here\n   CLOVER_MERCHANT_ID=your_pos_merchant_id_here\n   CLOVER_BASE_URL=https://api.clover.com/v3\n   CLOVER_ORDER_TYPE_ID=your_order_type_id\n   CLOVER_PRINTER_ID=your_printer_id\n   ```\n5. Seed Database (Optional - to insert mock data if POS is not configured):\n   ```bash\n   python -m src.utils.seed_mitchells_products\n   ```\n6. Run Backend Server:\n   ```bash\n   uvicorn main:app --reload --port 8000\n   ```\n\n---\n\n### 3. Frontend Installation (`frontend`)\n\n1. Navigate to the frontend directory:\n   ```bash\n   cd ../frontend\n   ```\n2. Install Node packages:\n   ```bash\n   npm install\n   ```\n3. Create a `.env` file:\n   ```ini\n   VITE_BASE_URL=http://localhost:8000/api\n   ```\n4. Run Development Server:\n   ```bash\n   npm run dev\n   ```\n5. Access the application at [http://localhost:5173](http://localhost:5173).\n\n---\n\n## 🧠 Key Challenges \u0026 Solutions\n\nDuring the implementation of this system, several technical challenges were encountered and resolved:\n\n### 1. Real-time NLP Transcription Parsing\n* **Challenge**: When a customer finishes a call, their order summary is sent as free-text (e.g., *\"two orange squashes and a Mixed Fruit Jam\"*). Mapping these strings to strict POS database models is error-prone.\n* **Solution**: Implemented `auto_extract_order_items`, which performs case-insensitive regex matching. It handles singularization (converting \"berries\" to \"berry\", \"jams\" to \"jam\") and uses bidirectional search patterns to capture quantity numbers written both before the item (e.g., `3x Mango Jam`) and after the item (e.g., `Mango Jam: 3`).\n\n### 2. Prompt Bloat vs. Context Limitations\n* **Challenge**: Passing the full product catalogue directly into the LLM system prompt for every call consumes excessive tokens and adds high latency to real-time conversations.\n* **Solution**: Developed a local SQL cache. The catalog data is fetched from the local PostgreSQL database (Neon), formatted compactly, and injected as a dynamic E.164-dependent variable *only* when the webhook triggers the inbound call.\n\n### 3. POS Integration \u0026 Financial Safety (Optional)\n* **Challenge**: POS APIs expect order line items in cents and will fail if price discrepancies exist between what the customer was quoted and what is sent to the POS, or if a sync fails mid-transit.\n* **Solution**: Configured database price-mapping functions (`get_menu_items_prices`). The app pulls current prices directly from verified SQL models in Neon, enforces clean float-to-int multiplication (dollars * 100), and records syncing failures so managers can review the drafts and perform manual overrides in the admin panel if using POS. If POS is not used, the system safely processes orders entirely within the Neon database.\n\n### 4. Timezone-Aware Operating States\n* **Challenge**: Orders should only be accepted if the warehouse is open. However, servers operate in UTC, while the client operates in Pakistan (`Asia/Karachi`).\n* **Solution**: Leveraged the `zoneinfo` module combined with dynamic database settings. During the inbound webhook, current local times are computed using the merchant's chosen timezone, evaluating open/closed business rules to adjust the voice agent's dialogue tree dynamically on the fly.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnajahaja%2Fmitchells-fruit-limited","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnajahaja%2Fmitchells-fruit-limited","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnajahaja%2Fmitchells-fruit-limited/lists"}