{"id":47032536,"url":"https://github.com/mchestr/homerp","last_synced_at":"2026-03-12T00:09:48.524Z","repository":{"id":329042113,"uuid":"1115529485","full_name":"mchestr/homerp","owner":"mchestr","description":null,"archived":false,"fork":false,"pushed_at":"2025-12-29T19:39:18.000Z","size":4768,"stargazers_count":0,"open_issues_count":8,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-01T00:31:50.429Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/mchestr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2025-12-13T03:14:07.000Z","updated_at":"2025-12-29T19:39:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mchestr/homerp","commit_stats":null,"previous_names":["mchestr/homerp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/mchestr/homerp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mchestr%2Fhomerp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mchestr%2Fhomerp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mchestr%2Fhomerp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mchestr%2Fhomerp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mchestr","download_url":"https://codeload.github.com/mchestr/homerp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mchestr%2Fhomerp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30408016,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-11T22:36:59.286Z","status":"ssl_error","status_checked_at":"2026-03-11T22:36:57.544Z","response_time":84,"last_error":"SSL_read: 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":[],"created_at":"2026-03-12T00:09:45.236Z","updated_at":"2026-03-12T00:09:48.517Z","avatar_url":"https://github.com/mchestr.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HomERP\n\n**Home inventory system with AI-powered item classification for hobbyists.**\n\n[![Backend CI](https://github.com/mchestr/homerp/actions/workflows/backend.yml/badge.svg)](https://github.com/mchestr/homerp/actions/workflows/backend.yml)\n[![Frontend CI](https://github.com/mchestr/homerp/actions/workflows/frontend.yml/badge.svg)](https://github.com/mchestr/homerp/actions/workflows/frontend.yml)\n\n---\n\n## Features\n\n### Core Inventory Management\n- **AI-Powered Classification** — Snap a photo and let GPT-4 Vision automatically identify, categorize, and tag your items\n- **Flexible Item Tracking** — Track anything from M3 screws to HDMI cables with custom attributes and JSONB metadata\n- **Hierarchical Categories** — Organize items in a tree structure (Electronics \u003e Cables \u003e HDMI)\n- **Smart Locations** — Multi-level storage hierarchy (Room → Shelf → Bin → Drawer)\n\n### Storage Visualization\n- **Gridfinity Integration** — Visual bin layout with drag-and-drop positioning\n- **Collision Detection** — Prevents overlapping bin placements\n- **QR Code Labels** — Generate and print labels for physical storage locations\n\n### Collaboration \u0026 Sharing\n- **Inventory Sharing** — Share your inventory with other users (view-only or full access)\n- **Multi-Tenant Architecture** — Complete data isolation via PostgreSQL Row-Level Security\n\n### Billing \u0026 Credits\n- **Credit-Based AI Usage** — Pay-as-you-go model for AI classification\n- **Free Tier** — 5 free AI credits per month\n- **Stripe Integration** — Secure payment processing for credit packs\n- **Low Stock Alerts** — Email notifications when items run low\n\n### Internationalization\n- **Multi-Language Support** — English, German, Spanish, French, Portuguese (BR), Japanese\n\n---\n\n## Tech Stack\n\n| Layer | Technology |\n|-------|------------|\n| **Backend** | Python 3.12, FastAPI, SQLAlchemy (async), PostgreSQL 16 |\n| **Frontend** | Next.js 15, React, Tailwind CSS, shadcn/ui |\n| **AI** | OpenAI GPT-4 Vision |\n| **Auth** | Google OAuth + JWT |\n| **Payments** | Stripe |\n| **Task Runner** | [mise](https://mise.jdx.dev/) |\n\n---\n\n## Quick Start\n\n### Prerequisites\n\n- [mise](https://mise.jdx.dev/) — Tool version manager \u0026 task runner\n- [Docker](https://www.docker.com/) \u0026 Docker Compose\n- Google OAuth credentials ([setup guide](https://developers.google.com/identity/protocols/oauth2))\n- OpenAI API key ([get one](https://platform.openai.com/api-keys))\n- Stripe API keys (optional, for billing)\n\n### Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/mchestr/homerp.git\ncd homerp\n\n# Install tools (Node.js, Python, uv) and all dependencies\nmise install\nmise run install\n```\n\n### Configuration\n\n1. Copy environment files:\n```bash\ncp backend/.env.example backend/.env\ncp frontend/.env.example frontend/.env\n```\n\n2. Edit `backend/.env` with your credentials:\n```env\n# Database\nDATABASE_URL=postgresql+asyncpg://homerp:homerp@localhost:5432/homerp\n\n# Authentication (required)\nGOOGLE_CLIENT_ID=your-google-client-id\nGOOGLE_CLIENT_SECRET=your-google-client-secret\nJWT_SECRET=your-secure-random-secret\n\n# OpenAI (required for AI classification)\nOPENAI_API_KEY=your-openai-api-key\n\n# Frontend URL (for CORS and Stripe redirects)\nFRONTEND_URL=http://localhost:3000\n\n# Storage\nUPLOAD_DIR=./uploads\n\n# Stripe (optional, for billing)\nSTRIPE_SECRET_KEY=sk_test_...\nSTRIPE_PUBLISHABLE_KEY=pk_test_...\nSTRIPE_WEBHOOK_SECRET=whsec_...\n\n# Credits\nFREE_MONTHLY_CREDITS=5\n\n# Admin (email that automatically becomes admin on login)\nADMIN_EMAIL=admin@example.com\n\n# Debug mode\nDEBUG=false\n```\n\n3. Edit `frontend/.env`:\n```env\nNEXT_PUBLIC_API_URL=http://localhost:8000\n\n# E2E testing (optional)\nPLAYWRIGHT_BASE_URL=http://localhost:3000\n```\n\n### Running the Application\n\n```bash\n# Start all services (PostgreSQL, backend, frontend)\nmise run dev\n```\n\nAccess the application:\n- **Frontend:** http://localhost:3000\n- **Backend API:** http://localhost:8000\n- **API Documentation:** http://localhost:8000/docs\n\n---\n\n## Development\n\n### Task Runner Commands\n\nAll common operations are available through mise:\n\n```bash\nmise tasks              # List all available tasks\n```\n\n#### Development\n```bash\nmise run dev            # Start all services with Docker\nmise run dev:backend    # Start backend only\nmise run dev:frontend   # Start frontend only\n```\n\n#### Code Quality\n```bash\nmise run lint           # Lint all code\nmise run format         # Format all code\nmise run check          # Run ALL CI checks (recommended before pushing)\n```\n\n#### Testing\n```bash\nmise run test           # Run all tests\nmise run test:backend   # Backend tests (pytest)\nmise run test:frontend  # Frontend unit tests (vitest)\nmise run test:e2e       # E2E tests (Playwright)\nmise run test:e2e:ui    # E2E tests with Playwright UI\n```\n\n#### Database\n```bash\nmise run db:migrate                  # Run migrations\nmise run db:migration \"description\"  # Create new migration\nmise run db:reset                    # Reset database\n```\n\n#### API Client\n```bash\nmise run api:generate   # Regenerate frontend TypeScript client from OpenAPI\n```\n\n### Manual Commands\n\n\u003cdetails\u003e\n\u003csummary\u003eBackend (without mise)\u003c/summary\u003e\n\n```bash\ncd backend\nuv sync                          # Install dependencies\nuv run pytest                    # Run tests\nuv run ruff check .              # Lint\nuv run ruff format .             # Format\nuv run alembic upgrade head      # Apply migrations\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eFrontend (without mise)\u003c/summary\u003e\n\n```bash\ncd frontend\npnpm install                     # Install dependencies\npnpm dev                         # Start dev server\npnpm build                       # Production build\npnpm lint                        # Lint\npnpm test                        # Unit tests\npnpm test:e2e                    # E2E tests\npnpm generate-api                # Regenerate API client\n```\n\u003c/details\u003e\n\n---\n\n## Project Structure\n\n```\nhomerp/\n├── mise.toml              # Task runner configuration\n├── docker-compose.yml     # Development environment\n│\n├── backend/               # FastAPI backend\n│   ├── src/\n│   │   ├── auth/          # OAuth + JWT authentication\n│   │   ├── users/         # User management\n│   │   ├── items/         # Inventory items (core)\n│   │   ├── categories/    # Item categories (tree structure)\n│   │   ├── locations/     # Storage locations\n│   │   ├── images/        # Image upload + storage\n│   │   ├── ai/            # OpenAI GPT-4 Vision integration\n│   │   ├── billing/       # Stripe billing + credits\n│   │   └── common/        # Shared utilities\n│   ├── alembic/           # Database migrations\n│   └── tests/             # pytest test suite\n│\n└── frontend/              # Next.js frontend\n    ├── src/\n    │   ├── app/           # App Router pages\n    │   ├── components/    # React components\n    │   │   └── ui/        # shadcn/ui components\n    │   ├── context/       # React Context providers\n    │   ├── hooks/         # Custom React hooks\n    │   └── lib/\n    │       └── api/       # Generated OpenAPI TypeScript client\n    ├── e2e/               # Playwright E2E tests\n    └── messages/          # i18n translation files\n```\n\n---\n\n## Architecture Highlights\n\n### Multi-Tenancy with Row-Level Security\nAll user data is isolated at the database level using PostgreSQL RLS policies. Each request sets `app.current_user_id` as a session variable, and RLS policies automatically filter all queries.\n\n### Async Everything\nThe entire backend is async-first using:\n- Async SQLAlchemy with `asyncpg` driver\n- Async FastAPI endpoints\n- Non-blocking I/O throughout\n\n### Type-Safe API Communication\nThe frontend uses an auto-generated TypeScript client from the backend's OpenAPI specification, ensuring compile-time type safety across the stack.\n\n### Credit-Based AI Billing\n- **Free tier:** 5 AI credits per month (resets on signup anniversary)\n- **Credit packs:** One-time purchases that never expire\n- **Stripe webhooks:** Automatic credit provisioning on payment\n\n---\n\n## API Overview\n\n| Endpoint | Description |\n|----------|-------------|\n| `POST /api/v1/auth/google` | Initiate Google OAuth |\n| `GET /api/v1/items` | List items (paginated, filterable) |\n| `POST /api/v1/items` | Create new item |\n| `POST /api/v1/images/upload` | Upload item image |\n| `POST /api/v1/images/classify` | AI classification (uses credits) |\n| `GET /api/v1/billing/balance` | Get credit balance |\n| `POST /api/v1/billing/checkout` | Create Stripe checkout session |\n\nFull API documentation available at `/docs` when running the backend.\n\n---\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Run checks before committing:\n   ```bash\n   mise run check\n   ```\n5. Commit using [Conventional Commits](https://www.conventionalcommits.org/):\n   ```bash\n   git commit -m \"feat(items): add bulk delete functionality\"\n   ```\n6. Push and open a Pull Request\n\n### Commit Message Format\n- `feat:` — New features\n- `fix:` — Bug fixes\n- `chore:` — Maintenance tasks\n- `refactor:` — Code improvements\n- `docs:` — Documentation updates\n- `test:` — Test additions/fixes\n\n---\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmchestr%2Fhomerp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmchestr%2Fhomerp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmchestr%2Fhomerp/lists"}