From d0d0b4c2ad3262846acc90ccd8d3691f2dea23e2 Mon Sep 17 00:00:00 2001
From: julien gourmet <julien.gourmet@epita.fr>
Date: Tue, 21 Oct 2025 21:39:37 +0200
Subject: [PATCH] add Readme.md

---
 README.md | 146 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 146 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..d0eee70
--- /dev/null
+++ b/README.md
@@ -0,0 +1,146 @@
+# API Factory - Insurance Management System
+
+A RESTful API for managing insurance clients and contracts, built with Spring Boot and H2 database.
+
+## Quick Start
+
+### Prerequisites
+- Java 17 or higher
+- Maven 3.6 or higher
+
+### Running the Application
+
+1. **Clone the repository:**
+   ```bash
+   git clone <git@github.com:jubbakka/API-Factory.git>
+   cd api-factory
+   ```
+
+2. **Start the application:**
+   ```bash
+   ./mvnw spring-boot:run
+   ```
+
+3. **Access the API:**
+   - Base URL: `http://localhost:8080`
+   - H2 Console: `http://localhost:8080/h2-console`
+   - Database URL: `jdbc:h2:~/<YOUR-LOCAL-PATH>/api-factory/data/localdb`
+   - Username: `admin`
+   - Password: `Admin@123`
+
+## API Endpoints
+
+### Clients
+- `POST /api/clients/person` - Create a person client
+- `POST /api/clients/company` - Create a company client
+- `GET /api/clients` - Retrieve all active clients
+- `GET /api/clients/{id}` - Get client details by ID
+- `PUT /api/clients/person/{id}` - Update a person client
+- `PUT /api/clients/company/{id}` - Update a company client
+- `DELETE /api/clients/{id}` - Soft delete a client
+- `GET /api/clients/{id}/contracts` - List all contracts for a client
+- `GET /api/clients/{id}/contracts/sum` - Calculate total contract value
+
+### Contracts
+- `POST /api/contracts` - Create a new contract
+- `PUT /api/contracts/{id}/cost` - Update contract cost
+
+## Testing
+
+### Running Tests
+Execute all tests with:
+```bash
+./mvnw test
+```
+
+### Postman Collection
+Import `API_Factory_Postman_Collection.json` into Postman for easy API testing.
+
+### Test Coverage
+The application has comprehensive test coverage:
+
+- **108 unit tests** across 6 test classes
+- **Service/model tests** for business logic and validation
+- **Tests cover** validation, duplicate detection, soft deletes, and error handling (404/409/500)
+
+### Test Data
+Seed data includes:
+
+- **50 clients** (37 person, 13 company)
+- **175 contracts** with varied costs and date scenarios
+- **Mix of active and deleted clients** for testing soft deletes
+
+To enable seed data, set `app.seed-db=true` in `application.properties` (disabled by default).
+
+## Architecture and Design
+
+### Soft Delete Strategy
+To meet audit and compliance needs:
+
+- **Deleting a client** sets status to `DELETED` with a timestamp
+- **Active contracts are closed** (endDate = current date)
+- **API filters show only ACTIVE clients**
+- **Data persists in the database** for historical/legal purposes
+
+### Client Types
+Separate endpoints for person and company clients due to distinct validation:
+
+- **Person**: Requires birth date, no company identifier
+- **Company**: Requires identifier (format: XXX-XXX), no birth date
+- **Uses inheritance** with a shared base Client entity
+
+### Database Setup
+
+- **Production**: H2 file-based database for data persistence
+- **Testing**: In-memory H2 database
+- **Seed data only populates empty databases**
+
+### Error Handling
+A global exception handler ensures consistent error responses:
+
+- **400**: Validation errors
+- **404**: Resource not found
+- **409**: Conflicts (e.g., duplicate email/phone)
+- **500**: Internal server errors
+
+### Validation
+
+- **Uses Bean Validation** with `@Valid` annotations
+- **Business rules enforced** in the service layer
+- **Custom error messages** for better user experience
+
+## Configuration
+
+### Database
+
+- **Production**: H2 file database at `./data/localdb`
+- **Testing**: In-memory H2 database
+- **H2 Console**: Available at `/h2-console`
+
+### Application Profiles
+
+- **Default**: Production mode with file-based database
+- **Test**: In-memory database for faster testing
+
+## Data Model
+
+```
+Client (abstract base)
+├── Person (birthDate)
+└── Company (identifier)
+
+Contract
+├── client (foreign key)
+├── startDate/endDate
+├── costAmount
+└── updatedDate (internal)
+```
+
+## Security and Validation
+
+- **Email format validation**
+- **Swiss phone number pattern validation**
+- **Company identifier format (XXX-XXX)**
+- **Unique constraints on email and phone**
+- **Birth dates must be in the past**
+- **Contract costs must be positive**
\ No newline at end of file