Skip to content

Commit 0073421

Browse files
PaolaAPL17PaolaAPL17
authored
Merge pull request #166 from Femcoders-SleepUp/docs/improve-project-readme
docs: improve README formatting
2 parents 10211f5 + 631a27f commit 0073421

1 file changed

Lines changed: 214 additions & 52 deletions

File tree

‎README.md‎

Lines changed: 214 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,10 @@ The API includes stateless session handling, Swagger-based documentation, and cl
2828
- [Reservations](#reservations)
2929
- [🧪 Running Tests](#running-tests-)
3030
- [🚀 CI/CD Pipeline](#cicd-pipeline)
31+
- [Detailed Workflows](#detail-workflows)
3132
- [📦 Diagrams](#diagrams-)
33+
- [🐳 Docker](#docker)
34+
- [☸️ Kubernetes](#kubernetes)
3235
- [👥 Contributors](#contributors-)
3336

3437
---
@@ -88,19 +91,21 @@ The API includes stateless session handling, Swagger-based documentation, and cl
8891

8992
## 👩‍💻 Technology Stack
9093

91-
| Component | Technology | Version | Purpose |
92-
|------------------|--------------------|-----------|-------------------------------------|
93-
| Framework | Spring Boot | 3.5.5 | Main application framework |
94-
| Runtime | Java | 21 | Runtime environment |
95-
| Database | MySQL | Latest | Persistent data storage |
96-
| Caching | Redis | Latest | Token blacklist |
97-
| Security | Spring Security | 6.x | Authentication & authorization |
98-
| JWT | JJWT | 0.12.6 | Token generation & validation |
99-
| Email | Spring Mail | 3.5.5 | Email notifications |
100-
| Images | Cloudinary | 2.0.0 | Image storage & management |
101-
| Documentation | SpringDoc OpenAPI | 2.8.9 | API documentation |
102-
| Mapping | MapStruct | 1.5.5 | Entity-DTO transformations |
103-
| Testing | Spring Boot Test | 3.5.5 | Unit & integration testing |
94+
| Component | Technology | Version | Purpose |
95+
|------------------|-------------------|---------|--------------------------------|
96+
| Framework | Spring Boot | 3.5.5 | Main application framework |
97+
| Runtime | Java | 21 | Runtime environment |
98+
| Database | MySQL | Latest | Persistent data storage |
99+
| Caching | Redis | Latest | Token blacklist |
100+
| Security | Spring Security | 6.x | Authentication & authorization |
101+
| JWT | JJWT | 0.12.6 | Token generation & validation |
102+
| Email | Spring Mail | 3.5.5 | Email notifications |
103+
| Images | Cloudinary | 2.0.0 | Image storage & management |
104+
| Documentation | SpringDoc OpenAPI | 2.8.9 | API documentation |
105+
| Mapping | MapStruct | 1.5.5 | Entity-DTO transformations |
106+
| Testing | Spring Boot Test | 3.5.5 | Unit & integration testing |
107+
| Containerization | Docker | Latest | Application containers |
108+
| Orchestration | Kubernetes | Latest | Container orchestration |
104109

105110
---
106111

@@ -114,11 +119,11 @@ cd SleepUp
114119
### Run 🏃‍♂️
115120

116121
```bash
117-
./mvnw spring-boot:run
122+
./mvnw spring-boot:run
118123
```
119124
or
120125
```bash
121-
mvn spring-boot:run
126+
mvn spring-boot:run
122127
```
123128

124129
> 💡 Alternatively, run the main application class (annotated with `@SpringBootApplication`) directly from your IDE, e.g., IntelliJ IDEA → right-click → **Run 'SuApplication.main()'**.
@@ -127,45 +132,47 @@ mvn spring-boot:run
127132

128133
## 📚 API Endpoints
129134

130-
### Authentication
131-
- `POST /auth/register` — Register a new user
132-
- `POST /auth/login` — Log in and receive JWT token
133-
- `POST /auth/logout` — Invalidate current token
134-
- `POST /auth/refresh` — Refresh expired token
135+
### 🔐 Authentication
136+
137+
| Method | Endpoint | Description |
138+
| ------ | ---------------- | ------------------------------- |
139+
| `POST` | `/auth/register` | 🆕 Register a new user |
140+
| `POST` | `/auth/login` | 🔑 Log in and receive JWT token |
141+
| `POST` | `/auth/logout` | 🚪 Invalidate current token |
142+
| `POST` | `/auth/refresh` | ♻️ Refresh expired token |
135143

136144
---
137145

138-
### Users
139-
- `GET /users/profile` — Get current user profile
140-
- `PUT /users/profile` — Update current user profile
141-
- `DELETE /users/profile` — Delete current user account
142-
- `POST /users/upload-avatar` — Upload avatar image
143-
- `GET /admin/users` — List all users (ADMIN)
144-
- `GET /admin/users/{id}` — Get user by ID (ADMIN)
145-
- `PUT /admin/users/{id}` — Update user by ID (ADMIN)
146-
- `DELETE /admin/users/{id}` — Delete user by ID (ADMIN)
146+
### 👤 Users
147+
| Method | Endpoint | Description |
148+
| -------- | ---------------------- | ------------------------------ |
149+
| `GET` | `/users/profile` | 👀 Get current user profile |
150+
| `PUT` | `/users/profile` | ✏️ Update current user profile |
151+
| `DELETE` | `/users/profile` | ❌ Delete current user account |
152+
| `POST` | `/users/upload-avatar` | 🖼️ Upload avatar image |
147153

148154
---
149155

150-
### Accommodations
151-
- `GET /accommodations` — List all accommodations
152-
- `GET /accommodations/{id}` — Get details by ID
153-
- `GET /accommodations/filter` — Filter accommodations with pagination
154-
- `POST /accommodations` — Create a new accommodation (USER)
155-
- `PUT /accommodations/{id}` — Update accommodation (OWNER)
156-
- `DELETE /accommodations/{id}` — Delete accommodation (OWNER)
156+
### 🏡Accommodations
157+
| Method | Endpoint | Description |
158+
| -------- | ------------------------ | ---------------------------------------- |
159+
| `GET` | `/accommodations` | 🌍 List all accommodations |
160+
| `GET` | `/accommodations/{id}` | 🔍 Get accommodation details |
161+
| `GET` | `/accommodations/filter` | 🧭 Filter accommodations with pagination |
162+
| `POST` | `/accommodations` | ➕ Create a new accommodation *(User)* |
163+
| `PUT` | `/accommodations/{id}` | 🛠️ Update accommodation *(Owner)* |
164+
| `DELETE` | `/accommodations/{id}` | 🗑️ Delete accommodation *(Owner)* |
157165

158166
---
159167

160-
### Reservations
161-
- `GET /reservations` — List user’s reservations
162-
- `GET /reservations/{id}` — Get reservation details
163-
- `POST /reservations` — Create new reservation
164-
- `PUT /reservations/{id}` — Update reservation
165-
- `DELETE /reservations/{id}` — Cancel reservation
166-
- `GET /owners/reservations` — List reservations for owner’s accommodations
167-
- `PUT /owners/reservations/{id}/confirm` — Confirm reservation
168-
- `PUT /owners/reservations/{id}/cancel` — Cancel reservation
168+
### 📅Reservations
169+
| Method | Endpoint | Description |
170+
| -------- | -------------------- | --------------------------- |
171+
| `GET` | `/reservations` | 📄 List user’s reservations |
172+
| `GET` | `/reservations/{id}` | 🔎 Get reservation details |
173+
| `POST` | `/reservations` | ✍️ Create new reservation |
174+
| `PUT` | `/reservations/{id}` | 🛠️ Update reservation |
175+
| `DELETE` | `/reservations/{id}` | ❌ Cancel reservation |
169176

170177
---
171178

@@ -175,25 +182,180 @@ mvn spring-boot:run
175182
- External services (Cloudinary, email) mocked for reliability
176183

177184
```bash
178-
./mvnw test
185+
./mvnw test
179186
```
180187

181188
---
182189

183-
## 🚀 CI/CD Pipeline
184-
- **GitHub Actions** with automated workflows:
185-
- `test.yml` — PR-triggered testing using Docker
186-
- `ci.yml` — Continuous integration for main/dev branches
187-
- `build.yml` — Build and publish Docker image
188-
- `release.yml` — Tag-based release pipeline with full test suite
190+
## ## 🚀 CI/CD Pipeline
191+
192+
Our project includes a complete **CI/CD pipeline powered by GitHub Actions**, ensuring code quality, automated testing, and reliable deployments across all development stages.
193+
194+
---
195+
196+
### 🧩 **Workflow Overview**
197+
198+
| Workflow | File | Purpose | Trigger | Main Actions |
199+
| ----------------------------- | ------------- | ------------------------------------- | ----------------------- | -------------------------------------------------- |
200+
| ✅ **Automated Tests** | `test.yml` | Validate Pull Requests before merging | On Pull Request | Runs test suite using Docker + MySQL + Redis |
201+
| ⚙️ **Continuous Integration** | `ci.yml` | Ensure code stability and integration | Push to `main` or `dev` | Compiles, tests, and validates build artifacts |
202+
| 🐳 **Docker Build & Publish** | `build.yml` | Build and publish Docker images | Push / Manual | Creates and uploads optimized images to GHCR |
203+
| 🏷️ **Release Pipeline** | `release.yml` | Create production releases | Tag `v*.*.*` | Runs full tests, builds, changelog, and release |
204+
| ☸️ **Kubernetes Deployment** | `deploy.yml` | Deploy app to Kubernetes cluster | Manual / After release | Updates configuration and performs rolling updates |
205+
206+
---
207+
208+
### 🔍 **Detailed Workflow Descriptions**
209+
210+
#### 🧪 1️⃣ `test.yml` — Automated Testing on Pull Requests
211+
**Purpose:** Validate code changes before merging to main branch.
212+
**Process:**
213+
- Spins up **MySQL** and **Redis** containers for integration tests.
214+
- Runs `mvn test` using isolated Docker environments.
215+
- Generates **coverage reports** and feedback.
216+
- Ensures no defective code reaches the main branch.
217+
218+
---
219+
220+
#### ⚙️ 2️⃣ `ci.yml` — Continuous Integration
221+
**Purpose:** Maintain stability of main and dev branches.
222+
**Process:**
223+
- Sets up **JDK 21** and caches dependencies.
224+
- Executes `mvn clean compile` and `mvn test`.
225+
- Validates successful builds and ensures no regressions.
226+
- Keeps stable and production-ready codebases.
227+
228+
---
229+
230+
#### 🐳 3️⃣ `build.yml` — Docker Build & Publish
231+
**Purpose:** Generate and publish containerized application images.
232+
**Process:**
233+
- Uses **Docker Buildx** for multi-architecture image builds.
234+
- Logs in to **GitHub Container Registry (GHCR)**.
235+
- Extracts version metadata and tags automatically.
236+
- Publishes lightweight, optimized Docker images.
237+
238+
---
239+
240+
#### 🏷️ 4️⃣ `release.yml` — Release Automation
241+
**Purpose:** Create official releases with changelogs and version tags.
242+
**Process:**
243+
- Detects new semantic version tags (e.g., `v1.2.3`).
244+
- Builds production artifacts and Docker images.
245+
- Publishes a **GitHub Release** with autogenerated notes.
246+
- Uploads versioned images to GHCR.
247+
248+
---
249+
250+
#### ☸️ 5️⃣ `deploy.yml` — Kubernetes Deployment
251+
**Purpose:** Automate deployment to Kubernetes clusters.
252+
**Process:**
253+
- Configures access to Kubernetes cluster.
254+
- Applies **ConfigMaps** and **Secrets**.
255+
- Deploys MySQL, Redis, and the application.
256+
- Performs **rolling updates** with zero downtime.
257+
- Verifies pod health and ingress configuration.
189258

190259
---
191260

261+
### 🔄 **Complete CI/CD Flow**
262+
263+
```text
264+
┌─────────────────┐
265+
│ Pull Request │
266+
└────────┬────────┘
267+
│
268+
▼
269+
┌─────────────────┐
270+
│ test.yml │ ◄─── Validate changes using Docker
271+
└────────┬────────┘
272+
│ [Merge]
273+
▼
274+
┌─────────────────┐
275+
│ main/dev │
276+
└────────┬────────┘
277+
│
278+
▼
279+
┌─────────────────┐
280+
│ ci.yml │ ◄─── Continuous Integration
281+
└────────┬────────┘
282+
│
283+
▼
284+
┌─────────────────┐
285+
│ build.yml │ ◄─── Build and push Docker image
286+
└────────┬────────┘
287+
│
288+
▼
289+
┌─────────────────┐
290+
│ Tag Release │
291+
└────────┬────────┘
292+
│
293+
▼
294+
┌─────────────────┐
295+
│ release.yml │ ◄─── Generate release artifacts
296+
└────────┬────────┘
297+
│
298+
▼
299+
┌─────────────────┐
300+
│ deploy.yml │ ◄─── Deploy to Kubernetes cluster
301+
└─────────────────┘
302+
303+
```
304+
### 📊 Status Badges
305+
Keep visibility of your pipeline status:
306+
- ![CI](https://github.com/Femcoders-SleepUp/SleepUp/actions/workflows/ci.yml/badge.svg)
307+
- ![Tests](https://github.com/Femcoders-SleepUp/SleepUp/actions/workflows/test.yml/badge.svg)
308+
- ![Build](https://github.com/Femcoders-SleepUp/SleepUp/actions/workflows/build.yml/badge.svg)
309+
- ![Release](https://github.com/Femcoders-SleepUp/SleepUp/actions/workflows/release.yml/badge.svg)
310+
311+
---
192312
## 📦 ER Diagram
193313

194314
Entity-relationship overview of database schema
195315
![sleepup_erdiagram.png](src/main/resources/static/images/sleepup_erdiagram.png)
196316

317+
---
318+
## 🐋 **Docker**
319+
320+
The project includes **full Docker support** with an optimized setup:
321+
322+
323+
### 🏗️ Dockerfile
324+
- **Multi-stage image** optimized for production:
325+
- Compiles the application in a **builder image**
326+
- Generates an **executable JAR**
327+
- Creates a **minimal runtime image with JRE 21**
328+
- Exposes **port 8080**
329+
330+
### 📦 Docker Compose
331+
For local development, includes:
332+
- **SleepUp** application service
333+
- **MySQL** database
334+
- **Redis** cache
335+
- Internal network for inter-service communication
336+
337+
```bash
338+
docker-compose up -d
339+
```
340+
---
341+
## ☸️ Kubernetes
342+
343+
Manifests for production deployment:
344+
345+
#### 📄 Included Resources
346+
347+
- deployment.yaml → Defines the application deployment
348+
349+
- service.yaml → Service to expose the application
350+
351+
- configmap.yaml → Non-sensitive configuration
352+
353+
- kustomization.yaml → Resource management with Kustomize
354+
355+
### ⚡ Deployment
356+
```
357+
kubectl apply -k kubernetes/
358+
```
197359
---
198360

199361
## 👥 Contributors

0 commit comments

Comments
 (0)