🕐 Open Attendance

All-in-One Attendance & Leave Management for Startups

English | 한국어

---

📋 Table of Contents

• Overview
• Features
• Tech Stack
• Quick Start
• Contributing
• License

---

🎯 Overview

Open Attendance is an open-source attendance and leave management system designed for small to medium-sized teams (especially startups). It provides a unified platform to handle daily check-in/out tracking, annual leave management, sick leave processing, and insight reporting.

Why Open Attendance?

• ✅ Free & Open Source - No licensing fees, full transparency
• 🚀 Easy Deployment - Simple setup with automated scripts
• 🌏 Multilingual - Korean and English support by default
• 📊 Comprehensive Reporting - Track attendance and leave patterns
• 🔒 Security - Strong authentication using NextAuth.js
• 🎨 Modern UI - Beautiful interface built with Tailwind CSS and Radix UI

---

✨ Features

📅 Attendance Management

• Attendance Recording - Record check-in and check-out on all working days (excluding holidays)
• Early Leave/Absence - Record and track reasons for early leave or absence

🏖️ Leave Management

• Leave Tracking - Monitor total, used, and remaining annual leave
• Automatic Calculation Based on Hire Date - Annual leave automatically calculated according to Korean labor law
  • First year: 1 day per month (up to 11 days)
  • After 1 year: 15 days granted at once
• Leave Request Workflow - Submit, approve, and track leave requests
• Diverse Leave Types:
  • Annual Leave
    • Full day (1.0)
    • Half day (0.5)
    • Quarter day (0.25)
  • Sick Leave
  • Official Leave
  • Early Leave
  • Other
• Korean Labor Law Compliant - Applies standard Korean annual leave regulations
• Leave Balance Dashboard - Real-time leave status at a glance

👥 User Management

• Role-Based Access Control (RBAC):
  • Admin (ADMIN) - Full system access and management permissions
  • Regular User (USER) - View and manage personal attendance and leave data
• Secure Authentication - Powered by NextAuth.js
• User Profiles - Manage personal information and settings

🌐 Internationalization (i18n)

• Korean - Full Korean language support
• English - Full English translation
• Easy Toggle - Seamless language switching

---

🚀 Quick Start

Get Open Attendance up and running in minutes!

Prerequisites

• Node.js 20.x or higher
• npm 10.x or higher
• Git

Clone the Repository

git clone https://github.com/thsvkd/open-attendance.git

Setup & Execution

Dependency Installation & Initial Setup

# Development setup
./scripts/setup.sh

# Or production setup
./scripts/setup.sh --prod

Running the Server

# Run in development mode
./scripts/run.sh

# Or run in production mode
./scripts/run.sh --prod

# Run on a custom port
./scripts/run.sh --port 3001

After the server starts, open http://localhost:3000 in your browser! 🎉

💡 Tip: For detailed documentation on the provided scripts, refer to scripts/README.md.

---

⚙️ Configuration

Environment Variables

Variable	Description	Required	Default
DATABASE_URL	Database connection string	Yes	file:./dev.db
NEXTAUTH_URL	Application URL	Yes	http://localhost:3000
NEXTAUTH_SECRET	NextAuth secret key	Yes	Auto-generated

Database Setup

Development Environment: SQLite (Default)

DATABASE_URL="file:./dev.db"

Production Environment: PostgreSQL (Recommended)

DATABASE_URL="postgresql://user:password@host:5432/database?schema=public"

---

Database Management

Run Prisma Studio (Database GUI):

npx prisma studio

Create a Migration:

npx prisma migrate dev --name your_migration_name

Reset Database:

npx prisma migrate reset

Update Annual Leave Balances (Recalculate annual leave for existing users based on hire date):

npm run db:update-annual-leave

---

🤝 Contributing

We welcome community contributions!

• 🐛 Bug Reports
• 💡 Feature Requests
• 📝 Documentation Improvements
• 🔧 Code Contributions

For details, please refer to the Contributing Guide.

Quick Start for Contributors

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

See CONTRIBUTING.md for detailed guidelines.

---

📚 Documentation

• Contributing Guide - How to contribute
• Security Policy - Security best practices
• Testing Guide - Testing documentation
• Deployment Guide - Production deployment
• Architecture - System architecture overview

---

🐛 Troubleshooting

NextAuth Configuration Error

Error:

[next-auth][warn][NEXTAUTH_URL]
[next-auth][warn][NO_SECRET]
GET /api/auth/error?error=Configuration 500

Solution: Run the setup script to configure environment variables:

./scripts/setup.sh

Database Connection Issues

Error: Can't reach database server

Solution: Verify the DATABASE_URL in .env.local and ensure your database server is reachable.

Port Already in Use

Error: Port 3000 is already in use

Solution: Terminate the process using port 3000 or use a different port:

PORT=3001 npm run dev

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🛠 Tech Stack

Built with the following modern technologies:

• Next.js
• Prisma
• NextAuth.js
• Tailwind CSS
• Radix UI

---

⬆ Back to Top

Made with ❤️ by the Open Attendance Team