From 7fdd7285a491c08db12c61e94ca13992e1971a9e Mon Sep 17 00:00:00 2001 From: mikicvi <88291034+mikicvi@users.noreply.github.com> Date: Sun, 28 Sep 2025 21:49:56 +0100 Subject: [PATCH] restructure docs and config, license, readme redo --- .gitignore | 22 +- License.md | 27 ++ README.md | 259 +++++++----------- .env.sample => config/.env.sample | 0 .../cloudflare-tunnel-config.yml | 0 .../docker-compose.sample.yml | 0 DATABASE_SETUP.md => docs/DATABASE_SETUP.md | 0 .../DEPLOYMENT_GUIDE.md | 0 8 files changed, 139 insertions(+), 169 deletions(-) create mode 100644 License.md rename .env.sample => config/.env.sample (100%) rename cloudflare-tunnel-config.yml => config/cloudflare-tunnel-config.yml (100%) rename docker-compose.sample.yml => config/docker-compose.sample.yml (100%) rename DATABASE_SETUP.md => docs/DATABASE_SETUP.md (100%) rename DEPLOYMENT_GUIDE.md => docs/DEPLOYMENT_GUIDE.md (100%) diff --git a/.gitignore b/.gitignore index 2aa829e..7c018a2 100644 --- a/.gitignore +++ b/.gitignore @@ -17,6 +17,8 @@ node_modules/ npm-debug.log* yarn-debug.log* yarn-error.log* +logs/ +*.log # Runtime data pids @@ -28,10 +30,14 @@ pids *.db *.sqlite *.sqlite3 +data/ +backups/ # IDE .vscode/ .idea/ +*.swp +*.swo # OS generated files .DS_Store @@ -48,6 +54,18 @@ build/ # Coverage directory used by tools like istanbul coverage/ - -# nyc test coverage .nyc_output +# Temporary files +*.tmp +*.temp +tmp/ +temp/ + +# Backups +*.bak +*.backup + +# Runtime directories (created during execution) +/logs +/backups +/data diff --git a/License.md b/License.md new file mode 100644 index 0000000..eb0d38b --- /dev/null +++ b/License.md @@ -0,0 +1,27 @@ +## License + +This project is licensed under the MIT License: + +``` +MIT License + +Copyright (c) 2024 Table Tennis Booking System + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. +``` diff --git a/README.md b/README.md index 418210d..bfa0bae 100644 --- a/README.md +++ b/README.md @@ -2,133 +2,93 @@ A modern, full-stack table tennis court booking system built with Next.js, shadcn/ui, and SQLite. -## Features +## ✨ Features -### User Features +- **🔐 Secure Authentication**: JWT-based registration and login +- **📅 Interactive Calendar**: Real-time court availability and booking +- **📧 Email Notifications**: Automatic booking confirmations +- **📱 Mobile-First Design**: Responsive UI for all devices +- **� Admin Panel**: Court management, user administration, analytics +- **🔒 Security**: Rate limiting, input validation, password hashing -- **Secure Authentication**: User registration and login with JWT tokens -- **Court Booking**: Interactive booking calendar with real-time availability -- **Email Notifications**: Automatic confirmation and cancellation emails -- **Mobile-First Design**: Responsive UI that works on all devices -- **Booking Management**: View and manage your bookings - -### Admin Features - -- **Court Management**: Add/remove courts and configure availability -- **Time Slot Configuration**: Set operating hours for different days -- **User Management**: View and manage user accounts -- **Booking Override**: Admin can edit or cancel any booking -- **Announcements**: Create and manage system announcements -- **Activity Logs**: Comprehensive logging of all system activities -- **Analytics Dashboard**: Booking statistics and usage metrics - -### System Features - -- **7-Day Booking Window**: Users can only book up to 1 week in advance -- **Real-time Validation**: Both client and server-side booking validation -- **Secure Backend**: SQLite database with Drizzle ORM -- **Docker Support**: Easy deployment with Docker and reverse proxy -- **Email Integration**: Gmail SMTP integration for notifications - -## Technology Stack - -- **Frontend**: Next.js 14, React, TypeScript -- **UI Components**: shadcn/ui, Tailwind CSS, Radix UI -- **Backend**: Next.js API routes, Drizzle ORM -- **Database**: SQLite -- **Authentication**: JWT tokens with httpOnly cookies -- **Email**: Nodemailer with Gmail -- **Deployment**: Docker, Nginx reverse proxy - -## Quick Start +## 🚀 Quick Start ### Prerequisites - Node.js 18+ -- npm or yarn -- Gmail account for email notifications +- npm/yarn +- Gmail account (for notifications) ### Installation -1. **Clone the repository** - - ```bash - git clone - cd tt-booking - ``` - -2. **Install dependencies** - - ```bash - npm install - ``` - -3. **Set up environment variables** - - ```bash - cp .env.example .env.local - ``` - - Edit `.env.local` with your configuration: - - ```env - NEXTAUTH_SECRET="your-secret-key-here-make-this-very-long-and-random" - EMAIL_USER="your-email@gmail.com" - EMAIL_PASSWORD="your-gmail-app-password" - ADMIN_EMAIL="admin@example.com" - ADMIN_PASSWORD="admin123" - ``` - -4. **Set up the database** - - ```bash - npm run db:push - ``` - -5. **Run the development server** - - ```bash - npm run dev - ``` - -6. **Access the application** - - User interface: http://localhost:3000 - - Admin panel: http://localhost:3000/admin - -## Configuration - -### Gmail Setup - -1. Enable 2-factor authentication on your Gmail account -2. Generate an App Password: Google Account > Security > App passwords -3. Use the App Password as `EMAIL_PASSWORD` in your environment variables - -### Default Settings - -- **Courts**: 2 courts (configurable via admin panel) -- **Monday/Tuesday**: 19:00-23:00 (configurable) -- **Sunday**: 12:00-17:00 (configurable) -- **Booking window**: 7 days from current date - -## Docker Deployment - -### Development - ```bash -docker-compose up -d +# Clone and install +git clone +cd tt-booking +npm install + +# Configure environment +cp .env.sample .env.local +# Edit .env.local with your settings + +# Setup database +npm run db:setup + +# Start development +npm run dev ``` -### Production +**Access**: http://localhost:3000 (Admin: `/admin`) -1. **Update environment variables** in `docker-compose.yml` -2. **Configure SSL certificates** in the `ssl` directory -3. **Update domain** in `nginx.conf` -4. **Deploy**: - ```bash - docker-compose -f docker-compose.yml up -d - ``` +## 🔧 Configuration -## Project Structure +Create `.env.local` with: + +```env +NEXTAUTH_SECRET=your-very-long-random-secret-key +NEXTAUTH_URL=http://localhost:3000 +ADMIN_EMAIL=admin@your-domain.com +ADMIN_PASSWORD=your-secure-password + +# Optional - Email notifications +EMAIL_USER=your-email@gmail.com +EMAIL_PASSWORD=your-gmail-app-password +``` + +## 🗄️ Database Commands + +```bash +npm run db:setup # Full database setup +npm run db:seed # Essential data only +npm run db:reset-confirm # Reset database +npm run db:studio # Open database GUI +``` + +## 🐳 Deployment + +### Production (Docker) + +```bash +cp .env.sample .env.production +docker compose -f docker-compose.production.yml up -d +``` + +### Home Server + +```bash +./setup-tunnel.sh # Setup Cloudflare tunnel +./deploy.sh # Deploy +``` + +## 🛠️ Technology Stack + +- **Frontend**: Next.js 14, React, TypeScript, shadcn/ui, Tailwind CSS +- **Backend**: Next.js API routes, SQLite, Drizzle ORM +- **Auth**: JWT with httpOnly cookies +- **Email**: Nodemailer + Gmail +- **Deployment**: Docker, Nginx + +## 🗂️ Project Structure ``` tt-booking/ @@ -139,63 +99,28 @@ tt-booking/ │ └── layout.tsx # Root layout ├── components/ # React components │ ├── ui/ # shadcn/ui components -│ ├── auth/ # Authentication forms -│ ├── booking/ # Booking components -│ └── admin/ # Admin components -├── lib/ # Utility libraries -│ ├── db/ # Database schema and connection -│ ├── auth.ts # Authentication utilities -│ ├── email.ts # Email functionality -│ └── utils.ts # General utilities -├── docker-compose.yml # Docker configuration -├── Dockerfile # Container definition -└── nginx.conf # Reverse proxy configuration +│ ├── auth/ # Authentication +│ ├── booking/ # Booking system +│ └── admin/ # Admin interface +├── lib/ # Utilities +│ ├── db/ # Database schema +│ ├── auth.ts # Authentication +│ └── email.ts # Email service +├── scripts/ # Database scripts +│ ├── setup-database.ts # Database setup +│ └── reset-db.ts # Database reset +└── docker-compose.*.yml # Deployment configs ``` -## API Endpoints - -### Authentication - -- `POST /api/auth/login` - User login -- `POST /api/auth/register` - User registration -- `POST /api/auth/logout` - User logout - -### Bookings - -- `GET /api/bookings` - Get user bookings -- `POST /api/bookings` - Create booking -- `PUT /api/bookings/[id]` - Update booking -- `DELETE /api/bookings/[id]` - Cancel booking - -### Admin - -- `GET /api/admin/stats` - Dashboard statistics -- `GET /api/admin/courts` - Manage courts -- `GET /api/admin/settings` - System settings -- `GET /api/admin/logs` - Activity logs - -## Security Features - -- **Rate Limiting**: API endpoints are rate-limited via Nginx -- **CSRF Protection**: Built-in Next.js CSRF protection -- **SQL Injection Prevention**: Drizzle ORM parameterized queries -- **XSS Protection**: Content Security Policy headers -- **Secure Cookies**: httpOnly, secure, sameSite cookies -- **Input Validation**: Zod schema validation -- **Password Hashing**: bcrypt with salt rounds - -## Contributing +## 🤝 Contributing 1. Fork the repository -2. Create a feature branch -3. Make your changes -4. Add tests if applicable -5. Submit a pull request +2. Create feature branch +3. Make changes and test +4. Submit pull request -## License +## 🆘 Support -This project is licensed under the MIT License. - -## Support - -For issues and questions, please create an issue in the repository. +- 📚 [Database Setup Guide](docs/DATABASE_SETUP.md) +- 🚀 [Deployment Guide](docs/DEPLOYMENT_GUIDE.md) +- 🐛 Create an issue for bugs or questions diff --git a/.env.sample b/config/.env.sample similarity index 100% rename from .env.sample rename to config/.env.sample diff --git a/cloudflare-tunnel-config.yml b/config/cloudflare-tunnel-config.yml similarity index 100% rename from cloudflare-tunnel-config.yml rename to config/cloudflare-tunnel-config.yml diff --git a/docker-compose.sample.yml b/config/docker-compose.sample.yml similarity index 100% rename from docker-compose.sample.yml rename to config/docker-compose.sample.yml diff --git a/DATABASE_SETUP.md b/docs/DATABASE_SETUP.md similarity index 100% rename from DATABASE_SETUP.md rename to docs/DATABASE_SETUP.md diff --git a/DEPLOYMENT_GUIDE.md b/docs/DEPLOYMENT_GUIDE.md similarity index 100% rename from DEPLOYMENT_GUIDE.md rename to docs/DEPLOYMENT_GUIDE.md