https://github.com/berkanserbes/smart-appointment-system
Smart, secure appointment management API built with Spring Boot, JWT, Redis, and PostgreSQL. Includes automated email reminders, role-based access, and admin reporting.
https://github.com/berkanserbes/smart-appointment-system
java java-security spring-boot
Last synced: about 9 hours ago
JSON representation
Smart, secure appointment management API built with Spring Boot, JWT, Redis, and PostgreSQL. Includes automated email reminders, role-based access, and admin reporting.
- Host: GitHub
- URL: https://github.com/berkanserbes/smart-appointment-system
- Owner: berkanserbes
- License: mit
- Created: 2026-02-12T14:20:00.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-05-12T11:35:19.000Z (about 2 months ago)
- Last Synced: 2026-05-12T12:34:58.044Z (about 2 months ago)
- Topics: java, java-security, spring-boot
- Language: Java
- Homepage:
- Size: 176 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# 📅 Smart Appointment System
### A modern, secure, and scalable appointment management platform
[](https://openjdk.org/)
[](https://spring.io/projects/spring-boot)
[](https://www.postgresql.org/)
[](https://redis.io/)
[](https://www.docker.com/)
[](LICENSE)
[Features](#-features) • [Quick Start](#-quick-start) • [Documentation](#-documentation) • [Tech Stack](#tech-stack) • [Contributing](#-contributing)
---
## 🌟 Features
### 🔐 Authentication & Security
- JWT-based authentication
- Role-based access control (USER/ADMIN)
- BCrypt password encryption
- Secure session management
### 📊 Appointment Management
- Complete lifecycle management
- Conflict detection
- Status tracking (Scheduled, Confirmed, Completed, etc.)
- Time slot validation
### 🚀 Performance & Scalability
- Redis caching layer with graceful fallback
- Scheduled background task processing
- Email notification delivery via SMTP
- Docker containerization
### 📝 Audit & Compliance
- Comprehensive audit logging
- User action tracking
- IP address recording
- Compliance-ready reports
### ✨ Additional Features
- 👥 **Service Provider Management** - Manage professionals and their services
- 📍 **Location Management** - Multiple location support
- 🏷️ **Category System** - Organize appointments by type
- ⭐ **Feedback System** - Collect and manage user reviews
- 📧 **Email Notifications** - Automated reminder system
- 📈 **Reporting Dashboard** - Admin analytics and insights
- 📖 **API Documentation** - Interactive Swagger UI
---
## 🚀 Quick Start
### Prerequisites
- Docker & Docker Compose
- Java 25 (for local development)
- Maven 3.9+ (for local development)
### 🐳 Run with Docker (Recommended)
```bash
# 1. Clone the repository
git clone https://github.com/yourusername/smart-appointment-system.git
cd smart-appointment-system
# 2. Setup environment
cp .env.example .env.development
# Edit .env.development with your configuration
# 3. Start all services
docker-compose --env-file .env.development up --build
# 4. Access the application
API: http://localhost:8080
Swagger UI: http://localhost:8080/swagger-ui.html
```
### 💻 Local Development
```bash
# 1. Start PostgreSQL and Redis
docker-compose up postgres redis -d
# 2. Run the application
mvn spring-boot:run
# 3. Access Swagger UI
open http://localhost:8080/swagger-ui.html
```
---
## 📚 Documentation
| Document | Description |
|----------|-------------|
| 📖 [Architecture](docs/ARCHITECTURE.md) | System design and architecture patterns |
| 🗄️ [Database Schema](docs/DATABASE_SCHEMA.md) | Complete database structure and relationships |
| 🐳 [Docker Guide](docs/DOCKER_GUIDE.md) | Docker setup and commands |
| ⚙️ [Environment Setup](docs/ENVIRONMENT_SETUP.md) | Configuration and environment variables |
| 🤝 [Contributing](CONTRIBUTING.md) | How to contribute to the project |
---
## Tech Stack
### Backend Framework
### Database & Cache
### Security & API
### DevOps & Tools
---
## 🏗️ Architecture
```
┌─────────────────────────────────────────┐
│ Client Applications │
└──────────────┬──────────────────────────┘
│ REST API
┌──────────────▼──────────────────────────┐
│ Controller Layer │
│ • Request validation │
│ • Response formatting │
└──────────────┬──────────────────────────┘
│ DTOs
┌──────────────▼──────────────────────────┐
│ Service Layer │
│ • Business logic │
│ • Transaction management │
│ • Authorization │
└──────────────┬──────────────────────────┘
│ Entities
┌──────────────▼──────────────────────────┐
│ Repository Layer │
│ • Data access │
│ • Query optimization │
└──────────────┬──────────────────────────┘
│
┌──────────┴──────────┐
▼ ▼
┌──────────┐ ┌──────────┐
│PostgreSQL│ │ Redis │
└──────────┘ └──────────┘
```
**Key Design Patterns:**
- 🎯 Repository Pattern
- 🔄 DTO Pattern
- 🏭 Service Layer Pattern
- 🗺️ Mapper Pattern
- 🔨 Builder Pattern
---
## 📊 Project Structure
```
smart-appointment-system/
├── 📁 src/main/java/com/smartappointment/
│ ├── 🔧 config/ # Configuration classes
│ ├── 🎮 controller/ # REST endpoints
│ ├── 📦 dto/ # Data Transfer Objects
│ ├── ⚠️ exception/ # Custom exceptions
│ ├── 🗺️ mapper/ # Entity-DTO mappers
│ ├── 📊 model/ # JPA entities & enums
│ ├── 💾 repository/ # Data access layer
│ ├── 🔐 security/ # Security components
│ ├── 💼 service/ # Business logic
│ └── 🛠️ util/ # Utility classes
│
├── 📁 docs/ # Documentation
│ ├── ARCHITECTURE.md
│ ├── DATABASE_SCHEMA.md
│ ├── DOCKER_GUIDE.md
│ └── ENVIRONMENT_SETUP.md
│
├── 🐳 docker-compose.yml # Docker orchestration
├── 📋 Dockerfile # Application container
├── 📝 pom.xml # Maven dependencies
└── 📖 README.md # You are here!
```
---
## 🔒 Security Features
- 🔐 **JWT Authentication** - Stateless token-based auth
- 👤 **Role-Based Access Control** - USER and ADMIN roles
- 🔑 **Password Encryption** - BCrypt hashing
- 🛡️ **CORS Protection** - Configurable CORS policies
- 📝 **Audit Logging** - Complete action tracking
- 🚫 **Input Validation** - Request validation with Bean Validation
---
## 🎯 API Endpoints
### 🔓 Public Endpoints
- `POST /api/auth/register` - User registration
- `POST /api/auth/login` - User login
### 🔐 Protected Endpoints
- `GET /api/appointments` - List appointments
- `POST /api/appointments` - Create appointment
- `GET /api/categories` - List categories
- `GET /api/providers` - List service providers
- `POST /api/feedback` - Submit feedback
### 👑 Admin Only
- `GET /api/reports/dashboard` - Admin dashboard
- `POST /api/categories` - Create category
- `DELETE /api/appointments/{id}` - Delete appointment
**📖 Full API documentation available at:** `http://localhost:8080/swagger-ui.html`
---
## 🧪 Testing
```bash
# Run all tests
mvn test
# Run with coverage
mvn test jacoco:report
# Run specific test
mvn test -Dtest=AppointmentServiceTest
```
---
## 🤝 Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
### Quick Contribution Steps
1. 🍴 Fork the repository
2. 🌿 Create your feature branch (`git checkout -b feature/amazing-feature`)
3. ✅ Commit your changes (`git commit -m 'feat: add amazing feature'`)
4. 📤 Push to the branch (`git push origin feature/amazing-feature`)
5. 🎉 Open a Pull Request
---
## 📝 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
---
### ⭐ Star this repository if you find it helpful!