{"id":50932046,"url":"https://github.com/kisaesdevlab/vibe-payroll-time","last_synced_at":"2026-06-17T05:04:44.335Z","repository":{"id":352671320,"uuid":"1216141978","full_name":"KisaesDevLab/Vibe-Payroll-Time","owner":"KisaesDevLab","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-28T03:48:09.000Z","size":1431,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-28T05:25:44.624Z","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":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/KisaesDevLab.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-04-20T15:57:29.000Z","updated_at":"2026-04-28T03:48:12.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/KisaesDevLab/Vibe-Payroll-Time","commit_stats":null,"previous_names":["kisaesdevlab/vibe-payroll-time"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/KisaesDevLab/Vibe-Payroll-Time","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KisaesDevLab%2FVibe-Payroll-Time","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KisaesDevLab%2FVibe-Payroll-Time/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KisaesDevLab%2FVibe-Payroll-Time/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KisaesDevLab%2FVibe-Payroll-Time/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KisaesDevLab","download_url":"https://codeload.github.com/KisaesDevLab/Vibe-Payroll-Time/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KisaesDevLab%2FVibe-Payroll-Time/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34434498,"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-17T02:00:05.408Z","response_time":127,"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":"2026-06-17T05:04:28.810Z","updated_at":"2026-06-17T05:04:44.330Z","avatar_url":"https://github.com/KisaesDevLab.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Vibe Payroll Time\n\nA self-hosted, multi-tenant **employee time tracking** appliance for hourly and\nshift workers. Designed for CPA firms tracking their own staff hours (free,\ninternal use) and for CPA firms reselling it to their small-business clients\n(commercial tier). Narrower and simpler than QuickBooks Time, OnTheClock, or\nHomebase — punch-in/out, timesheet approval, payroll export, nothing more.\n\n**Explicit non-goals (v1):** payroll processing, scheduling, GPS/geofencing,\nrate or wage data, native mobile apps, state-specific overtime rules, GL\nintegration. See [`CLAUDE.md`](./CLAUDE.md) for the full scope.\n\n## Install or update in one line\n\nOn a fresh Ubuntu Server 24.04 LTS box (e.g. a GMKtec NucBox M6) **or** an\nexisting appliance — the same command does both:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/KisaesDevLab/Vibe-Payroll-Time/main/scripts/get.sh | sudo bash\n```\n\n[`scripts/get.sh`](./scripts/get.sh) detects whether `/opt/vibept/.env`\nalready exists and routes to the installer or the updater accordingly. On\nfirst run it walks you through the ingress choice (Cloudflare Tunnel /\nTailscale Funnel / public + Caddy), stands up Docker + the stack, and leaves\nyou at a first-run web wizard for the SuperAdmin. On subsequent runs it takes\na `pg_dump` snapshot, `git pull`s the latest compose / scripts, pulls the\nmatching GHCR image tag, rolls over the stack, and\nauto-rolls-back on health-check failure (only when no migrations ran —\notherwise it prints manual recovery steps).\n\n**Non-interactive install** (pre-answer the ingress prompts):\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/KisaesDevLab/Vibe-Payroll-Time/main/scripts/get.sh \\\n  | PROFILE=cloudflare CLOUDFLARE_TUNNEL_TOKEN=xxx sudo -E bash\n```\n\nFull list of env-var overrides lives in the header comments of\n[`scripts/appliance/install.sh`](./scripts/appliance/install.sh) and\n[`scripts/appliance/update.sh`](./scripts/appliance/update.sh).\n\n### Container images\n\nPre-built images are published to the GitHub Container Registry on every\nsuccessful CI run against `main` and every `v*` release tag. Names follow\nthe Vibe distribution convention (`vibe-distribution-plan.md`):\n\n- `ghcr.io/kisaesdevlab/vibe-payroll-api`\n- `ghcr.io/kisaesdevlab/vibe-payroll-web`\n\nTags:\n\n- `:latest` — most recent release tag\n- `:X.Y.Z` / `:X.Y` / `:X` — semver tags on `v*` releases\n- `:main` — rolling tip of `main`\n- `:sha-\u003cshort\u003e` — exact commit, pinnable from `IMAGE_TAG=sha-abc1234` in\n  `.env`\n\n`docker-compose.prod.yml` references these paths and pulls them from GHCR;\nbuild from source uses the grouped overlay (see below).\n\n### Compose file conventions\n\nThree compose files cooperate for the dev → grouped → prod lifecycle:\n\n| File                         | Purpose                                                                                                                                                                                                                              |\n| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `docker-compose.yml`         | Dev base — Postgres (+ optional pgAdmin via `--profile tools`) on the host. Backend and frontend run on the host via `npm run dev` for hot reload.                                                                                   |\n| `docker-compose.grouped.yml` | Multi-app dev overlay — adds containerized `api` + `web` (built from source), joins the externally-managed `vibe_ingress` network, bakes the `/payroll/` base path into the bundle. Used to test multi-app deployment shape locally. |\n| `docker-compose.prod.yml`    | Single-app production — pulls `vibe-payroll-{api,web}` from GHCR, ships its own Caddy ingress, supports the `cloudflare` and `tailscale` tunnel profiles.                                                                            |\n\n## Quick start (dev)\n\n```bash\n# boot Postgres\ndocker compose up -d\n\n# run migrations\nnpm run migrate --workspace=backend\n\n# start dev servers with hot reload (host process; no container)\nnpm run dev\n```\n\nBackend: \u003chttp://localhost:4000/api/v1/health\u003e · Frontend:\n\u003chttp://localhost:5180\u003e\n\n### Multi-app dev (grouped overlay)\n\nTo mirror a multi-app deployment locally:\n\n```bash\ndocker network create vibe_ingress    # one-time\ndocker compose -f docker-compose.yml -f docker-compose.grouped.yml up --build -d\n```\n\nThe `api` + `web` containers join `vibe_ingress` and serve under the\n`/payroll/` prefix. Run a Caddy ingress separately in front of\n`vibe_ingress` to route to them.\n\n## Documentation\n\n- [`CLAUDE.md`](./CLAUDE.md) — architecture, conventions, and the canonical\n  scope document\n- [`BUILD_PLAN.md`](./BUILD_PLAN.md) — phased, checklist-driven build plan\n- [`CONTRIBUTING.md`](./CONTRIBUTING.md) — branching, commits, and PR flow\n\n## Licensing\n\n- Source: [PolyForm Internal Use 1.0.0](./LICENSE) — free for internal\n  staff-only use\n- Client-portal and reseller use: see\n  [`LICENSE-COMMERCIAL.md`](./LICENSE-COMMERCIAL.md)\n- Commercial keys vended by the shared\n  [`kisaes-license-portal`](https://licensing.kisaes.com)\n\n## Stack\n\nReact 18 + Vite + Tailwind + TanStack Query/Table · Node 20 + Express + Knex +\nZod + Pino · PostgreSQL 16 · Docker Compose · Caddy · Cloudflare Tunnel or\nTailscale Funnel.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkisaesdevlab%2Fvibe-payroll-time","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkisaesdevlab%2Fvibe-payroll-time","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkisaesdevlab%2Fvibe-payroll-time/lists"}