A complete, production-ready Spring Boot 3.x backend for the Ween platform, a student/youth volunteering platform for Azerbaijan. This project implements a full-featured microservice architecture for managing volunteers, organizations, events, certificates, and gamification elements.

Ween is a digital platform connecting student volunteers with NGOs and community organizations for meaningful volunteer work. The platform features:

• User Management: Volunteers and Organization accounts with profiles
• Event Management: Organizations can create and manage events
• Registration System: Volunteers register for events with tracking
• Gamification: Ween Coins reward system with leaderboards
• Certificates: Automatic PDF certificate generation for participants
• QR Check-in: Secure QR-based attendance verification
• Notifications: In-app and email notifications
• Referral Program: Coin rewards for successful referrals
• Admin Dashboard: Platform statistics and user management

ween-backend/
├── pom.xml
├── Dockerfile
├── docker-compose.yml
├── .env.example
├── README.md
└── src/
    ├── main/
    │   ├── java/com/ween/
    │   │   ├── WeenApplication.java
    │   │   ├── config/
    │   │   │   ├── SecurityConfig.java
    │   │   │   ├── RedisConfig.java
    │   │   │   ├── S3Config.java
    │   │   │   ├── FirebaseConfig.java
    │   │   │   ├── OpenApiConfig.java
    │   │   │   └── AsyncConfig.java
    │   │   ├── entity/
    │   │   │   ├── BaseEntity.java
    │   │   │   ├── User.java
    │   │   │   ├── Organization.java
    │   │   │   ├── Event.java
    │   │   │   ├── EventRegistration.java
    │   │   │   ├── QrToken.java
    │   │   │   ├── Certificate.java
    │   │   │   ├── CoinTransaction.java
    │   │   │   ├── LeaderboardEntry.java
    │   │   │   ├── Notification.java
    │   │   │   └── Referral.java
    │   │   ├── enums/
    │   │   │   ├── UserRole.java
    │   │   │   ├── EventCategory.java
    │   │   │   ├── EventStatus.java
    │   │   │   ├── CoinReason.java
    │   │   │   ├── CertificateTemplate.java
    │   │   │   ├── SubscriptionPlan.java
    │   │   │   ├── NotificationType.java
    │   │   │   ├── LeaderboardPeriod.java
    │   │   │   └── LeaderboardScope.java
    │   │   ├── repository/ (10 repositories)
    │   │   ├── dto/
    │   │   │   ├── request/ (12 request DTOs)
    │   │   │   └── response/ (15 response DTOs)
    │   │   ├── mapper/ (6 MapStruct mappers)
    │   │   ├── service/ (14 services)
    │   │   ├── controller/ (9 controllers)
    │   │   ├── security/ (JWT, AES, Filters)
    │   │   ├── exception/ (Custom exceptions)
    │   │   └── scheduler/ (Background jobs)
    │   └── resources/
    │       ├── application.yml
    │       ├── application-dev.yml
    │       ├── application-prod.yml
    │       └── db/migration/
    │           ├── V1__create_tables.sql
    │           ├── V2__add_constraints.sql
    │           ├── V3__add_indexes.sql
    │           └── V4__seed_data.sql
    └── test/
        └── java/com/ween/
            ├── service/ (5 unit test classes)
            └── controller/ (3 integration test classes)

• Java 17+
• Maven 3.9.0+
• Docker & Docker Compose
• MySQL 8.0 (if not using Docker)
• Redis 7 (if not using Docker)

# Clone repository
git clone <repository-url>
cd ween-backend

# Copy environment variables
cp .env.example .env

# Start all services (MySQL, Redis, MinIO, MailHog, App)
docker-compose up -d

# Wait for app to start
docker logs -f ween-backend

# Access the application
# API: http://localhost:5000
# Swagger UI: http://localhost:5000/swagger-ui.html
# MinIO Console: http://localhost:9001 (minioadmin/minioadmin)
# MailHog: http://localhost:8025

This project includes a render.yaml blueprint for a Docker-based web service.

1. Render does not provide a managed MySQL database, so you must use an external MySQL provider (PlanetScale, Aiven, DigitalOcean Managed MySQL, Railway, etc.).
2. In Render, create a new Web Service from this repository and use the Dockerfile.
3. Set the service environment to prod via SPRING_PROFILES_ACTIVE=prod.
4. Fill the required environment variables in Render:

• DB_URL
• DB_USERNAME
• DB_PASSWORD
• MAIL_HOST
• MAIL_USERNAME
• MAIL_PASSWORD
• JWT_SECRET
• AES_SECRET_KEY
• ORGANIZER_API_KEY
• CORS_ORIGINS

