Shield Logo

CYPHER-HR

The Fully Transparent, Free, & Open-Source HR Management System

Designed & Developed by KENCYPHER

Status Active License MIT Node JS PostgreSQL Vanilla JS @thesvg/icons NPM Package

---

## 🌟 The Vision & Motivation > *"I created CYPHER-HR because, working in industries and corporations, I faced a recurring issue: **employees didn't know their own leaves and reports**. This critical data was often hidden from them, creating confusion, frustration, and an imbalance of power. I believe everyone should have the right to transparently see their own leavesβ€”how much they have used, what is remaining, and their historical data. Transparency builds trust, and trust builds great companies."* > > β€” **KENCYPHER**
## 🐧 The Open Source Philosophy (100% Free) This is **NOT** a SaaS platform designed to extract monthly fees from growing businesses. In the spirit of true open-source development and drawing inspiration from the philosophy of **Linus Torvalds**, CYPHER-HR is entirely **FREE** and built for the community. Software that governs people's daily lives and working conditions shouldn't be locked behind enterprise paywalls. It should be open, auditable, modifiable, and accessible to everyone. You have full control over the source code, your data, and your infrastructure. Fork it, improve it, and host it yourself forever.
--- ## ✨ Comprehensive Feature Suite CYPHER-HR is built as an enterprise-grade Single Page Application (SPA), rivaling expensive proprietary solutions without the bloat.

πŸ‘₯ For Employees
- **Total Transparency:** An interactive dashboard displaying pending, approved, and total leave requests at a glance. - **Leave Allowances:** Real-time progress bars showing exactly how many leaves of each type are available vs. consumed. - **Seamless Applications:** A beautifully crafted form to apply for leave, complete with a custom corporate date picker that strictly formats dates as `DD:MM:YYYY`. - **Complete History:** View past applications, statuses, and administrative remarks without needing to ask HR.

πŸ‘” For Administrators & HR
- **Centralized Employee Directory:** Add, edit, deactivate, or delete employees securely. - **Password Management:** Instantly reset employee passwords if they get locked out. - **Granular Leave Controls:** Create custom leave policies (e.g., Sick, Casual, Maternity) and set exact monthly limits. - **Direct Allowance Adjustments:** Manually increment or decrement individual employee leave balances when necessary. - **Automated Monthly Resets:** A built-in backend Cron Job automatically refreshes all enabled leave allowances at midnight on the 1st of every month. - **Bulk Employee Import:** Need to onboard 500 people? Upload an entire roster at once via Excel (`.xls`, `.xlsx`) or `.csv`. A pre-formatted `CYPHER_HR_Employee_Template.csv` is included directly in the repository for quick, seamless mass-onboarding. Files are parsed instantly in the browser using the blazing-fast SheetJS library.

πŸ“Š Advanced Reporting & Exporting
- **Dynamic Data Filtering:** Query employee leave requests by date range, specific employee, or status (pending, approved, rejected). - **PDF Generation:** Instantly generate professional, styled PDF reports with tabular data using `jsPDF` and `jspdf-autotable`. - **CSV Export:** Download raw data into perfectly formatted `.csv` files for Excel or Google Sheets manipulation.

