{"id":51230310,"url":"https://github.com/kuldeepsingh343/time-tracker-payroll","last_synced_at":"2026-06-28T15:31:19.463Z","repository":{"id":364434385,"uuid":"1267911244","full_name":"kuldeepsingh343/time-tracker-payroll","owner":"kuldeepsingh343","description":"A secure, responsive full-stack employee time-tracking and payroll application with shared Kiosk mode, Employee, and Admin dashboards.","archived":false,"fork":false,"pushed_at":"2026-06-13T01:38:06.000Z","size":634,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-13T03:10:46.584Z","etag":null,"topics":["express","nodejs","payroll","postgresql","react","sqlite","time-tracker"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","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/kuldeepsingh343.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":"2026-06-13T01:01:54.000Z","updated_at":"2026-06-13T01:38:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/kuldeepsingh343/time-tracker-payroll","commit_stats":null,"previous_names":["kuldeepsingh343/time-tracker-payroll"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/kuldeepsingh343/time-tracker-payroll","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kuldeepsingh343%2Ftime-tracker-payroll","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kuldeepsingh343%2Ftime-tracker-payroll/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kuldeepsingh343%2Ftime-tracker-payroll/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kuldeepsingh343%2Ftime-tracker-payroll/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kuldeepsingh343","download_url":"https://codeload.github.com/kuldeepsingh343/time-tracker-payroll/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kuldeepsingh343%2Ftime-tracker-payroll/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34894560,"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-28T02:00:05.809Z","response_time":54,"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":["express","nodejs","payroll","postgresql","react","sqlite","time-tracker"],"created_at":"2026-06-28T15:31:19.358Z","updated_at":"2026-06-28T15:31:19.457Z","avatar_url":"https://github.com/kuldeepsingh343.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Chronos Time-Tracking \u0026 Payroll Web Application\n\nA secure, responsive full-stack web application designed for shared kiosk operations (ideal for iPad/tablet terminals), individual employee timesheets, and administrator payroll controls.\n\n![Chronos Dashboard Screenshot](./dashboard_screenshot.png)\n\n## 🚀 Features\n\n- **Shared Kiosk Terminal:** A grid roster showing all employee profiles. Quick buttons allow employees to Clock In or Clock Out. Actions are secured via individual passwords and verified using bcrypt hashing on the backend.\n- **Passcode Touch-Pad:** An on-screen keypad optimized for touchscreen tablets (like iPads) alongside traditional keyboard input.\n- **Private Employee Dashboard:** Secure employee login showing accumulated pending and paid work hours/earnings with interactive timesheet history filtering.\n- **Admin Command Board:** \n  - *Payroll Reconciliation:* Overview of total unpaid payouts. Tabular review of unpaid completed shifts with instantaneous status-updating buttons.\n  - *User Management:* CRUD forms for adding new staff profiles (role, hourly rates) and removing profiles.\n\n---\n\n## 📁 Project Structure\n\n```text\ntime-tracker-payroll/\n├── backend/\n│   ├── src/\n│   │   ├── config/\n│   │   │   └── db.js          # Unified SQLite \u0026 PostgreSQL adapter\n│   │   ├── db/\n│   │   │   ├── schema.sql     # Relational DB Schema\n│   │   │   └── seed.js        # Hashed password user seeder\n│   │   ├── middleware/\n│   │   │   └── auth.js        # JWT protection middleware\n│   │   ├── routes/\n│   │   │   └── api.js         # API Route controllers\n│   │   └── index.js           # Express server entry point\n│   ├── .env                   # Environment config (defaults to SQLite)\n│   └── package.json\n├── frontend/\n│   ├── src/\n│   │   ├── components/        # Kiosk, Login, Employee \u0026 Admin view panels\n│   │   ├── context/\n│   │   │   └── AuthContext.jsx# React Context for session management\n│   │   ├── App.css            # Unused default styles (cleared)\n│   │   ├── App.jsx            # Main app shell \u0026 React Router routes\n│   │   ├── index.css          # Custom visual styling \u0026 responsive design tokens\n│   │   └── main.jsx           # Vite entrypoint\n│   ├── package.json\n│   └── vite.config.js\n├── docker-compose.yml         # Containerized PostgreSQL service\n└── README.md                  # Setup \u0026 Usage Documentation\n```\n\n---\n\n## 🛠️ Setup Instructions\n\n### 1. Prerequisite\nEnsure you have **Node.js** (v16+) installed. Optionally, **Docker** is recommended if you wish to run PostgreSQL.\n\n### 2. Database Modes\nThe application supports **SQLite (Default - Zero Configuration)** and **PostgreSQL (Production-Ready)**.\n\n#### Option A: SQLite (Immediate running - Recommended for testing)\nNo installation is required. The backend automatically initializes and seeds a local database file at `backend/src/db/local.db`.\n\n#### Option B: PostgreSQL\n1. Start the PostgreSQL container from the root directory:\n   ```bash\n   docker-compose up -d\n   ```\n2. Update the environment configuration in `backend/.env`:\n   ```env\n   DB_TYPE=postgres\n   DATABASE_URL=postgresql://postgres:postgres@localhost:5432/time_tracker\n   ```\n3. Run the schema seeder manually to create the tables in PostgreSQL:\n   ```bash\n   npm --prefix backend run seed\n   ```\n\n---\n\n## 🏃 Running the Application\n\n### Step 1: Run the Backend Server\nStart the Express server on port `5001`:\n```bash\nnpm --prefix backend run dev\n```\n\n### Step 2: Run the Frontend App\nStart the Vite development server on port `5173`:\n```bash\nnpm --prefix frontend run dev\n```\nOpen **[http://localhost:5173](http://localhost:5173)** in your browser.\n\n---\n\n## 🔑 Test Credentials (Seeded Automatically)\n\n| Account Role | Username | Password/PIN | Hourly Rate |\n| :--- | :--- | :--- | :--- |\n| **Administrator** | `admin1` | `admin123` | *N/A* |\n| **Employee** | `john_doe` | `john123` | `$25.00` |\n| **Employee** | `jane_smith` | `jane123` | `$30.00` |\n\n---\n\n## 🔄 Verification Scenarios\n\n1. **Verify Clocking-In:**\n   - On the Kiosk view, click **Clock-In** under `jane_smith`.\n   - Enter password `jane123`.\n   - Verify that her card updates to \"Clocked In\" and a success toast appears.\n2. **Verify Clocking-Out \u0026 Calculations:**\n   - Since `john_doe` is clocked in, click **Clock-Out** under his name.\n   - Enter password `john123`.\n   - Verify that he is clocked out and a success toast displays his total hours (calculated as `(ClockOut - ClockIn) / 60 minutes`).\n3. **Verify Employee Dashboard:**\n   - Go to **Sign In** (top right) and log in with `john_doe` / `john123`.\n   - View your hours breakdown (Pending vs Paid) and logs. Toggle filters.\n4. **Verify Admin Dashboard:**\n   - Log out and sign in with `admin1` / `admin123`.\n   - Go to **Admin Board**. Check the outstanding payouts under **Payroll**.\n   - Check the **Unpaid completed shifts** list. Click **Mark Paid** next to a shift.\n   - Observe that the shift disappears, and the employee's payroll balance updates instantly.\n5. **Verify User Management:**\n   - On the **User Roster Manager** tab, create a new employee `bob_builder` with rate `22.50`.\n   - Check the Kiosk Mode roster -\u003e `bob_builder` is instantly visible.\n   - In the Admin panel, delete `bob_builder` -\u003e he is removed immediately.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkuldeepsingh343%2Ftime-tracker-payroll","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkuldeepsingh343%2Ftime-tracker-payroll","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkuldeepsingh343%2Ftime-tracker-payroll/lists"}