Ween Backend

Ween is a Youth Volunteering and Social Impact Platform built for connecting young volunteers with organizations, community events, certificates, social activity, and measurable impact. This repository contains the Spring Boot backend API for authentication, event discovery, event registration, organization management, posts, chat, QR check-in, certificates, coins, badges, notifications, leaderboards, AI helpers, and administration.

The project is developed by Team Enthuzone.

The detailed project documentation is stored in the docs folder:

• Architecture
• Entity Relationship Diagram
• User Flow
• API Reference
• Setup Guide
• Security Model
• Testing Guide
• Grading Requirements Alignment

Ween solves the problem of fragmented volunteer discovery and impact tracking. Volunteers need a simple way to find relevant opportunities, register for events, prove participation, receive certificates, and build a visible social impact profile. Organizations need a controlled way to publish events, manage participants, communicate with users, verify attendance, and review platform activity.

The backend exposes a REST API under /api/v1, uses JWT authentication, applies role-based authorization, stores data through JPA/Hibernate, and uses Flyway migrations for database schema management.

• User registration, organization registration, login, refresh, logout, email verification, password reset, and password change.
• JWT-based stateless authentication with HTTP-only token cookies and Bearer token support.
• Role-based access control for VOLUNTEER, ORGANIZER, ORGANIZATION_ADMIN, and ADMIN.
• Event CRUD with categories, status transitions, filters, public reads, organizer writes, and participant statistics.
• Event registration and cancellation for volunteers.
• QR generation and check-in flow for participation verification.
• Organization profile management, organizer invitations, approval, rejection, and organizer removal.
• Social posts with media, likes, saves, reposts, and comments.
• User profile, public profile, followers, following, badges, certificates, events, and coin data.
• Direct and room-based chat with REST endpoints and WebSocket support.
• Certificates for completed participation.
• Ween Coins, transaction history, leaderboards, badges, and referrals.
• Notifications for user-facing platform activity.
• Admin moderation for users, organizations, events, posts, comments, certificates, coins, badges, referrals, audit logs, and AI statistics.
• AI endpoints for event content assistance and chat history.
• Global exception handling with consistent error responses.
• OpenAPI/Swagger documentation.
• Docker and Docker Compose support.

weenBackend/
  .github/
  src/
    main/
      java/com/ween/
        config/
        controller/
        dto/
        entity/
        enums/
        exception/
        mapper/
        repository/
        security/
        seeder/
        service/
        WeenApplication.java
      resources/
        db.migration/
        templates/
    test/
      java/com/ween/
        controller/
        security/
        service/
      resources/
        application-test.yml
  docker-compose.yml
  Dockerfile
  pom.xml
  README.md
  docs/

See API Reference for a more complete endpoint map.

This backend directly supports the major backend grading requirements:

• REST API with proper HTTP method usage across 18 controllers.
• DTO-based request and response handling.
• Full CRUD support for events and posts, plus administrative CRUD-style management for users, organizations, badges, events, posts, comments, and certificates.
• Input validation through annotations such as @NotBlank, @NotNull, @Size, @Email, and @Min.
• Global exception handling through GlobalExceptionHandler.
• MySQL database support with JPA/Hibernate and Flyway migrations.
• JWT registration, login, refresh, logout, protected endpoints, and role-based authorization.
• Four roles: VOLUNTEER, ORGANIZER, ORGANIZATION_ADMIN, and ADMIN.
• Swagger/OpenAPI API documentation.
• Unit and controller test coverage across service, controller, and security layers.

See Grading Requirements Alignment for a grader-friendly checklist.

• Java 17 or newer
• Maven 3.9 or newer, or the included Maven wrapper
• Docker and Docker Compose
• MySQL 8.0 if running without Docker

Copy .env.example to .env and fill in real values.

DB_USERNAME=your-db-username
DB_PASSWORD=your-db-password
JWT_SECRET=your-secret-key-min-32-characters-required
AES_SECRET_KEY=16-character-key
ORGANIZER_API_KEY=your-api-key-here
GEMINI_API_KEY=your-gemini-api-key-here
MAIL_USERNAME=your-email@example.com
MAIL_PASSWORD=your-smtp-app-password

docker compose up --build

Default service URLs:

• Backend API: http://localhost:5050
• Swagger UI: http://localhost:5050/swagger-ui.html
• OpenAPI JSON: http://localhost:5050/v3/api-docs
• MySQL: localhost:3306

./mvnw clean test
./mvnw spring-boot:run

On Windows PowerShell:

.\mvnw.cmd clean test
.\mvnw.cmd spring-boot:run

1. A volunteer registers with POST /api/v1/auth/register, or an organization registers with POST /api/v1/auth/register/organization.
2. The user logs in with POST /api/v1/auth/login or POST /api/v1/auth/login/organization.
3. The API returns authentication data and sets HTTP-only accessToken and refreshToken cookies.
4. Protected endpoints are called with an authenticated request.
5. The access token can be refreshed with POST /api/v1/auth/refresh.
6. Logout is handled through POST /api/v1/auth/logout.

The requested branch for README work is update/readme. Do not develop directly on main. For project tasks, use a task branch such as:

feature/user-authentication
feature/event-crud
feature/post-feed
fix/login-validation
update/readme

Recommended commit discipline:

• Keep commits focused.
• Use descriptive messages such as Document backend architecture or Add API reference documentation.
• Avoid large unrelated changes in the same commit.
• Do not mix documentation updates with backend behavior changes unless they belong to the same task.

Run the complete test suite:

./mvnw test

Run service tests only:

./mvnw test -Dtest=*ServiceTest

Run controller tests only:

./mvnw test -Dtest=*ControllerTest

The repository currently contains tests for services, controllers, and security helpers, including authentication, events, posts, organizations, participation, QR, certificates, coins, chat, notifications, admin behavior, and utility classes.

Flyway migrations are located in src/main/resources/db.migration.

Important tables include:

• users
• organizations
• events
• event_registrations
• participations
• qr_tokens
• certificates
• coin_transactions
• leaderboard_entries
• notifications
• referrals
• chat_rooms
• chat_messages

See Entity Relationship Diagram for the data model.

When the application is running, API documentation is available at:

http://localhost:5050/swagger-ui.html
http://localhost:5050/v3/api-docs

Team Name: Enthuzone

Team Members:

• Kenan Gafarov
• Mansura Badalova
• Umut Alizade
• Lala Aliyeva

This project is prepared for the Ween final project submission. Usage and distribution should follow the team and course rules.