🎨 State-of-the-Art UI/UX
- **Custom Built Design System:** No massive UI frameworks (like Bootstrap or Tailwind). The entire corporate aesthetic is crafted in pure, lightweight CSS featuring glassmorphism, soft shadows, and clean typography. - **Global Dark Mode:** A native dark mode toggle providing a deep, high-contrast palette for low-light environments. - **Dynamic Iconography:** Leveraging the highly optimized `@thesvg/icons` library to fetch and render crisp vector graphics seamlessly. - **Custom Date Picker Engine:** Bypasses ugly native browser inputs with a fully custom, interactive calendar dropdown built in Vanilla JS.
--- ## πŸ› οΈ Feature Deep-Dive We don't just list features; we build them right. Here is exactly how some of the most advanced capabilities of CYPHER-HR work under the hood. ### πŸ“ˆ Bulk Employee Onboarding (Excel & CSV) Manually typing out 100 new hires is a nightmare. CYPHER-HR includes a **Mass Import Engine**. 1. **The Template:** Find the `CYPHER_HR_Employee_Template.csv` file located directly in the repository root. Open it in Microsoft Excel, Google Sheets, or Apple Numbers. 2. **The Formatting:** Just fill out `first_name`, `last_name`, `email`, and `password`. The system is smart enough to handle missing optional fields (like department or phone). 3. **The Engine:** Go to the Admin Dashboard -> Employees -> Click **Import Employees**. Upload your spreadsheet. 4. **Client-Side Parsing:** Using the blazing-fast `SheetJS` library via CDN, the dashboard parses the entire Excel file directly in your browser. This means zero lag and zero heavy lifting for your backend server! 5. **Smart Skip:** If you accidentally upload an employee who already exists, the backend intelligently skips the duplicate email without crashing the rest of the batch. ### πŸŒ— Global Dark Mode A true corporate system respects your eyes during late-night shifts. - **Not just a theme:** The dark mode toggle actively shifts the entire CSS variable hierarchy (`--bg`, `--surface`, `--text`). - **Persistent State:** Your preference is automatically saved to your browser's `localStorage`. Next time you boot up the dashboard, it remembers if you prefer light or dark mode. ### πŸ“„ PDF Reporting Engine Instead of just handing you raw data, CYPHER-HR creates beautiful, structured PDF documents. - **Powered by jsPDF:** Using `jsPDF` and `jspdf-autotable`, the frontend takes your filtered leave requests and dynamically draws a professional PDF document. - **Custom Headers:** The PDF automatically injects the current timestamp, the applied filters, and draws corporate-style tables that you can immediately send to payroll or management. ### 🌍 Local Area Network (LAN) Ready CYPHER-HR isn't just stuck on `localhost`. The backend Express server is explicitly bound to `0.0.0.0`, meaning it is instantly accessible to anyone on your local network out-of-the-box. Spin it up on a spare office computer, and your entire HR department can securely connect via the host's local IP address without any complex reverse-proxy setup.
--- ## πŸ—οΈ Deep-Dive Architecture The application utilizes a **Vanilla SPA (Single Page Application)** architecture on the frontend, communicating with a **Node.js/Express** REST API, backed by a fully normalized **PostgreSQL** database.

