{"id":51102013,"url":"https://github.com/Dhuvie/Card-Orchestration","last_synced_at":"2026-07-12T16:01:03.163Z","repository":{"id":366451263,"uuid":"1276320615","full_name":"Dhuvie/Card-Orchestration","owner":"Dhuvie","description":"An AI-powered CRM orchestration platform that automatically extracts, enriches, and stores business card contacts using multimodal AI (Gemini Vision \u0026 Audio). Built with a LangGraph state machine, it features duplicate detection, web enrichment, Google Sheets integration, and automated WhatsApp notifications.","archived":false,"fork":false,"pushed_at":"2026-06-23T06:23:02.000Z","size":70,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-09T13:22:24.017Z","etag":null,"topics":["agentic-workflows","artificial-intelligence","automation","computer-vision","crm-system","fastapi","gemini-api","langgraph","mongodb","ocr","react","twilio-api"],"latest_commit_sha":null,"homepage":"https://card-orchestration-b6ov.vercel.app/","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/Dhuvie.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-06-21T20:40:32.000Z","updated_at":"2026-06-23T06:23:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Dhuvie/Card-Orchestration","commit_stats":null,"previous_names":["dhuvie/card-orchestration"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Dhuvie/Card-Orchestration","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dhuvie%2FCard-Orchestration","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dhuvie%2FCard-Orchestration/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dhuvie%2FCard-Orchestration/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dhuvie%2FCard-Orchestration/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Dhuvie","download_url":"https://codeload.github.com/Dhuvie/Card-Orchestration/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dhuvie%2FCard-Orchestration/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35395749,"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-12T02:00:06.386Z","response_time":87,"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":["agentic-workflows","artificial-intelligence","automation","computer-vision","crm-system","fastapi","gemini-api","langgraph","mongodb","ocr","react","twilio-api"],"created_at":"2026-06-24T12:00:22.053Z","updated_at":"2026-07-12T16:01:03.152Z","avatar_url":"https://github.com/Dhuvie.png","language":"Python","funding_links":[],"categories":["What's Inside"],"sub_categories":[],"readme":"# CRM Orchestration System (Contact Digitization Platform)\n\nAn end-to-end automated CRM digitization platform that uses computer vision and natural language processing to extract, enrich, and save business card contacts into a Google Sheet while providing real-time WhatsApp notifications to managers. \n\nThis platform uses **LangGraph** for resilient stateful workflow orchestration and **Gemini 2.5 Flash Lite** for both vision (image OCR) and native multimodal audio transcription.\n\n---\n\n## Architectural Overview (LangGraph Agent)\n\nThe core logic of the CRM Orchestration System is orchestrated via a fully stateful, cyclic graph built on **LangGraph**. It utilizes a finite state machine to manage human-in-the-loop interactions.\n\n### Agent Workflow (Node by Node)\n1. **`process_input`**: The router node. It reads the incoming message from the React UI. If it's an image, it routes to `extract_vision`. If audio, to `process_audio`. If text, it evaluates whether the user is confirming a pending extraction or simply chatting.\n2. **`extract_vision`**: Receives a Base64 encoded image of a business card. Leverages Gemini 2.5 Flash Lite (with structured Pydantic outputs and cascading fallbacks) to extract Name, Company, Email, and Phone.\n3. **`deduplicate_contact`**: Connects to Google Sheets and checks if the extracted email or phone number already exists in the CRM. If a duplicate is found, the graph gracefully halts and notifies the user.\n4. **`enrich_contact`**: Using the extracted company name, the agent performs a secondary LLM inference to automatically find or guess the company's official Website and LinkedIn profile URL.\n5. **`save_to_sheets`**: Pauses the graph to await human confirmation. Once approved by the user, this node appends the structured data (including enriched URLs) to the Google Sheet.\n6. **`send_whatsapp`**: Fires a WhatsApp notification to the assigned manager alerting them of the newly saved contact via the Meta/Twilio Business API.\n7. **`process_audio`**: An asynchronous side-loop. Listens to Base64 audio voice notes, natively transcribes them using Gemini's multimodal engine, summarizes the context, and attaches the transcript to the saved contact in the database.\n\n**Checkpointing**: The entire LangGraph state is persisted using a local `MongoDB` instance. This guarantees that if the server crashes while awaiting human approval, the state is preserved and the session resumes seamlessly.\n\n---\n\n## Environment Variables Setup\n\nBefore running the project, you must set up your credentials. In the `backend` directory, duplicate the `.env.example` file and rename it to `.env`. \n\n```env\n# MongoDB (Leave as is for local Docker deployment)\nMONGODB_URL=mongodb://mongo:27017\n\n# Google Core (Gemini)\nGOOGLE_API_KEY=your_gemini_api_key_here\n\n# Google Sheets Configuration\nGOOGLE_SHEET_ID=your_spreadsheet_id_here\nGOOGLE_SHEETS_CREDENTIALS={\"type\":\"service_account\", ...} # Minified JSON string\n\n# WhatsApp Business API (Meta Developer Portal or Twilio Sandbox)\nWHATSAPP_TOKEN=your_whatsapp_bearer_token\nWHATSAPP_PHONE_ID=your_whatsapp_phone_number_id\nWHATSAPP_MANAGER_PHONE=+1234567890\n```\n\n### Note on Google Sheets:\nEnsure your target Google Sheet has been \"Shared\" with the `client_email` address found inside your `GOOGLE_SHEETS_CREDENTIALS` JSON. The system will automatically generate header columns if the sheet is empty.\n\n---\n\n## Build, Run, and Test Locally\n\nThis project is fully containerized using Docker, allowing you to run the frontend, backend, and MongoDB checkpointer simultaneously with a single command.\n\n### Prerequisites:\n- Docker Desktop installed and running.\n\n### 1. Build and Run the Containers\nOpen your terminal at the root of the project and execute:\n```bash\ndocker compose up --build\n```\nThis command will pull the necessary images, install all Python/Node dependencies, compile the Vite frontend using SWC, and start the local network.\n\n### 2. Access the Platform\n- **Frontend (React UI)**: Open your browser to `http://localhost:5173`\n- **Backend (FastAPI)**: Open your browser to `http://localhost:8000/docs` to view the interactive Swagger API documentation.\n\n### 3. Testing the Workflow\n1. Open the Frontend UI.\n2. Drag and drop a business card image into the chat input.\n3. Wait for the system to extract the text and enrich the data.\n4. Review the returned payload. Type \"Yes\" to approve.\n5. Check your Google Sheet to verify the new row has been appended.\n6. Click the microphone icon to record a voice note, and verify the transcript is attached to the spreadsheet row.\n\n---\n\n## Deployment Guide\n\nBecause the application is stateless at the container level and relies on MongoDB for state management, it is perfectly suited for modern cloud hosting.\n\n### 1. Deploying the Backend (GCP Cloud Run)\nGoogle Cloud Run is highly recommended for the FastAPI backend as it scales to zero.\n1. Authenticate with GCP CLI: `gcloud auth login`\n2. Submit the backend build to Google Artifact Registry.\n3. Deploy the container:\n   ```bash\n   gcloud run deploy crm-backend \\\n     --source ./backend \\\n     --port 8000 \\\n     --set-env-vars MONGODB_URL=\"your_atlas_uri\",GOOGLE_API_KEY=\"...\" \\\n     --allow-unauthenticated\n   ```\n*(Ensure you use a MongoDB Atlas URI for production instead of the local Docker network).*\n\n### 2. Deploying the Frontend (Vercel / Netlify)\n1. Navigate to your hosting provider (e.g., Vercel).\n2. Link your Git repository and set the Root Directory to `frontend`.\n3. Set the Framework Preset to `Vite`.\n4. Add an environment variable `VITE_API_URL` pointing to your newly deployed Cloud Run backend URL.\n5. Click **Deploy**.\n\nYour CRM Orchestration System is now live and globally accessible.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FDhuvie%2FCard-Orchestration","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FDhuvie%2FCard-Orchestration","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FDhuvie%2FCard-Orchestration/lists"}