Getting Started

This guide will help you get Timesheet up and running in your environment. Timesheet is a Next.js 15 application designed for Australian businesses requiring workforce management and award compliance.

Prerequisites

Before installing Timesheet, ensure you have:

System Requirements

• Node.js 18.17 or later
• MongoDB 4.4 or later (local or MongoDB Atlas)
• Git for version control

Optional Services

• Cloudinary account for image storage (employee photos, clock-in images)
• SMTP server for email notifications
• SSL certificate for production deployment

Quick Start

The fastest way to get started is with our installation script:

# Clone the repository
git clone https://github.com/your-org/timesheet.git
cd timesheet

# Install dependencies
npm install

# Copy environment template
cp .env.example .env.local

# Configure your environment (see Configuration guide)
# Edit .env.local with your settings

# Run database setup
npm run db:setup

# Start development server
npm run dev

Your Timesheet application will be available at http://localhost:3000.

What's Next?

After installation, follow these steps:

Architecture Overview

Timesheet is built with modern web technologies:

Frontend

• Next.js 15 with App Router for server-side rendering
• React 18 with Server Components and Suspense
• TypeScript for type safety
• Tailwind CSS with shadcn/ui components

Backend

• Next.js API Routes for RESTful API
• MongoDB with Mongoose ODM
• JWT Authentication with role-based access control
• Cloudinary for image storage

Key Features

• Offline Support - Works without internet connection
• Face Detection - Optional photo capture during clock in/out
• Geofencing - Location-based restrictions
• Multi-tenant - Support for multiple employers/locations
• Australian Compliance - Award wages and penalty rates

Development vs Production

Development Environment

• Uses npm run dev for hot reloading
• SQLite fallback for local development
• Detailed error messages and debugging
• Mock external services

Production Environment

• Optimised build with npm run build
• MongoDB Atlas recommended
• Error logging and monitoring
• SSL/HTTPS required
• Environment variable validation

Getting Help

If you encounter issues during setup:

1. Check the logs - Development server shows detailed error messages
2. Verify environment variables - Ensure all required variables are set
3. Database connection - Test MongoDB connectivity
4. Port conflicts - Default port 3000 may be in use

Next Steps

Once you have Timesheet running locally, proceed to:

• Configuration - Set up environment variables and external services
• First Setup - Create your initial admin user and basic configuration
• Installation - Detailed installation instructions for different environments