{"id":28996782,"url":"https://github.com/hunkim/img2excel","last_synced_at":"2025-10-10T13:05:04.510Z","repository":{"id":299151132,"uuid":"1002143906","full_name":"hunkim/img2excel","owner":"hunkim","description":null,"archived":false,"fork":false,"pushed_at":"2025-06-17T17:35:13.000Z","size":11351,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-25T05:11:35.592Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://img2excel-omega.vercel.app","language":"TypeScript","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/hunkim.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}},"created_at":"2025-06-14T20:08:43.000Z","updated_at":"2025-06-17T17:35:15.000Z","dependencies_parsed_at":"2025-06-15T01:32:28.279Z","dependency_job_id":null,"html_url":"https://github.com/hunkim/img2excel","commit_stats":null,"previous_names":["hunkim/img2excel"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/hunkim/img2excel","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hunkim%2Fimg2excel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hunkim%2Fimg2excel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hunkim%2Fimg2excel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hunkim%2Fimg2excel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hunkim","download_url":"https://codeload.github.com/hunkim/img2excel/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hunkim%2Fimg2excel/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279004005,"owners_count":26083661,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-10T02:00:06.843Z","response_time":62,"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":[],"created_at":"2025-06-25T05:11:30.773Z","updated_at":"2025-10-10T13:05:04.488Z","avatar_url":"https://github.com/hunkim.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# img2excel - AI-Powered Image to Spreadsheet Converter\n\n**Never Manually Type Data Again.** Turn any image with data into an editable spreadsheet instantly using AI.\n\n[![Version](https://img.shields.io/badge/version-0.3-blue.svg)](https://github.com/hunkim/img2excel)\n[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n[![Powered by Upstage](https://img.shields.io/badge/powered%20by-Upstage%20AI-orange.svg)](https://www.upstage.ai/)\n\n## ✨ Features\n\n- 🤖 **AI-Powered**: Uses [Upstage AI](https://console.upstage.ai/docs/capabilities/information-extraction/universal-information-extraction) for intelligent schema generation and data extraction\n- 📸 **Smart Schema Detection**: Automatically detects data structure from your first image\n- 🔄 **Adaptive Extraction**: Uses your custom column headers as schema for subsequent images\n- 📊 **Real-time Editing**: Edit extracted data in a spreadsheet interface\n- 💾 **Project Management**: Save and manage multiple projects with Firebase\n- 🔐 **Authentication**: Google Sign-in for project persistence\n- 📱 **Responsive Design**: Works on desktop and mobile\n- 🎯 **Multiple Formats**: Supports receipts, tables, invoices, lists, and more\n- 📈 **CSV Export**: Download your data as CSV files\n- 🐛 **Issue Reporting**: Built-in GitHub issue reporting\n\n## 🏗️ Architecture Overview\n\n```mermaid\ngraph TB\n    subgraph \"Frontend (Next.js 15)\"\n        A[Landing Page] --\u003e B[Image Upload]\n        B --\u003e C[Editor Page]\n        C --\u003e D[Spreadsheet Interface]\n        D --\u003e E[CSV Export]\n    end\n    \n    subgraph \"State Management\"\n        F[Zustand Store] --\u003e G[Project State]\n        F --\u003e H[Image Columns]\n        F --\u003e I[Schema Keys]\n    end\n    \n    subgraph \"Backend Services\"\n        J[Upstage AI] --\u003e K[Schema Generation]\n        J --\u003e L[Information Extraction]\n        M[Firebase] --\u003e N[Authentication]\n        M --\u003e O[Firestore DB]\n        M --\u003e P[Storage]\n    end\n    \n    C --\u003e F\n    B --\u003e J\n    C --\u003e M\n    \n    style A fill:#e1f5fe\n    style C fill:#e8f5e8\n    style J fill:#fff3e0\n    style M fill:#fce4ec\n```\n\n## 🔄 Business Logic Flow\n\n```mermaid\nsequenceDiagram\n    participant U as User\n    participant UI as Frontend\n    participant S as Store\n    participant AI as Upstage AI\n    participant FB as Firebase\n    \n    U-\u003e\u003eUI: Upload First Image\n    UI-\u003e\u003eS: addImageColumn(file, userId?)\n    S-\u003e\u003eAI: Generate Schema\n    AI--\u003e\u003eS: Schema Fields\n    S-\u003e\u003eAI: Generate Title\n    AI--\u003e\u003eS: Meaningful Title\n    \n    alt User Logged In\n        S-\u003e\u003eFB: Save Project Template\n        FB--\u003e\u003eS: Project ID\n    end\n    \n    S-\u003e\u003eAI: Extract Information\n    AI--\u003e\u003eS: Extracted Data\n    S-\u003e\u003eUI: Update Spreadsheet\n    \n    U-\u003e\u003eUI: Upload Additional Images\n    UI-\u003e\u003eS: addImageColumn(file, userId?)\n    S-\u003e\u003eAI: Extract with Existing Schema\n    AI--\u003e\u003eS: Extracted Data\n    \n    alt User Logged In\n        S-\u003e\u003eFB: Update Project\n    end\n    \n    U-\u003e\u003eUI: Export CSV\n    UI-\u003e\u003eU: Download File\n```\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- Node.js 18+ and npm/pnpm\n- [Upstage AI API Key](https://console.upstage.ai/)\n- [Firebase Project](https://console.firebase.google.com/) (optional, for project persistence)\n\n### Installation\n\n1. **Clone and Install**:\n   ```bash\n   git clone https://github.com/hunkim/img2excel.git\n   cd img2excel\n   npm install --legacy-peer-deps\n   ```\n\n2. **Configure Environment**:\n   Create `.env.local` in the root directory:\n   ```env\n   # Required: Upstage AI API Key\n   UPSTAGE_API_KEY=your_upstage_api_key_here\n   \n   # Optional: Firebase Configuration (for project persistence)\n   NEXT_PUBLIC_FIREBASE_API_KEY=your_firebase_api_key\n   NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your_project.firebaseapp.com\n   NEXT_PUBLIC_FIREBASE_PROJECT_ID=your_project_id\n   NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your_project.appspot.com\n   NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=123456789\n   NEXT_PUBLIC_FIREBASE_APP_ID=1:123456789:web:abcdef\n   \n   # Optional: Rate Limiting Configuration\n   ANONYMOUS_RATE_LIMIT=60        # Requests per hour for non-logged users\n   AUTHENTICATED_RATE_LIMIT=240   # Requests per hour for logged users  \n   RATE_LIMIT_WINDOW_MS=3600000   # Time window in milliseconds (1 hour)\n   ```\n\n3. **Run Development Server**:\n   ```bash\n   npm run dev\n   ```\n\n4. **Open Application**:\n   Visit `http://localhost:3000`\n\n## 📋 Usage Examples\n\n### 📄 Receipt Processing\n1. Upload a receipt image\n2. AI detects: \"Item Name\", \"Price\", \"Category\"\n3. Add more receipts - they follow the same schema\n4. Export to CSV for expense tracking\n\n### 🧾 Invoice Processing\n1. Upload an invoice\n2. AI detects: \"Description\", \"Quantity\", \"Unit Price\", \"Total\"\n3. Process multiple invoices consistently\n4. Export for accounting\n\n### 📊 Table Digitization\n1. Upload a photo of a table/list\n2. AI detects column structure\n3. Add similar tables with consistent extraction\n4. Export structured data\n\n## 🔧 API Integration\n\n### Schema Generation API\n```typescript\nPOST /api/schema-generation\nContent-Type: application/json\n\n{\n  \"imageUrl\": \"data:image/jpeg;base64,...\"\n}\n```\n\n### Information Extraction API\n```typescript\nPOST /api/information-extraction\nContent-Type: application/json\n\n{\n  \"imageUrl\": \"data:image/jpeg;base64,...\",\n  \"schema\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"field_name\": {\n        \"type\": \"string\",\n        \"description\": \"Field description\"\n      }\n    }\n  }\n}\n```\n\n### Schema Naming API\n```typescript\nPOST /api/schema-naming\nContent-Type: application/json\n\n{\n  \"fieldNames\": [\"field1\", \"field2\", \"field3\"]\n}\n```\n\n## 🏛️ Tech Stack\n\n- **Framework**: Next.js 15 with React 19\n- **Language**: TypeScript\n- **Styling**: Tailwind CSS + shadcn/ui\n- **State Management**: Zustand\n- **Authentication**: Firebase Auth\n- **Database**: Firestore\n- **Storage**: Firebase Storage\n- **AI Service**: Upstage AI Agentic Information Extraction\n- **Deployment**: Vercel\n\n## 📁 Project Structure\n\n```\n├── app/\n│   ├── api/                    # API routes\n│   │   ├── schema-generation/  # AI schema generation\n│   │   ├── information-extraction/ # AI data extraction\n│   │   └── schema-naming/      # AI title generation\n│   ├── editor/                 # Spreadsheet editor page\n│   ├── globals.css            # Global styles\n│   ├── layout.tsx             # Root layout\n│   └── page.tsx               # Landing page\n├── components/\n│   ├── ui/                    # shadcn/ui components\n│   ├── auth-button.tsx        # Authentication component\n│   ├── image-uploader.tsx     # Drag \u0026 drop upload\n│   ├── projects-sidebar.tsx   # Project management\n│   └── ...                    # Other components\n├── lib/\n│   ├── firebase-service.ts    # Firebase operations\n│   ├── upstage-service.ts     # AI API integration\n│   └── utils.ts               # Utility functions\n├── store/\n│   └── spreadsheet-store.ts   # Zustand state management\n├── hooks/\n│   └── useAuth.ts             # Authentication hook\n└── public/                    # Static assets\n```\n\n## 🔄 v0.3 Improvements\n\n### 📱 Mobile-First Responsive Design\n- ✅ **Complete Mobile Optimization**: Fully responsive design while preserving desktop experience\n- ✅ **Touch-Friendly Interface**: Proper touch targets and mobile interactions throughout\n- ✅ **Smart Sidebar Behavior**: Closed by default on mobile, auto-opens on desktop with projects\n- ✅ **Adaptive Layouts**: Responsive sizing for all components (thumbnails, tables, forms)\n- ✅ **Enhanced Typography**: Custom breakpoints with scaled text for optimal mobile readability\n- ✅ **Performance Optimizations**: Touch manipulation CSS and efficient mobile rendering\n\n### 🎯 Mobile UX Improvements\n- ✅ **Overlay Interactions**: Tap outside to close sidebars on mobile\n- ✅ **Condensed UI**: Hidden non-essential elements on small screens\n- ✅ **Better Spacing**: Optimized padding and margins for touch interfaces\n- ✅ **Responsive Icons**: Appropriately scaled icon sizes across breakpoints\n- ✅ **Mobile-First Table**: Horizontal scrolling with touch-friendly cells\n- ✅ **Progressive Enhancement**: Graceful scaling from mobile (320px) to desktop\n\n## 🔄 v0.2 Improvements\n\n### DRY (Don't Repeat Yourself) Refactoring\n- ✅ **Eliminated Redundancy**: Removed 200+ lines of duplicate code\n- ✅ **Unified Image Processing**: Single flow for all image uploads\n- ✅ **Consolidated Save Logic**: 3 Firebase functions → 1 `saveProject` function\n- ✅ **Simplified Authentication**: Clear pattern (logged in = save, not logged in = local only)\n\n### Code Quality Improvements\n- ✅ **Clean Logging**: 80% reduction in verbose console output\n- ✅ **Better Error Handling**: Essential error logging preserved\n- ✅ **Single Responsibility**: Each function has one clear purpose\n- ✅ **Production Ready**: No sensitive data in logs\n\n### User Experience Enhancements\n- ✅ **Report Issues**: Bug report icons linking to GitHub\n- ✅ **Consistent Behavior**: Same upload flow everywhere\n- ✅ **Better Performance**: Reduced string processing and console I/O\n\n## 🌍 Environment Variables\n\n| Variable | Description | Required | Default |\n|----------|-------------|----------|---------|\n| `UPSTAGE_API_KEY` | Your Upstage AI API key | ✅ | - |\n| `ANONYMOUS_RATE_LIMIT` | Rate limit for non-logged in users (requests/hour) | ❌ | 60 |\n| `AUTHENTICATED_RATE_LIMIT` | Rate limit for logged in users (requests/hour) | ❌ | 240 |\n| `RATE_LIMIT_WINDOW_MS` | Rate limit time window in milliseconds | ❌ | 3600000 |\n| `NEXT_PUBLIC_FIREBASE_API_KEY` | Firebase API key | ⚠️ Optional* |\n| `NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN` | Firebase auth domain | ⚠️ Optional* |\n| `NEXT_PUBLIC_FIREBASE_PROJECT_ID` | Firebase project ID | ⚠️ Optional* |\n| `NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET` | Firebase storage bucket | ⚠️ Optional* |\n| `NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID` | Firebase messaging sender ID | ⚠️ Optional* |\n| `NEXT_PUBLIC_FIREBASE_APP_ID` | Firebase app ID | ⚠️ Optional* |\n\n*Firebase variables are optional. Without them, the app works in local-only mode (no project persistence).\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Test thoroughly\n5. Commit your changes (`git commit -m 'Add amazing feature'`)\n6. Push to the branch (`git push origin feature/amazing-feature`)\n7. Open a Pull Request\n\n### 🐛 Reporting Issues\n\nFound a bug or have a feature request? Please use the built-in issue reporting button in the app header, or visit our [GitHub Issues](https://github.com/hunkim/img2excel/issues) page.\n\n## 📄 License\n\nMIT License - feel free to use for personal or commercial projects.\n\n## 🙏 Acknowledgments\n\n- **[Upstage AI](https://www.upstage.ai/)** - For providing the powerful Agentic Information Extraction API\n- **[Vercel](https://vercel.com/)** - For seamless deployment and hosting\n- **[Firebase](https://firebase.google.com/)** - For authentication and data storage\n- **[shadcn/ui](https://ui.shadcn.com/)** - For beautiful, accessible UI components\n\n---\n\n**Built with ❤️ for productivity** | [Report Issues](https://github.com/hunkim/img2excel/issues) | [Documentation](https://github.com/hunkim/img2excel) ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhunkim%2Fimg2excel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhunkim%2Fimg2excel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhunkim%2Fimg2excel/lists"}