🌳 Family Tree - Genealogy Application

A modern Spring Boot application to manage a family tree using Neo4j, leveraging Java Records for DTOs and following best development practices.

📋 Table of Contents

Features
Prerequisites
Installation
Configuration
Running the Application
API Endpoints
Testing
Docker
Architecture
Best Practices
Useful Cypher Queries
Contributing
License
Authors
Acknowledgements

✨ Features

✅ Java 17 with Records for DTOs
✅ Spring Boot 3.2 with layered architecture
✅ Neo4j as a graph database
✅ OpenAPI/Swagger for documentation
✅ Bean Validation with Jakarta Validation
✅ Centralized exception handling
✅ Unit and integration tests
✅ Docker multi-stage build
✅ Docker Compose for orchestration
✅ Structured logging with SLF4J
✅ Typed enums for Gender and Relationships
✅ Mappers for Entity ↔ DTO conversion
✅ Service interface + implementation

📦 Prerequisites

Java 17 or higher
Maven 3.9+
Docker & Docker Compose (recommended)
Neo4j 5.15 (for local installation)

🚀 Installation

Clone the repository

git clone https://github.com/Juste120/family-tree.git
cd family-tree

Copy the environment file
```
cp .env.example .env
```

Modify variables if necessary

# Edit .env with your settings
nano .env

⚙️ Configuration

Spring Profiles

dev: Development with detailed logs
prod: Production with limited logs
test: Testing with a dedicated Neo4j database

Environment Variables

SPRING_PROFILE=dev
NEO4J_URI=bolt://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=password
SERVER_PORT=8080

🏃 Running the Application

Option 1: With Docker Compose (Recommended)

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

The application will be accessible at:

API: http://localhost:8080
Swagger UI: http://localhost:8080/swagger-ui.html
Neo4j Browser: http://localhost:7474

Option 2: Local Development

# Start Neo4j with Docker
docker run -d \
  --name neo4j \
  -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/password \
  neo4j:5.15.0

# Run the application
mvn spring-boot:run -Dspring-boot.run.profiles=dev

Option 3: Build and Run the JAR

# Compile
mvn clean package -DskipTests

# Run
java -jar target/family-tree.jar

📡 API Endpoints

Persons (CRUD)

# List all persons
GET /api/v1/persons

# Get a person by ID
GET /api/v1/persons/{id}

# Create a person
POST /api/v1/persons

# Update a person
PUT /api/v1/persons/{id}

# Delete a person
DELETE /api/v1/persons/{id}

Relationships

# Add a parent-child relationship
POST /api/v1/persons/{parentId}/children/{childId}

# Add a marriage relationship
POST /api/v1/persons/{person1Id}/spouse/{person2Id}

# Remove relationships
DELETE /api/v1/persons/{parentId}/children/{childId}
DELETE /api/v1/persons/{person1Id}/spouse/{person2Id}

Tree Navigation

# Descendants
GET /api/v1/persons/{id}/descendants

# Ancestors
GET /api/v1/persons/{id}/ancestors

# Siblings
GET /api/v1/persons/{id}/siblings

# Grandchildren
GET /api/v1/persons/{id}/grandchildren

# Grandparents
GET /api/v1/persons/{id}/grandparents

# Count descendants
GET /api/v1/persons/{id}/descendants/count

# Path between two persons
GET /api/v1/persons/path?from={id1}&to={id2}

Search and Statistics

# Search by name
GET /api/v1/persons/search?lastName=Smith

# Statistics
GET /api/v1/persons/stats/count
GET /api/v1/persons/stats/alive

🎯 Usage Examples

Create a person

curl -X POST http://localhost:8080/api/v1/persons \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Alice",
    "lastName": "Martin",
    "birthDate": "1990-05-15",
    "gender": "F"
  }'

Add a relationship

# Parent (ID 1) → Child (ID 2)
curl -X POST http://localhost:8080/api/v1/persons/1/children/2

🧪 Testing

Run all tests

mvn test

Run a specific test

mvn test -Dtest=PersonServiceImplTest

Coverage with JaCoCo

