moeny/freesched
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add CONTRIBUTE and update README

Browse Source
This commit is contained in:
Doug Masiero 2025-02-28 15:18:01 -05:00
parent d5c5f2838f
commit 5f019c7ed4
3 changed files with 182 additions and 78 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

107
CONTRIBUTING.md Normal file
View File

@ -0,0 +1,107 @@
# Contributing to FreeSched
Thank you for your interest in contributing to FreeSched! This document provides guidelines and instructions for contributing to this open-source scheduling tool.
## Code of Conduct
Please be respectful and considerate of others when contributing to this project. We aim to foster an inclusive and welcoming community.
## How to Contribute
### Reporting Bugs
If you find a bug in the application:
1. Check if the bug has already been reported in the Issues section
2. If not, create a new issue with a clear title and description
3. Include steps to reproduce the bug
4. Add information about your environment (OS, Node.js version, etc.)
5. If possible, include screenshots or error logs
### Suggesting Features
Have an idea for a new feature?
1. Check if the feature has already been suggested in the Issues section
2. If not, create a new issue with the tag "enhancement"
3. Provide a clear description of the feature and how it would benefit the project
4. If possible, include mockups or examples
### Pull Requests
We welcome contributions via pull requests:
1. Fork the repository
2. Create a new branch for your feature or bugfix (`git checkout -b feature/your-feature-name`)
3. Make your changes
4. Test your changes thoroughly
5. Commit your changes (`git commit -am 'Add some feature'`)
6. Push to the branch (`git push origin feature/your-feature-name`)
7. Create a new Pull Request
### Pull Request Guidelines
- Keep your changes focused on a single issue or feature
- Follow the existing code style and formatting
- Include tests if applicable
- Update documentation as needed
- Make sure all tests pass before submitting
- Provide a clear description of the changes in your PR
## Development Setup
Follow these steps to set up the project for development:
1. Clone the repository
```bash
git clone https://github.com/moeny/freesched.git
cd freesched
```
2. Install dependencies
```bash
npm install
```
3. Start the server
```bash
npm start
```
## Project Structure
- `server.js` - Express server and API endpoints
- `db/` - SQLite database and initialization
- `views/` - HTML templates for admin and public interfaces
- `public/` - JavaScript, CSS, and static assets
- `timepicker-modal/` - Custom timepicker component
## Coding Standards
- Use consistent indentation (2 spaces)
- Follow JavaScript best practices
- Comment your code when necessary
- Keep functions small and focused
- Use meaningful variable and function names
## Testing
Currently, the project does not have automated tests. Manual testing is required before submitting PRs:
1. Test both admin and user interfaces
2. Verify that time slots can be created and booked correctly
3. Test edge cases (invalid inputs, concurrent bookings, etc.)
## Documentation
If you make changes that affect how users interact with the application, please update the README.md accordingly.
## License
By contributing to FreeSched, you agree that your contributions will be licensed under the project's ISC license.
## Questions?
If you have any questions about contributing, feel free to open an issue for discussion.
Thank you for helping improve FreeSched!

153
README.md
View File

