📚 TarDetect - Attendance & Tardiness Detection System

A comprehensive Laravel 10 + React (Inertia.js) application for managing student attendance and tardiness tracking with kiosk browser capabilities.

Developed by: Johcel Gene T. Bitara

---

📋 Table of Contents

• Tech Stack
• Features
• Prerequisites
• Installation
• Running Locally
• Docker Setup
• Kiosk Browser Setup
• Available Scripts

---

🛠 Tech Stack

Backend

• Laravel 10 - Modern PHP framework
• PHP 8.1+ - Language runtime
• MySQL - Relational database
• Laravel Sanctum - API authentication
• Spatie Laravel Data - Data transfer objects

Frontend

• React 18 - UI library
• Inertia.js - Server-driven SPA framework
• TypeScript - Type-safe JavaScript
• Tailwind CSS - Utility-first CSS framework
• Material UI (MUI) - Component library
• Shadcn UI - Accessible UI components
• Radix UI - Unstyled, accessible components

Additional Libraries

• Axios - HTTP client
• TanStack React Table - Advanced data tables
• DOMPDF - PDF generation
• Barcode Generator - Barcode handling
• Log Viewer - Application logging dashboard

---

✨ Features

• 📱 Attendance Management - Track student attendance and tardiness
• 🎓 Grade Level Management - Organize students by grade levels
• 📊 Reporting & Analytics - Generate tardiness summary reports
• 🖥️ Kiosk Mode - Full-screen browser mode for public terminals
• 🔐 Role-Based Access Control - Secure authentication with different user roles
• 🎨 Modern UI/UX - Responsive design with Tailwind CSS and Material UI
• 🚀 Real-time Updates - Server-driven updates via Inertia.js

---

📦 Prerequisites

Before you begin, ensure you have the following installed:

• PHP 8.1 or higher
• Composer - PHP package manager
• Node.js 16+ & npm - JavaScript runtime and package manager
• MySQL 8.0+ - Database server
• Docker & Docker Compose - (Optional, for containerized setup)

---

🚀 Installation

1. Clone the repository

git clone <repository-url>
cd tardetect

2. Install PHP dependencies

composer install

3. Set up environment configuration

cp .env.example .env

Then edit .env with your database and application settings.

4. Generate application key

php artisan key:generate

5. Install JavaScript dependencies

npm install

6. Run database migrations

php artisan migrate

7. Set up storage and publish vendor files

php artisan storage:link
php artisan log-viewer:publish

---

🏃 Running Locally

Development Environment

Start both the Laravel backend and Vite dev server concurrently:

npm run dev

This command runs:

• Laravel backend server: http://localhost:8000
• Vite dev server for hot module replacement (HMR)

Alternative: Running Services Separately

Terminal 1 - Start Laravel:

php artisan serve --host localhost

Terminal 2 - Start Vite:

npm run dev:vite

Pull Submodules

git submodule init
git submodule update --recursive --remote

---

🐋 Running with Docker

docker build -t laravel-react:latest .
docker compose up -d

# Seed the application
docker compose exec app php artisan db:seed --force

Terminal 2 - Start Vite:

npm run dev:vite

---

🐋 Running with Docker

Build and Start Containers

docker compose build
docker compose up -d

Access the Application

• Application: http://localhost
• Database: MySQL on port 3306

View Logs

docker compose logs -f

Stop Containers

docker compose down

---

🖥️ Kiosk Browser Setup

This application supports dedicated kiosk mode for public access terminals.

Windows Setup

1. Launch Firefox in kiosk mode:

   firefox.exe -kiosk "http://your-app-url.com"

2. Configure Firefox settings:

   • Access about:config in Firefox
   • Set print.always_print_silent to true (for silent printing)
   • Disable auto-updates to prevent interruptions

Linux Setup

firefox --kiosk "http://your-app-url.com"

Additional Kiosk Tips

• Use F11 or F5 to toggle fullscreen
• Disable keyboard shortcuts to prevent user exit
• Consider using a dedicated user account with limited permissions
• Set up automatic restart scripts for reliability

---

📜 Available Scripts

Development

npm run dev           # Run Laravel + Vite dev servers concurrently
npm run build         # Compile TypeScript and build assets for production

Production

npm run production    # Build + cache configuration + optimize Laravel
npm run cache         # Clear and rebuild caches
npm run optimize      # Optimize Laravel for production
npm run clear         # Clear all caches and compiled files

---

📁 Project Structure

app/
├── Console/           # Artisan console commands
├── Http/
│   ├── Controllers/   # API & web controllers
│   ├── Requests/      # Form request validation
│   ├── Resources/     # API response resources
│   └── Middleware/    # HTTP middleware
├── Models/            # Eloquent models
├── Services/          # Business logic services
├── Repositories/      # Data access layer
├── DTOs/              # Data transfer objects
└── Exceptions/        # Custom exceptions

resources/
├── js/                # React components
├── css/               # Tailwind CSS
└── views/             # Blade templates

database/
├── migrations/        # Database migrations
├── seeders/           # Database seeders
└── factories/         # Model factories

tests/
├── Feature/           # Feature tests
└── Unit/              # Unit tests

---

🔧 Configuration

Key configuration files:

• .env - Environment variables
• config/app.php - Application configuration
• config/database.php - Database configuration
• config/auth.php - Authentication settings
• tailwind.config.js - Tailwind CSS configuration
• vite.config.js - Vite bundler configuration
• tsconfig.json - TypeScript configuration

---

📝 Database

Seeding

Populate database with sample data:

php artisan db:seed

---

🛡️ Security

• Uses Laravel Sanctum for API authentication
• CORS middleware for cross-origin requests
• SQL injection protection via Eloquent ORM
• CSRF protection on all forms
• Role-based access control for different user types

---

📊 Debugging

Using Laravel Debugbar

The application includes Laravel Debugbar for development debugging:

# Debugbar is enabled in development by default
# Visit http://localhost:8000 and check the bottom of the page

Viewing Logs

# Access log viewer dashboard
php artisan tinker
# Then visit http://localhost:8000/log-viewer

---

🤝 Contributing

This is a development project. For contributions or issues, please contact the project developer.

---

📄 License

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

---

👤 Author

Johcel Gene T. Bitara
Full Stack Developer

---

🆘 Troubleshooting

Common Issues

Port 8000 already in use:

php artisan serve --port 8001

Composer autoload issues:

composer dump-autoload

Node modules corrupted:

rm -rf node_modules package-lock.json
npm install

Database connection error:

• Verify .env DATABASE_* variables
• Ensure MySQL service is running
• Check database user permissions