Club-Cycle

Club Operations Automation System – Backend

Club-Cycle is a backend system built with Spring Boot to automate and manage club operations such as users, roles, events, memberships, and administration. The project follows production-grade architecture, security practices, and CI/CD workflows.

---

Project Structure

Standard layered architecture (production-friendly)

│
├── ClubCycleApplication.java
│
├── config/                 # Security, Swagger, CORS, Beans
│   ├── ApplicationStartupListener.java
│   ├── CustomCorsConfiguration.java
│   ├── SecurityConfig.java
│   └── SwaggerConfig.java
│
├── controller/             # REST controllers (API layer)
│   ├── AuthController.java
│   ├── HomeController.java
│   ├── RoleController.java
│   └── UserController.java
│
├── service/                # Business logic
│   ├── UserService.java
│   ├── RoleService.java
│   └── impl/
│       └── UserServiceImpl.java
│       └── RoleServiceImpl.java
│
├── Entity/                # Business logic
│   ├── RoleEntity.java
│   ├── RoleEnum.java
│   ├── UserEntity.java
│   └── UserSessionEntity.java
│
├── repository/             # Data access layer
│   ├── RoleRepository.java
│   ├── UserRepository.java
│   └── UserSessionRepository.java
│
├── model/                  # JPA / Mongo entities
│   └── User.java
│
├── dto/                    # Request / Response DTOs
│   ├── LoginRequest.java
│   ├── LoginResponse.java
│   ├── RefreshTokenRequest.java
│   ├── RoleDto.java
│   ├── TokenResponse.java
│   ├── UserDto.java
│   └── UserResponseDto.java
│
├── mapper/                 # Entity ↔ DTO mappers
│   └── UserMapper.java
│
├── exception/
│   ├── AppException.java               # Abstract base
│   ├── ResourceNotFoundException.java  # 404
│   ├── BadRequestException.java        # 400
│   ├── ConflictException.java          # 409
│   ├── GlobalExceptionHandler.java     # @RestControllerAdvice
│   ├── ErrorResponse.java              # Response DTO
│   └── ErrorCode.java                  # Enum (optional)
│
└── util/                   # Utility / helper classes
    └── JwtUtil.java

---

Development Roadmap

---

Step 0: Planning & Brainstorming

• Define project goals
• Identify core modules
• Decide tech stack
• High-level architecture design

---

Step 1: GitHub Repository Setup

• Version control
• Team collaboration
• Code reviews
• CI/CD integration

📄 Documentation Step 01 – GitHub Setup

---

Step 2: Spring Boot Base Project Setup

• Choose Java version & build tool
• Configure base dependencies
• Define initial project structure

Project Generator https://spring.io/

Dependency Reference https://mvnrepository.com/

Documentation Step 02 – Spring Boot Setup

---

Step 3: Contract-Driven API Development (CDD)

Define API contracts before implementation.

Includes:

• API endpoints
• Request & response schemas
• HTTP status codes
• Validation rules

Benefits:

• Parallel frontend & backend development
• Reduced miscommunication
• Easier testing & maintenance

Documentation Step 03 – Contract-Driven API

---

Step 4: Database Design & ER Diagram

Identify entities:

• User
• Role
• Event
• Membership
• Club

Define relationships and normalize schema.

Documentation Step 04 – ER_DIAGRAM

---

Step 5: Docker & Docker Compose

• Containerize the application
• Run backend & database together
• Ensure environment consistency

Includes:

• Dockerfile
• docker-compose.yml

Documentation docs/step05-docker-setup.md

---

Step 6: Test-Driven Development (TDD)

• Write tests before implementation
• Improve reliability and confidence

Testing includes:

• Unit tests (Service layer)
• Repository tests
• Integration tests (Controller layer)

Documentation docs/step06-tdd.md

---

Step 7: Security Implementation

Includes:

• JWT authentication
• Cookie-based session support
• Password hashing using BCrypt
• CORS configuration
• Request rate limiting

Documentation docs/step07-security.md

---

Step 8: Environment Configuration

• Externalize configuration using .env

• Use application.yml & profile-based configs

• Separate environments:

  • dev
  • test
  • prod

Documentation docs/step08-env-config.md

---

Step 9: VPS Deployment

• Setup VPS (Excloud)
• Install Docker & Docker Compose
• Configure firewall & Nginx (optional)
• Deploy application securely

Documentation docs/step09-vps-deployment.md

---

Step 10: GitHub Actions (CI/CD)

Automated pipeline for:

• Build
• Test
• Docker image creation
• Deployment to VPS

Documentation docs/step10-github-actions.md

---

Step 11: Pre-Deployment Test Validation

• All tests must pass before deployment
• Enforced via CI pipeline
• Prevents broken builds in production

Documentation docs/step11-ci-test-check.md

---

Tech Stack

• Java 25
• Spring Boot
• Spring Data JPA
• Hibernate
• DTO Pattern
• Swagger / OpenAPI
• JUnit & Mockito
• MongoDB / MySQL (configurable)
• Docker & Docker Compose
• Maven
• Git & GitHub
• GitHub Actions

---

Future Enhancements

• Role-Based Access Control (Admin / Member)
• Advanced Event & Membership management
• Email & notification service
• Audit logging & activity tracking
• Analytics dashboard
• Microservices migration (optional)

---

Contributing to Club-Cycle

We welcome:

• Bug fixes
• Feature enhancements
• Documentation improvements
• Refactoring & performance improvements

Contribution Guidelines CONTRIBUTING.md

---

Running

---

Development environment - for doing testing

make build-development
make start-development

Open http://localhost:3001

Staging environment - for doing UAT testing

make build-staging
make start-staging

Open http://localhost:3002

Production environment - for users

make build-production
make start-production

Open http://localhost:3003

Developer environment - for Hot reloading

make start-developer

Open http://localhost:3003

Running Locally

---

First, run the development server:

mvn spring-boot:run

Open http://localhost:3000 with your browser to see the result.