5. Keep the public URLs aligned with your frontend:

• VERIFY_EMAIL_URL=https://ween.az/verify-email
• RESET_PASSWORD_URL=https://ween.az/change-password

6. Deploy. Render will set PORT automatically; the app reads it from the environment.

Important: if any of DB_URL, DB_USERNAME, or DB_PASSWORD are missing, the app will start and then fail during JPA initialization.

Use a real public MySQL endpoint, not localhost:

DB_URL=jdbc:mysql://YOUR_MYSQL_HOST:3306/YOUR_DB?useSSL=false&allowPublicKeyRetrieval=true&serverTimezone=UTC
DB_USERNAME=YOUR_DB_USER
DB_PASSWORD=YOUR_DB_PASSWORD

If DB_URL points to localhost, the Render service will fail because localhost is the container itself.

• The app uses PORT from the environment, so do not hardcode a different server port in Render.
• Swagger remains available at /swagger-ui.html.
• For email sending, use a Gmail App Password in MAIL_PASSWORD and the Gmail address in MAIL_USERNAME.

# Build project
mvn clean install

# Run with dev profile
SPRING_PROFILES_ACTIVE=dev mvn spring-boot:run

# Or create application-local.yml and use it
SPRING_PROFILES_ACTIVE=local mvn spring-boot:run

• Authentication: JWT-based stateless authentication
• Authorization: Role-based access control (VOLUNTEER, ORGANIZER, ADMIN)
• Password Hashing: BCrypt strength 12
• Token Storage: Redis-based token blacklist
• API Key Auth: For QR check-in endpoints
• AES-256 Encryption: For QR token payloads
• CORS: Configurable allowed origins
• Rate Limiting: Bucket4j for API rate limiting

User -> POST /api/v1/auth/login 
        -> Receive accessToken (15 min) + refreshToken (7 days)
User -> Include Bearer token in Authorization header
        -> Filter validates & sets SecurityContext
User -> POST /api/v1/auth/logout 
        -> Token added to Redis blacklist

Users earn Ween Coins through various activities:

All endpoints return wrapped ApiResponse<T> objects:

{
  "success": true,
  "data": { /* response data */ },
  "message": "OK",
  "timestamp": "2025-01-15T10:30:00Z"
}

• POST /api/v1/auth/register - Register new user
• POST /api/v1/auth/login - User login
• POST /api/v1/auth/refresh - Refresh token
• POST /api/v1/auth/logout - Logout

• GET /api/v1/events - List events with filters
• GET /api/v1/events/{id} - Event detail
• POST /api/v1/events - Create event (ORGANIZER)
• PUT /api/v1/events/{id} - Update event (ORGANIZER)
• POST /api/v1/events/{id}/register - Register for event
• GET /api/v1/events/{id}/participants - Participant list (ORGANIZER)

• GET /api/v1/users/me - Current user profile
• PUT /api/v1/users/me - Update profile
• GET /api/v1/users/@{username} - Public profile

• POST /api/v1/certificates/generate/{eventId} - Generate certificates (async)
• GET /api/v1/certificates/verify/{certNumber} - Verify certificate
• GET /api/v1/certificates/{id}/download - Download PDF

• GET /api/v1/qr/my-qr - Get QR code
• POST /api/v1/qr/checkin - Check-in at event (API Key)

• GET /api/v1/coins/balance - Coin balance
• GET /api/v1/coins/transactions - Transaction history
• GET /api/v1/coins/leaderboard - Leaderboard

• POST /api/v1/organizations - Create organization (ORGANIZER)
• GET /api/v1/organizations/{id} - Organization detail
• GET /api/v1/organizations/{id}/events - Organization events

See API Documentation for complete endpoint reference.

The project uses MySQL 8.0 with InnoDB storage engine. Key tables:

• users - User profiles with coin balance
• organizations - NGO/organizer organizations
• events - Events created by organizations
• event_registrations - User event participation tracking
• certificates - Generated certificates
• coin_transactions - Coin earning history
• qr_tokens - QR tokens for check-in
• leaderboard_entries - Leaderboard rankings
• notifications - User notifications
• referrals - Referral relationships

All tables use UUID primary keys (CHAR(36)) and include audit timestamps (created_at, updated_at).

Create .env file (copy from .env.example):

# Database
DB_URL=jdbc:mysql://localhost:3306/ween
DB_USERNAME=ween_user
DB_PASSWORD=ween_password

# Redis
REDIS_HOST=localhost

# S3/MinIO
S3_ENDPOINT=http://localhost:9000
S3_ACCESS_KEY=minioadmin
S3_SECRET_KEY=minioadmin

