{"id":46391653,"url":"https://github.com/idrisakintobi/salespider","last_synced_at":"2026-03-05T09:02:05.581Z","repository":{"id":294901777,"uuid":"988227099","full_name":"IdrisAkintobi/SaleSpider","owner":"IdrisAkintobi","description":"Salespider is a store inventory, sales, and staff management system","archived":false,"fork":false,"pushed_at":"2025-12-15T09:17:39.000Z","size":4395,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-12-18T08:11:39.723Z","etag":null,"topics":["ai-insights","inventory-management","nextjs","pos-system","postgresql","retail","sales-management","typescript"],"latest_commit_sha":null,"homepage":"https://idrisakintobi.github.io/SaleSpider/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/IdrisAkintobi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":"audit-ci.json","citation":null,"codeowners":null,"security":".github/SECURITY_SETUP.md","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":"2025-05-22T08:36:42.000Z","updated_at":"2025-12-15T09:17:45.000Z","dependencies_parsed_at":"2025-12-08T22:09:09.865Z","dependency_job_id":null,"html_url":"https://github.com/IdrisAkintobi/SaleSpider","commit_stats":null,"previous_names":["idrisakintobi/salespider"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/IdrisAkintobi/SaleSpider","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IdrisAkintobi%2FSaleSpider","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IdrisAkintobi%2FSaleSpider/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IdrisAkintobi%2FSaleSpider/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IdrisAkintobi%2FSaleSpider/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/IdrisAkintobi","download_url":"https://codeload.github.com/IdrisAkintobi/SaleSpider/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IdrisAkintobi%2FSaleSpider/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30117480,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-05T08:19:04.902Z","status":"ssl_error","status_checked_at":"2026-03-05T08:17:37.148Z","response_time":93,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["ai-insights","inventory-management","nextjs","pos-system","postgresql","retail","sales-management","typescript"],"created_at":"2026-03-05T09:02:04.907Z","updated_at":"2026-03-05T09:02:05.540Z","avatar_url":"https://github.com/IdrisAkintobi.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SaleSpider - Smart Inventory \u0026 Sales Management\n\nSaleSpider is a modern, Next.js-based application designed for small and medium-sized stores to streamline sales, manage inventory efficiently, and leverage AI-powered insights for growth.\n\n## 📖 Table of Contents\n\n- [🚀 Quick Start](#-quick-start)\n- [✨ Key Features](#-key-features)\n- [🛠️ Tech Stack](#-tech-stack)\n- [💻 Development Setup](#-development-setup)\n- [📚 Documentation](#-documentation)\n\n## 🚀 Quick Start\n\n### Self-Hosted Deployment\n\n**Deploy SaleSpider in 3 commands:**\n\n```bash\n# 1. Initial setup\nmake setup\n\n# 2. Edit configuration (set passwords, domain, etc.)\nnano .env\n\n# 3. Deploy\nmake deploy\n```\n\n**That's it!** Your production-ready SaleSpider instance will be running with HTTPS, automated backups, and monitoring.\n\n### Cloud Deployment\n\n**Deploy to Vercel, Railway, or Render:**\n\n1. Set up a PostgreSQL database (Neon, Supabase, Railway)\n2. Copy `.env.cloud.example` to `.env` and configure\n3. Deploy with one click or CLI\n\n📖 **For cloud deployment:** See [Cloud Platforms Guide](https://idrisakintobi.github.io/SaleSpider/deployment/cloud-platforms)\n\n### Quick Commands\n\n```bash\nmake help      # Show all available commands\nmake status    # Check service status\nmake logs      # View logs\nmake backup    # Create manual backup\n```\n\n📖 **For complete self-hosted instructions:** [Deployment Guide](https://idrisakintobi.github.io/SaleSpider/deployment/)\n\n## ✨ Key Features\n\n- **🏪 Advanced Dashboard \u0026 Reporting**: Gain insights into sales performance, manage staff, and track inventory with role-based views\n- **📦 Smart Inventory Management**: Optimize stock levels, product deshelving, and prevent stockouts with AI insights\n- **🔔 Low Stock Notifications**: Real-time alerts for products running low with visual indicators and quick navigation\n- **🔐 Role-Based Access Control**: Secure operations with distinct roles for Managers, Cashiers, and Super Admins\n- **🤖 AI-Driven Recommendations**: Utilize AI for inventory suggestions, loss prevention, and reorder predictions\n- **💰 Sales Recording**: Easy-to-use interface for recording transactions with comprehensive audit trails\n- **👥 Staff Management**: Complete user management with performance tracking and audit logs\n- **📊 CSV Export**: Export sales and audit data with full filter support in multiple languages\n- **🌍 Multi-Language Support**: Full internationalization (English, French, Spanish, German)\n- **⚡ Performance Optimized**: Virtual scrolling, smart prefetching, and TanStack Query caching\n\n### Design Decisions\n\n**📸 Product Images**: The app supports product images via image URLs rather than direct file uploads. Users can set up their own image processing service (local or cloud with CDN) and simply provide the image links for products. This approach provides flexibility while avoiding the complexity of built-in file storage, processing, and CDN management. You maintain full control over your image infrastructure and can choose the solution that best fits your needs.\n\n**🎨 Customization**: SaleSpider is designed to be easily customized to match your brand:\n\n- **Application Icons**: Replace the default icons in `public/icons/` directory with your own branded versions. Maintain the same file names or update references in the code where needed.\n- **Logo**: Update `logo.png` in `public/icons/` for the main application logo, or set a custom URL via environment variables.\n- **Favicons**: All favicon files are located in `public/icons/` - replace them with your branded versions following standard favicon naming conventions.\n\n**🔧 Extensibility**: The clean, modular architecture makes it easy to fork and extend SaleSpider with additional features like:\n\n- Direct image uploads and advanced image processing\n- Payment provider integrations (Paystack, Moniepoint, Stripe, etc.)\n- Custom reporting and analytics dashboards\n- Integration with accounting software or ERPs\n- Multi-location/multi-store management\n- Custom workflow automations\n\nCreate your own extended version tailored to your specific business requirements!\n\n## 🛠️ Tech Stack\n\n### Frontend\n\n- **Next.js 14**: React framework with App Router\n- **React 18**: Modern React with hooks and concurrent features\n- **TypeScript**: Full type safety throughout the application\n- **Tailwind CSS**: Utility-first CSS framework\n- **ShadCN UI**: Beautiful, accessible UI components\n- **TanStack Query**: Intelligent data fetching and caching\n\n### Backend \u0026 Database\n\n- **PostgreSQL 16**: Production-ready database with optimization\n- **Prisma ORM**: Type-safe database access with migrations\n- **JWT Authentication**: Secure token-based authentication and session management\n- **Genkit AI**: Firebase's generative AI toolkit for smart insights\n\n### Deployment \u0026 Infrastructure\n\n- **Docker**: Containerized deployment\n- **Caddy**: Automatic HTTPS and reverse proxy\n- **pgBackRest**: Enterprise-grade backup system\n- **AWS S3**: Cloud backup storage\n- **Platform Agnostic**: Linux, macOS, Windows support\n\n## 💻 Development Setup\n\nFor local development:\n\n1.  **Clone the repository**:\n\n    ```bash\n    git clone \u003crepository-url\u003e\n    cd SaleSpider\n    ```\n\n2.  **Install dependencies**:\n\n    ```bash\n    npm install\n    ```\n\n3.  **Set up environment variables**:\n\n    ```bash\n    cp env.example .env\n    # Edit .env with your development settings\n    ```\n\n4.  **Set up database** (required):\n\n    ```bash\n    npx prisma migrate dev\n    npx prisma db seed\n    ```\n\n    **Important:** Database seeding is required for the application to function. It creates the initial super admin account and essential data.\n\n5.  **Run development server**:\n\n    ```bash\n    npm run dev\n    ```\n\n    Application available at `http://localhost:3000`\n\n6.  **Run AI development server** (optional):\n    ```bash\n    npm run genkit:dev\n    ```\n    Genkit flows available at `http://localhost:4000`\n\n## Exploring the Code\n\n- The main application pages are located in `src/app/`.\n- UI components can be found in `src/components/`.\n- AI-related flows using Genkit are in `src/ai/flows/`.\n- Core data structures and mock data logic are in `src/lib/`.\n\n### Path Aliases\n\nThis project uses TypeScript path aliases for clean, maintainable imports:\n\n```typescript\n// Instead of relative imports like this:\nimport { Button } from \"../../../components/ui/button\";\n\n// Use clean path aliases like this:\nimport { Button } from \"@/components/ui/button\";\n```\n\nAvailable aliases:\n\n- `@/*` - Root src directory\n- `@/components/*` - UI components\n- `@/lib/*` - Utility libraries\n- `@/hooks/*` - React hooks\n- `@/contexts/*` - React contexts\n- `@/app/*` - Next.js app directory\n- `@/ai/*` - AI-related code\n- `@/prisma/*` - Prisma schema and seeds\n- `@/types/*` - TypeScript type definitions\n\n## 📚 Documentation\n\n**📖 [View Full Documentation](https://idrisakintobi.github.io/SaleSpider/)**\n\nOur comprehensive documentation site includes:\n\n### 🚀 Getting Started\n\n- **[Quick Start Guide](https://idrisakintobi.github.io/SaleSpider/getting-started)** - Get up and running in minutes\n- **[Deployment Options](https://idrisakintobi.github.io/SaleSpider/deployment/)** - Self-hosted, hosted database, and cloud platforms\n\n### 📦 Features\n\n- **[Dashboard \u0026 Reporting](https://idrisakintobi.github.io/SaleSpider/features/dashboard)** - Analytics and insights\n- **[Inventory Management](https://idrisakintobi.github.io/SaleSpider/features/inventory)** - Stock tracking and management\n- **[Sales Recording](https://idrisakintobi.github.io/SaleSpider/features/sales)** - Point-of-sale operations\n- **[Staff Management](https://idrisakintobi.github.io/SaleSpider/features/staff)** - User roles and permissions\n- **[AI Features](https://idrisakintobi.github.io/SaleSpider/features/ai)** - Smart recommendations\n\n### ⚙️ Configuration\n\n- **[Environment Variables](https://idrisakintobi.github.io/SaleSpider/configuration/environment-variables)** - All configuration options\n- **[Security Settings](https://idrisakintobi.github.io/SaleSpider/configuration/security)** - Authentication and security\n- **[Backup Configuration](https://idrisakintobi.github.io/SaleSpider/configuration/backup)** - Data protection\n\n### 🔧 Operations\n\n- **[Backup \u0026 Restore](https://idrisakintobi.github.io/SaleSpider/operations/backup-restore)** - Database backup procedures\n- **[Makefile Commands](https://idrisakintobi.github.io/SaleSpider/operations/makefile)** - Automation commands\n- **[Monitoring](https://idrisakintobi.github.io/SaleSpider/operations/monitoring)** - System monitoring\n- **[Troubleshooting](https://idrisakintobi.github.io/SaleSpider/operations/troubleshooting)** - Common issues\n\n### 💻 Development\n\n- **[Local Setup](https://idrisakintobi.github.io/SaleSpider/development/local-setup)** - Development environment\n- **[Architecture](https://idrisakintobi.github.io/SaleSpider/development/architecture)** - System design\n- **[Contributing](https://idrisakintobi.github.io/SaleSpider/development/contributing)** - How to contribute\n\n### ⚡ Quick Reference\n\n**Common Operations:**\n\n```bash\nmake deploy        # Full deployment\nmake start         # Start services\nmake stop          # Stop services\nmake status        # Service status\nmake logs          # View logs\nmake backup        # Manual backup\nmake help          # All commands\n```\n\n**For detailed command references, see [Makefile Commands](https://idrisakintobi.github.io/SaleSpider/operations/makefile)**\n\n## ❓ FAQ\n\n### Why can't I log in after deployment?\n\n**You must seed the database** to create the super admin account. This is a required step:\n\n```bash\n# For self-hosted (Docker)\ndocker-compose exec app npm run seed\n\n# For cloud/production\nnpm run seed:prod\n```\n\nThe `make deploy` command handles this automatically for self-hosted deployments. For cloud deployments, you must run the seed command manually after your first deployment.\n\n### What does database seeding do?\n\nSeeding creates:\n\n- Super admin account (using SUPER_ADMIN_EMAIL and SUPER_ADMIN_PASSWORD from .env)\n- Essential roles and permissions\n- Initial system configuration\n\n**Without seeding, the application will not be functional.**\n\n### How do I reset my admin password?\n\nYou can reset the database and re-seed:\n\n```bash\n# Self-hosted\ndocker-compose exec app npx prisma migrate reset\ndocker-compose exec app npm run seed\n\n# Cloud\nnpx prisma migrate reset\nnpm run seed:prod\n```\n\nOr update the password directly in the database using Prisma Studio.\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Attribution\n\nIf you use SaleSpider in your project, please:\n\n- **Keep the license notice**: The MIT license requires that you include the original copyright notice and license text in any substantial portions of the software you distribute.\n- **Give credit**: Consider mentioning SaleSpider in your project's README or documentation.\n- **Star the repository**: If you find this project useful, please give it a star on GitHub to show your appreciation.\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [Contributing Guidelines](https://idrisakintobi.github.io/SaleSpider/development/contributing) for details on how to:\n\n- Report bugs\n- Suggest features\n- Submit pull requests\n- Follow our code of conduct\n\n## 💖 Support\n\nIf SaleSpider has helped your business, please consider:\n\n- ⭐ Starring this repository\n- 🐛 Reporting bugs and suggesting improvements\n- 🔧 Contributing code or documentation\n- 💬 Sharing your success story\n\n---\n\n**Built with ❤️ for the open source community**\n\nFeel free to explore and modify the code to fit your specific needs!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fidrisakintobi%2Fsalespider","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fidrisakintobi%2Fsalespider","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fidrisakintobi%2Fsalespider/lists"}