### 🐘 Why PostgreSQL? Because it's the absolute GOAT 🐐 of databases. Honestly, I just love it. It's fully cross-platform (meaning it runs on my toaster if I want it to), but the real reason? **The terminal.** Who needs clunky, bloated GUI wrappers taking up RAM when you can just drop into the `psql` shell, type raw SQL like a 90s movie hacker, and feel like an absolute Gigachad? πŸ—Ώ `psql` supremacy all the way.
### πŸ“‚ Detailed File Guide Want to modify the code? Here is exactly what every file in the project does: #### πŸ–₯️ Server & Database Layer | File | Description | | :--- | :--- | | **`server.js`** | The heart of the backend. It spins up the Express server, provides RESTful endpoints, handles JWT authentication/middleware, and runs the `node-cron` scheduler for monthly balance resets. | | **`db_connection.js`** | Manages the `pg` connection pool. Ensures queries to PostgreSQL are handled efficiently and handles database connection errors gracefully. | | **`schema.sql`** | The relational database blueprint. It creates the `kencypher` role, builds tables for `users`, `leave_policies`, `leave_balances`, and `leave_requests`, and establishes foreign key constraints. | | **`seed.sql`** | Optional script to populate the database with dummy data for immediate testing and demonstration. | #### 🌐 Frontend Core & UI Layer | File | Description | | :--- | :--- | | **`index.html`** | The unified HTML shell. It imports CDNs (jsPDF), Google Fonts (Inter), and all JavaScript modules. The entire app mounts inside the `
` container. | | **`styles.css`** | The complete design token system. Contains all CSS variables for the Light and Dark themes, responsive layout grids, sidebar styling, button states, and the custom date picker styling. | | **`design.js`** | The UI rendering engine. It handles loading dynamic SVGs from the local `/thesvg` route and houses the complex logic for rendering, navigating, and interacting with the custom calendar date picker. | | **`main.js`** | The central nervous system of the SPA. It handles the `App` state, checks JWT validity, triggers the theme toggler, handles asynchronous API wrappers (`App.api`), and provides global utility functions like toast notifications. | #### 🧩 Application Modules | File | Description | | :--- | :--- | | **`setup.js`** | The first-run initialization wizard. If the database is empty, this module guides the user to create the master company profile and the first Admin account. | | **`login.js`** | Renders the beautiful login screen, authenticates credentials with the backend, stores the JWT securely, and routes to the correct dashboard based on the user's role. | | **`admin.js`** | The administrative portal. Manages the DOM injection for employee directories, leave policy configuration tables, and the master leave request approval system. | | **`employee.js`** | The employee portal. Renders personalized stat cards, leave allowance progress bars, and handles the logic for submitting new time-off requests. | | **`reports.js`** | The reporting UI controller. It manages the complex filtering forms, queries the API with URL parameters, and renders the data tables. | | **`pdf_reports.js`** | The specialized PDF export engine. It takes JSON data from `reports.js`, configures document layouts, creates custom headers, and utilizes `jspdf-autotable` to draw perfectly aligned tables before initiating a browser download. | | **`Add_bulk_employees.js`** | The Excel/CSV parsing engine. Hooks into the Admin portal, manages the file upload modal, parses spreadsheets locally using SheetJS, and shoots JSON payloads to the backend for mass insertion. |
--- ## πŸš€ Complete Installation & Setup Guide Because CYPHER-HR is self-hosted, your data remains 100% yours. Follow these steps to deploy the system locally or on your own server. ### Step 1: System Requirements Ensure you have the following installed on your machine: - **Node.js** (v16 or higher) - **PostgreSQL** (v12 or higher) - **Git** ### Step 2: Database Preparation CYPHER-HR requires a dedicated PostgreSQL database and user. 1. Open your terminal and access the Postgres CLI: psql -U postgres 2. Create the user and database: ```sql CREATE USER kencypher WITH PASSWORD 'secure_password'; CREATE DATABASE cypher_hr_db OWNER kencypher; ``` 3. Initialize the schema. Exit `psql` and run: psql -U kencypher -d cypher_hr_db -f schema.sql ### Step 3: Environment Configuration Create a `.env` file in the root directory of the project. This keeps your secrets secure. ```env # Server Configuration PORT=5200 JWT_SECRET=generate_a_random_secure_string_here # Database Configuration DB_USER=kencypher DB_PASS=secure_password DB_HOST=localhost DB_PORT=5432 DB_NAME=cypher_hr_db ``` ### Step 4: Install Dependencies Install the required Node packages (`express`, `pg`, `bcryptjs`, `jsonwebtoken`, `cors`, `dotenv`): ```bash npm install ``` ### Step 5: Launch the System Start the backend server: ```bash node server.js ``` The console will confirm: `[CYPHER-HR] Server active on port 5200` and `[CYPHER-HR] Database connected`. ### Step 6: Initial Setup Wizard 1. Open your web browser and navigate to **`http://0.0.0.0:5200`** (or your server's IP address). 2. Because it is the first time running the system, CYPHER-HR will automatically present the **System Setup Wizard**. 3. Follow the UI prompts to configure your company details and create your Master Administrator account. 4. Log in and begin adding your employees!
--- ## 🀝 Contributing to CYPHER-HR Open source thrives on community. If you are a developer, designer, or HR professional who wants to improve this system: 1. **Fork** the repository. 2. Create a new branch: git checkout -b feature/amazing-new-feature 3. Commit your changes: git commit -m 'Add amazing new feature' 4. Push to the branch: git push origin feature/amazing-new-feature 5. Open a **Pull Request**. All contributions, bug reports, and feature requests are highly welcome. Let's build the ultimate free HR tool together.
## πŸ“œ License & Freedom This project is licensed under the **MIT License**. You are free to use it, modify it, distribute it, and run it for your business without ever paying a dime. As Linus Torvalds demonstrated with Linux, the greatest tools are built when we share knowledge and empower each other.

Built with passion and a commitment to transparency by KENCYPHER.

Give this repository a ⭐ if it helped your business!