mvn clean verify
# Report in target/site/jacoco/index.html

🐳 Docker

Build the image

# Production
docker build -t family-tree:latest .

# Development
docker build -f Dockerfile.dev -t family-tree:dev .

Run the container

docker run -d \
  -p 8080:8080 \
  -e SPRING_PROFILE=prod \
  -e NEO4J_URI=bolt://neo4j:7687 \
  --name family-tree-app \
  family-tree:latest

Docker Compose

# Start
docker-compose up -d

# Logs
docker-compose logs -f family-tree-app

# Rebuild
docker-compose up -d --build

# Stop and delete
docker-compose down -v

🏗️ Architecture

src/main/java/com/example/familytree/
├── FamilyTreeApplication.java
├── config/                    # Spring Configuration
│   ├── Neo4jConfig.java
│   ├── OpenApiConfig.java
│   └── DataInitializer.java
├── model/                     # Neo4j Entities
│   └── Person.java
├── dto/                       # DTOs (Java Records)
│   ├── PersonDTO.java
│   ├── PersonSummaryDTO.java
│   ├── PersonCreateDTO.java
│   ├── PersonUpdateDTO.java
│   └── ...
├── enums/                     # Enumerations
│   ├── Gender.java
│   └── RelationType.java
├── mapper/                    # Entity ↔ DTO Conversion
│   └── PersonMapper.java
├── repository/                # Neo4j Data Access
│   └── PersonRepository.java
├── service/                   # Business Logic
│   ├── PersonService.java
│   └── impl/
│       └── PersonServiceImpl.java
├── controller/                # REST API
│   └── PersonController.java
└── exception/                 # Error Handling
    ├── GlobalExceptionHandler.java
    ├── PersonNotFoundException.java
    └── ...

📚 Best Practices Applied

Layered Architecture
- Clear separation of concerns
- Controller → Service → Repository
- DTOs to decouple the API from the model
Java Records for DTOs
- Immutable by default
- Concise code (-47% lines)
- Thread-safe
Validation
- Bean Validation on DTOs
- Business validation in the service layer
- Clear error messages
Custom Exceptions
- GlobalExceptionHandler for centralization
- Standardized JSON responses
- Structured logs
Testing
- Unit tests (Mockito)
- Integration tests (MockMvc)
- Coverage > 80%
Docker
- Optimized multi-stage build
- Lightweight Alpine image
- Non-root user for security
- Health checks
Documentation
- Integrated OpenAPI/Swagger
- JavaDoc on public methods
- Comprehensive README
Security
- Input validation
- Non-root user in Docker
- No sensitive data in logs

📊 Useful Cypher Queries

// Visualize the whole family
MATCH path = (p:Person)-[*]-(p2:Person)
RETURN path
LIMIT 100

// Find the person with the most descendants
MATCH (p:Person)-[:PARENT_OF*]->(d:Person)
WITH p, count(d) as descendants
RETURN p.firstName, p.lastName, descendants
ORDER BY descendants DESC
LIMIT 1

// Calculate the tree depth
MATCH path = (root:Person)-[:PARENT_OF*]->(leaf:Person)
WHERE NOT (leaf)-[:PARENT_OF]->()
RETURN max(length(path)) as maxDepth

🤝 Contributing

Fork the project
Create a feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

👥 Authors

Juste Pakou - Initial work - Juste120 - [email protected]

🙏 Acknowledgements

Spring Boot Team
Neo4j Community
OpenAPI Initiative

Made with ❤️ and ☕ by the Family Tree Team

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
gradle/wrapper		gradle/wrapper
public		public
src		src
.gitattributes		.gitattributes
.gitignore		.gitignore
Dockerfile		Dockerfile
Dockerfile.dev		Dockerfile.dev
README.md		README.md
build.gradle		build.gradle
build.sh		build.sh
docker-compose.yml		docker-compose.yml
gradlew		gradlew
gradlew.bat		gradlew.bat
settings.gradle		settings.gradle

Juste120/family-tree

Folders and files

Latest commit

History

Repository files navigation