@ -1,95 +1,92 @@
# Quick Start
# FreeSched
`npm install`
A lightweight, open-source scheduling tool for managing appointments with a clean, intuitive interface.
`node server.js`
## Features
Browse to http://localhost:3000/admin for admin interface.
- **Simple Scheduling**: Create unique scheduling identifiers (UIDs) for different meeting types
- **Visual Calendar Interface**: Easy-to-use calendar for both admin and users
- **Time Slot Management**: Flexibly define available time slots on specific dates
- **Booking System**: Let others book available time slots with name, email, and notes
- **Admin Dashboard**: Manage UIDs and availability all in one place
- **Local Database**: SQLite-based storage for simplicity and portability
Create a UID and follow link in admin interface for frontend.
## Live Demo
# Introducing FreeSched: A Simpler Alternative to Cal.com
You’ve asked for a much simpler, easy-to-use version of Cal.com, named "FreeSched," that retains the clean and intuitive UI/UX of Cal.com and mirrors the simplicity of Calendly.com. Below, I’ll outline what FreeSched is, its core features, how it works, and why it’s a streamlined alternative to Cal.com—all while keeping the design aesthetic you love.
Access the main scheduling page: [http://localhost:3000/](http://localhost:3000/)
Access the admin interface: [http://localhost:3000/admin](http://localhost:3000/admin)
What is FreeSched?
FreeSched is a lightweight, open-source scheduling tool designed to make booking meetings as simple as possible. Inspired by Cal.com (an open-source scheduling infrastructure) and Calendly.com (a popular scheduling platform), FreeSched strips away complexity to focus on the essentials. It’s perfect for individuals—like freelancers, consultants, or anyone needing quick one-on-one scheduling—while maintaining a modern, minimalistic interface similar to Cal.com and Calendly.
## Quick Start
Key Features of FreeSched
FreeSched focuses on simplicity without sacrificing usability. Here’s what it offers:
### Prerequisites
Single Event Type
Users set one type of event with a fixed duration (e.g., 30 minutes).
No need to juggle multiple event types—just one straightforward option.
Basic Availability Settings
Set your available days and hours using a simple weekly grid (e.g., Monday to Friday, 9 AM to 5 PM).
Availability is divided into 30-minute slots for easy selection.
Google Calendar Integration
Connects to your Google Calendar to check existing events and prevent double-booking.
Only shows time slots when you’re truly free.
Simple Booking Page
A clean, public page (e.g., freesched.example.com/yourname) where others can pick a date and time.
Invitees provide their name and email to confirm the booking.
Email Notifications
Sends confirmation emails to you and the invitee with all the details.
Keeps everyone in the loop without extra effort.
Time Zone Support
Automatically adjusts available times to the invitee’s time zone.
No more confusion for international scheduling.
How FreeSched Works
FreeSched is designed to be intuitive for both the user (you) and the invitee (the person booking with you). Here’s the process:
- Node.js (version 12 or higher)
- npm
For You (The User):
Sign Up and Set Up
Log in with Google (which also links your Google Calendar).
Set your availability (e.g., weekdays from 9 AM to 5 PM) and event duration (e.g., 30 minutes).
Share Your Booking Link
Get a unique URL (e.g., freesched.example.com/yourname) to share via email, social media, or anywhere.
Manage Bookings
View upcoming bookings in a simple dashboard.
Cancel bookings if needed, with automatic notifications sent to both parties.
For Invitees (The Booker):
Visit Your Booking Page
They open your link and see a calendar with your available dates.
Pick a Time
They select a date and choose from your available 30-minute slots, adjusted to their time zone.
Confirm the Booking
They enter their name and email, hit confirm, and receive an email with the details.
Once booked, the event is added to your Google Calendar, and both of you get a confirmation email. That’s it—no fuss, no extra steps.
### Installation
UI/UX: Inspired by Cal.com and Calendly
FreeSched keeps the polished, user-friendly design of Cal.com and Calendly:
1. Clone the repository
```bash
git clone https://github.com/moeny/freesched.git
cd freesched
```
Clean Layout: A minimalistic interface with plenty of whitespace, clear fonts, and a simple color scheme.
Intuitive Navigation: Easy-to-use calendar for picking dates and a straightforward list of time slots.
Responsive Design: Works seamlessly on desktops, tablets, and phones.
Booking Flow: Select a date → pick a time → enter details → confirm—all in a few clicks.
Think of Calendly’s booking page or Cal.com’s sleek dashboard, but pared down to the essentials. The focus is on clarity and ease, avoiding overwhelming options or cluttered screens.
2. Install dependencies
```bash
npm install
```
How It’s Simpler Than Cal.com
Cal.com is a powerful scheduling infrastructure with tons of features, but that can make it overkill for simple needs. FreeSched simplifies things:
3. Start the server
```bash
npm start
```
Feature Cal.com FreeSched
Event Types Multiple (15-min, 30-min, etc.) One fixed duration (e.g., 30 min)
Availability Detailed rules and buffers Basic weekly grid
Integrations Multiple calendars, payments, etc. Google Calendar only
Team Support Yes (shared schedules, etc.) Individual use only
Customization Highly customizable Simple, uniform design
FreeSched cuts out the extras to deliver a tool that’s fast to set up and easy to use, while still looking and feeling like its more complex cousins.
4. Access the application
- Admin interface: [http://localhost:3000/admin](http://localhost:3000/admin)
- Create a UID in the admin interface
- Access your scheduling page at: http://localhost:3000/YOUR-UID
Technical Overview (For the Curious)
FreeSched is built with modern, open-source tools:
## Usage Guide
Frontend: Next.js (a React framework for fast, server-rendered pages).
Backend: Node.js with Express.js for handling bookings and logic.
Database: PostgreSQL with Prisma to store user data and bookings.
Authentication: NextAuth.js with Google OAuth for login and calendar access.
Emails: SendGrid or Nodemailer for notifications.
This keeps FreeSched lightweight, secure, and easy to maintain, with a tech stack similar to Cal.com but scaled back for simplicity.
### Admin Interface
Why Use FreeSched?
FreeSched is for anyone who wants a free, no-nonsense scheduling tool:
1. **Create a UID**: Click "Create" button and enter a unique identifier
2. **Manage Availability**:
- Select a UID from the dropdown
- Navigate through the calendar to select dates
- Add and manage time slots for each date
3. **Clear Availability**: Reset all availability for a specific UID
4. **Delete UID**: Remove a UID and all its associated availability data
Perfect For: Freelancers, tutors, consultants, or anyone needing simple one-on-one bookings.
Benefits: Quick setup, no learning curve, and a professional look inspired by Cal.com and Calendly.
Open-Source: Like Cal.com, it’s free to use and customizable if you’re a developer.
It’s scheduling made easy—just share a link and let others book you, all wrapped in a familiar, user-friendly package.
### User Scheduling Interface
1. Users visit your unique scheduling link
2. They select an available date from the calendar
3. They choose an available time slot
4. They enter their contact information to confirm the booking
## Development
The project structure is organized as follows:
- `server.js` - Express server and API endpoints
- `db/` - SQLite database and initialization
- `views/` - HTML templates for admin and public interfaces
- `public/` - JavaScript, CSS, and static assets
- `timepicker-modal/` - Custom timepicker component
## Technologies Used
- **Backend**: Node.js with Express
- **Database**: SQLite3
- **Frontend**: HTML, CSS, JavaScript
- **UI Framework**: Bootstrap 5
- **Icons**: Bootstrap Icons
## License
ISC
## GitHub Repository
[https://github.com/moeny/freesched](https://github.com/moeny/freesched)

BIN
db/freesched.db
View File

Binary file not shown.