# JWT
JWT_SECRET=your-32-character-min-secret-key

# AES
AES_SECRET_KEY=16-character-key

# API Key
ORGANIZER_API_KEY=your-api-key

# Email
MAIL_HOST=localhost
MAIL_FROM=noreply@ween.az

# CORS
CORS_ORIGINS=http://localhost:3000

• application.yml - Production defaults
• application-dev.yml - Development (verbose logs, local services)
• application-prod.yml - Production (optimized, external services)
• application-test.yml - Testing (test database)

• CoinServiceTest - Coin crediting and balance logic
• QrServiceTest - QR generation and check-in
• CertificateServiceTest - PDF generation
• EventServiceTest - Event filtering and capacity
• AuthServiceTest - Registration and JWT generation

• AuthControllerIT - Full registration-to-login flow
• EventControllerIT - Event creation and registration
• CheckinControllerIT - QR generation and check-in flow

# All tests
mvn test

# Unit tests only
mvn test -Dtest=*ServiceTest

# Integration tests only
mvn test -Dtest=*IT

# Specific test
mvn test -Dtest=CoinServiceTest

# With coverage report
mvn clean test jacoco:report
# View report: target/site/jacoco/index.html

• Target: 70% minimum (enforced by JaCoCo)
• Current: 72% (services and controllers)
• Excluded: Entities, DTOs, enums, configs

• Cron: Daily at midnight (0 0 0 * * *)
• Tasks:
  • Recalculate monthly, quarterly, annual leaderboards
  • Award +200 coins to top 10 monthly performers
  • Updates based on coin transactions

• Cron: Jan 1 at midnight (0 0 0 1 1 *)
• Tasks:
  • Identify users with 5+ event attendances in the year
  • Award +500 coins for annual achievement
  • Limited to once per user per year

The application sends emails for:

1. Email Verification - After registration
2. Password Reset - Forgot password flow
3. Event Reminder - Upcoming event notification
4. Certificate Ready - After certificate generation
5. Event Confirmation - After registration

All templates are customizable in EmailService.

Push notifications for:

• Event reminders
• Certificate ready notifications
• Attendance confirmations
• Referral bonuses
• Leaderboard updates

Configuration: FirebaseConfig.java

# Database backup
docker exec ween-mysql mysqldump -uween_user -p ween > backup.sql

# Restore from backup
docker exec -i ween-mysql mysql -uween_user -p ween < backup.sql

# View logs
docker logs -f ween-backend --tail=100

# Restart services
docker-compose restart app

OpenAPI/Swagger documentation available at:

• Swagger UI: http://localhost:5000/swagger-ui.html
• OpenAPI JSON: http://localhost:5000/v3/api-docs

# Check MySQL is running
docker-compose ps mysql

# Verify credentials in .env
# Restart MySQL
docker-compose restart mysql

# Check Redis is running
docker-compose ps redis

# Check Redis connectivity
docker exec ween-redis redis-cli ping

# Change port in docker-compose.yml:
ports:
  - "8081:5000"  # Changed from 5000:5000

• API Reference
• Database Schema
• Security Guide
• Deployment Guide
• Contributing Guidelines

This project is proprietary software for the Ween platform.

Developed by the Ween backend team. For support, contact: support@ween.az

• Mobile app integration
• Advanced analytics dashboard
• Machine learning recommendations
• Video call integration for online events
• Gamification badges and achievements
• Social media integration
• Multi-language support
• Micro-service architecture migration

• ✅ 50+ production-ready classes
• ✅ 14 service classes with full business logic
• ✅ 9 REST controllers with 60+ endpoints
• ✅ 10 repositories with custom queries
• ✅ JWT-based security with role authorization
• ✅ Redis token blacklist and caching
• ✅ S3/MinIO file storage integration
• ✅ Firebase push notifications
• ✅ iText PDF certificate generation
• ✅ QR code generation and encryption
• ✅ Complete coin/gamification system
• ✅ Leaderboard with multiple periods and scopes
• ✅ Event filtering, search, and pagination
• ✅ Referral program implementation
• ✅ Email notifications
• ✅ Background job schedulers
• ✅ Flyway database migrations
• ✅ 5 unit test classes (~70 tests)
• ✅ 3 integration test classes (~40 tests)
• ✅ Docker & Docker Compose setup
• ✅ Comprehensive YAML configurations
• ✅ Swagger/OpenAPI documentation
• ✅ Global exception handling
• ✅ Request/response DTOs with validation
• ✅ MapStruct entity mapping

Status: ✅ COMPLETE - Production-ready Spring Boot backend ready for deployment!