{"id":50964310,"url":"https://github.com/aslon1213/g4h-pos","last_synced_at":"2026-06-18T18:01:07.496Z","repository":{"id":337039889,"uuid":"1053152233","full_name":"aslon1213/g4h-pos","owner":"aslon1213","description":"G4H pos system written in fiber/golang","archived":false,"fork":false,"pushed_at":"2026-05-30T20:23:05.000Z","size":1447,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-30T22:11:45.642Z","etag":null,"topics":["caddy","docker","erp","golang","gorelaser","http","rest"],"latest_commit_sha":null,"homepage":"https://aslon1213.github.io/g4h-pos/","language":"Go","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/aslon1213.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-09-09T04:12:42.000Z","updated_at":"2026-05-30T20:22:12.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/aslon1213/g4h-pos","commit_stats":null,"previous_names":["aslon1213/g4h_pos_erp","aslon1213/g4h-pos"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/aslon1213/g4h-pos","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aslon1213%2Fg4h-pos","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aslon1213%2Fg4h-pos/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aslon1213%2Fg4h-pos/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aslon1213%2Fg4h-pos/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aslon1213","download_url":"https://codeload.github.com/aslon1213/g4h-pos/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aslon1213%2Fg4h-pos/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34501482,"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-06-18T02:00:06.871Z","response_time":128,"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":["caddy","docker","erp","golang","gorelaser","http","rest"],"created_at":"2026-06-18T18:01:06.580Z","updated_at":"2026-06-18T18:01:07.490Z","avatar_url":"https://github.com/aslon1213.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Magazin POS/ERP (Go)\n\n[![Release](https://img.shields.io/github/v/release/aslon1213/g4h_pos_erp?style=flat-square)](https://github.com/aslon1213/g4h_pos_erp/releases)\n[![Build Status](https://img.shields.io/github/actions/workflow/status/aslon1213/g4h_pos_erp/release.yaml?style=flat-square)](https://github.com/aslon1213/g4h_pos_erp/actions/workflows/release.yaml)\n[![Go Version](https://img.shields.io/github/go-mod/go-version/aslon1213/g4h_pos_erp?style=flat-square)](https://golang.org/)\n[![License](https://img.shields.io/github/license/aslon1213/g4h_pos_erp?style=flat-square)](LICENSE)\n\nA Point of Sale (POS) and ERP backend built with Go for retail operations.\n\n## Latest Changes (May 2026)\n\n- All staff endpoints moved under a versioned **`/api/v1/admin/*`** namespace (auth, suppliers, products, journals, finance, transactions, customers, bnpl, proposals). Admin `login` stays public; `register` is disabled.\n- Added a public **storefront API** under **`/api/v1/store/*`** (customer auth, catalog, products, cart, wishlist, orders, reviews, promotions) with a dedicated `CustomerAuthMiddleware` (validates the `store_customers` collection). Phase-1 stubs — see `docs/storefront-implementation-guide.md`.\n- Response envelope is now the **generic `Output[T]`**; error responses use `ErrorOutput`. Swaggo annotations are typed per endpoint.\n\nEarlier:\n\n- Auth token handling decodes `server.secret_symmetric_key` from Base64 before creating/verifying PASETO tokens.\n- Config loading supports explicit environment variable bindings (via Viper) with optional `.env` loading using `LOAD_DOT_ENV`.\n\n## 🚀 Features\n\n- **Sales Management** - Complete sales transaction processing\n- **Product Management** - Inventory tracking and product catalog\n- **Customer Management** - Customer data and relationship management\n- **Supplier Management** - Vendor and supplier relationship tracking\n- **Financial Management** - Transaction processing and financial reporting\n- **Journal Entries** - Accounting and bookkeeping functionality\n- **Internal Expenses** - Business expense tracking and management\n- **REST API** - Full RESTful API with Swagger documentation\n- **Real-time Data** - Redis caching for optimal performance\n- **Observability** - OpenTelemetry integration for monitoring\n\n## 🛠️ Tech Stack\n\n- **Backend**: Go 1.24.3\n- **Web Framework**: [Fiber v2](https://github.com/gofiber/fiber)\n- **Database**: MongoDB\n- **Cache**: Redis\n- **Documentation**: Swagger/OpenAPI\n- **Authentication**: PASETO (Bearer token) + BasicAuth (docs/dashboard)\n- **Observability**: OpenTelemetry\n- **Logging**: Zerolog\n- **Configuration**: Viper (YAML + environment overrides)\n\n## 📋 Prerequisites\n\n- Go 1.24.3 or higher\n- MongoDB 4.4+ cluster with replica set\n- Redis 6.0+\n- Docker \u0026 Docker Compose (for containerized setup)\n\n## 🚀 Quick Start\n\n### Using Docker Compose (Recommended)\n\n1. **Clone the repository**\n\n   ```bash\n   git clone https://github.com/aslon1213/g4h_pos_erp.git\n   cd g4h_pos_erp\n   ```\n\n2. **Prepare configuration**\n\n   ```bash\n   cp example.config.yaml config.local.yaml\n   # Edit config.local.yaml to match your MongoDB/Redis/S3/settings\n   ```\n\n3. **Create required docker networks (first run only)**\n\n   ```bash\n   docker network create mongoCluster || true\n   docker network create caddy || true\n   ```\n\n4. **Start optional infrastructure (reverse proxy, redis UI)**\n\n   ```bash\n   # Caddy (for domain/HTTPS via labels). Optional for local use\n   docker compose -f deploy/docker-compose-caddy.yaml up -d\n\n   # Redis (redis-stack with UI). Optional\n   docker compose -f deploy/docker-compose-db.yml up -d\n   ```\n\n5. **Start the backend**\n\n   ```bash\n   docker compose -f deploy/docker-compose.yml up -d --build\n   ```\n\n### Manual Setup\n\n1. **Install dependencies**\n\n   ```bash\n   go mod download\n   ```\n\n2. **Setup MongoDB**\n\n   - Use an existing MongoDB replica set, or update your active config file (`config.local.yaml` by default, `config.yaml` in production) to point to your MongoDB URL. Ensure `replica_set` aligns with your cluster if replication is enabled.\n\n3. **Configure the application**\n\n   ```bash\n   cp example.config.yaml config.local.yaml\n   # Edit config.local.yaml with your database and Redis settings\n   ```\n\n4. **Run the application**\n   ```bash\n   go run cmd/main.go\n   ```\n\n## ⚙️ Configuration\n\nThe app loads config in this order:\n\n- If `ENVIRONMENT=production`: uses `config.yaml`\n- Otherwise: uses `config.local.yaml` (or `CONFIG_FILE` if set, e.g. `CONFIG_FILE=config.staging`)\n- If `LOAD_DOT_ENV` is set (non-empty), `.env` is loaded\n- Bound environment variables override matching YAML keys\n\nStart from:\n\n```bash\ncp example.config.yaml config.local.yaml\n```\n\nYAML shape:\n\n```yaml\ndatabase:\n  host: \"localhost\"\n  port: \"27017\"\n  username: \"admin\"\n  password: \"admin\"\n  database: \"store\"\n  max_connections: 20\n  min_pool_size: 10\n  auth: false\n  replica_set: \"rs0\"\n  url: \"mongodb://localhost:27017/?replicaSet=rs0\"\n\nredis:\n  host: \"localhost\"\n  port: \"6379\"\n  password: \"\"\n  database: 0\n\nserver:\n  port: \":12000\"\n```\n\n### Environment Variables (Supported Bindings)\n\nThe config loader binds these env vars:\n\n- Database: `DATABASE_HOST`, `DATABASE_PORT`, `DATABASE_USERNAME`, `DATABASE_PASSWORD`, `DATABASE_NAME`, `DATABASE_MAX_CONNECTIONS`, `DATABASE_MIN_POOL_SIZE`, `DATABASE_AUTH`, `DATABASE_REPLICA_SET`, `DATABASE_URL`\n- Redis: `REDIS_HOST`, `REDIS_PORT`, `REDIS_PASSWORD`, `REDIS_DATABASE`\n- Server: `SERVER_HOST`, `SERVER_PORT`, `SERVER_SECRET_SYMMETRIC_KEY`, `SERVER_TOKEN_EXPIRY_HOURS`\n- S3: `S3_REGION`, `S3_ENDPOINT`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`, `S3_IMAGE_BUCKET`\n\n### Auth Key Requirement\n\n`server.secret_symmetric_key` is Base64-decoded at runtime for PASETO middleware and token creation. Use a Base64-encoded 32-byte key, for example:\n\n```bash\nopenssl rand -base64 32\n```\n\n## 📖 API Documentation\n\nOnce the application is running, access Swagger at:\n\n```\nhttp://localhost:12000/docs/index.html\n```\n\nNote: Access to `/docs` is protected with BasicAuth. Credentials are configured in `server.admin_docs_users` in your active config file.\n\nThe API is split into an **admin/staff** tree and a public **storefront** tree.\n\n**Admin / staff — `/api/v1/admin/*`** (PASETO bearer token against the `users` collection):\n\n- `/api/v1/admin/auth/login` (public), `/api/v1/admin/auth/me`, `/api/v1/admin/activities/*`\n- `/api/v1/admin/products/*` - product catalog, stock ops, images\n- `/api/v1/admin/customers/*` - customers\n- `/api/v1/admin/suppliers/*` - suppliers and supplier transactions\n- `/api/v1/admin/transactions/*` - transaction queries/updates/docs enums\n- `/api/v1/admin/finance/*` - branch finance\n- `/api/v1/admin/journals/*` - journal lifecycle and operations\n- `/api/v1/admin/bnpl/*`, `/api/v1/admin/branches/:branch_id/bnpls`, `/api/v1/admin/customers/:customer_id/bnpls`\n- `/api/v1/admin/proposals/*` and `/proposals` (proxy route)\n\n**Storefront — `/api/v1/store/*`** (public browse + customer PASETO token against `store_customers`):\n\n- `/api/v1/store/auth/*` (register/login public; me/logout protected), `/api/v1/store/account/addresses/*`\n- `/api/v1/store/catalog/*`, `/api/v1/store/products/*` - public catalog \u0026 product browse + reviews\n- `/api/v1/store/cart/*`, `/api/v1/store/wishlist/*`, `/api/v1/store/orders/*`, `/api/v1/store/checkout/*` - customer-only\n- `/api/v1/store/reviews/*`, `/api/v1/store/promotions/*`\n\n**Still under `/api`:** `/api/sales/transactions/*`.\n\nNotes:\n\n- Storefront endpoints are **Phase-1 stubs** (return HTTP 501 `not implemented`); routing and customer auth are wired, business logic is pending. See `docs/storefront-implementation-guide.md`.\n- The admin `register` endpoint and `/api/sales/session/*` are disabled/commented out.\n- Responses use a generic envelope `Output[T]` → `{ \"data\": \u003cT\u003e, \"error\": [] }`; errors use `ErrorOutput`.\n\n## 🔧 Development\n\n### Project Structure\n\n```\n.\n├── cmd/                            # Application entry points - main.go\n├── pkg/                            # Application packages\n│   ├── app/                        # Main application logic\n│   ├── controllers/                # Business logic controllers\n│   │   ├── customers/              # Customer management (+ bnpl/)\n│   │   ├── finance/                # Financial operations\n│   │   ├── internalExpenses/       # Internal expenses\n│   │   ├── journals/               # Journal entries for daily financial operations\n│   │   ├── products/               # Product management\n│   │   ├── sales/                  # Sales transactions\n│   │   ├── suppliers/              # Supplier management\n│   │   ├── transactions/           # Financial transactions\n│   │   └── store/                  # Storefront API (auth, cart, catalog, orders, ...)\n│   ├── routes/                     # API route definitions (routes.go, store.go)\n│   ├── middleware/                 # HTTP middleware (staff + customer auth)\n│   ├── repository/                 # Data access layer, models\n│   ├── utils/                      # Utility functions\n│   └── configs/                    # Configuration management\n├── docs/                           # API documentation\n├── deploy/                         # Deployment configurations - docker-compose*.yml\n├── test/                           # Test files\n├── web/                            # Frontend assets (if any)\n└── scripts/                        # Build and deployment scripts\n```\n\n### Building the Application\n\n```bash\n# Build for current platform\ngo build -o bin/pos-erp cmd/main.go\n\n# Build for multiple platforms using GoReleaser\ngoreleaser build --snapshot --clean\n```\n\n### Running Tests\n\n```bash\ngo test ./test\n```\n\n### Generate Swagger Documentation\n\n```bash\n# Run from the repo root (the older --dir pkg,routes,app flags are stale)\nswag init -g cmd/main.go\n```\n\n## 🐳 Docker Deployment\n\nThe project includes Docker Compose configuration for easy deployment:\n\n```bash\n# Start backend\ndocker compose -f deploy/docker-compose.yml up\n\n# View logs\ndocker compose -f deploy/docker-compose.yml logs -f\n\n# Stop services\ndocker compose -f deploy/docker-compose.yml down\n```\n\n## 📦 Releases \u0026 CI/CD\n\n### Automated Releases\n\nThis project uses GitHub Actions with [GoReleaser](https://goreleaser.com/) for automated releases:\n\n- **Trigger**: Releases are automatically triggered when you push a git tag starting with `v` (e.g., `v1.0.0`, `v2.1.3`)\n- **Build Matrix**: Cross-platform builds for Linux, macOS, and Windows (amd64, arm64)\n- **Artifacts**: Pre-built binaries, archives, and checksums\n- **Distribution**: Automatically published to GitHub Releases\n\n### Release Workflow\n\n1. **Create and push a tag**:\n\n   ```bash\n   git tag v1.0.0\n   git push origin v1.0.0\n   ```\n\n2. **GitHub Actions automatically**:\n   - Builds binaries for all supported platforms\n   - Runs tests and quality checks\n   - Creates GitHub release with artifacts\n   - Generates changelog\n\n### Build Platforms\n\n| OS      | Architecture | Status       |\n| ------- | ------------ | ------------ |\n| Linux   | amd64, arm64 | ✅ Supported |\n| macOS   | amd64, arm64 | ✅ Supported |\n| Windows | amd64        | ✅ Supported |\n\n### Local Development Build\n\n```bash\n# Build snapshot for testing (without releasing)\ngoreleaser build --snapshot --clean\n\n# Build for current platform only\ngo build -o bin/pos-erp cmd/main.go\n```\n\n### Download Latest Release\n\nVisit the [Releases page](https://github.com/aslon1213/g4h_pos_erp/releases) to download pre-built binaries for your platform.\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/\u003csome-feature\u003e`)\n3. Commit your changes (`git commit -m 'Add some amazing -- \u003csome-feature\u003e'`)\n4. Push to the branch (`git push origin feature/\u003csome-feature\u003e`)\n5. Open a Pull Request\n\n## 🆘 Support\n\nFor support and questions:\n\n- Create an issue in the GitHub repository\n- Contact: hamidovaslon13@gmail.com\n\n## 🚧 Development Status\n\nThis project is actively maintained and under development. Please check the [issues](https://github.com/aslon1213/g4h_pos_erp/issues) for current development status and upcoming features.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faslon1213%2Fg4h-pos","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faslon1213%2Fg4h-pos","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faslon1213%2Fg4h-pos/lists"}