{"id":24773946,"url":"https://github.com/bjfikky/carhov","last_synced_at":"2026-04-10T23:04:10.592Z","repository":{"id":270537846,"uuid":"910688211","full_name":"bjfikky/carhov","owner":"bjfikky","description":"Carhov is a modern carpooling application designed to bridge the gap between drivers and passengers, making commuting more efficient, cost-effective, and environmentally friendly. The platform allows users to create and join rides effortlessly by leveraging real-time geolocation, secure payment integration, and smart matching algorithms.","archived":false,"fork":false,"pushed_at":"2025-03-23T20:39:30.000Z","size":93,"stargazers_count":0,"open_issues_count":3,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-23T21:29:41.717Z","etag":null,"topics":["hibernate-jpa","java","postgresql","spring","spring-boot","spring-data-jpa","spring-security"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bjfikky.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-01-01T04:30:07.000Z","updated_at":"2025-03-23T20:39:35.000Z","dependencies_parsed_at":null,"dependency_job_id":"800ed7b0-178c-4ebd-830b-1c4e57150ad0","html_url":"https://github.com/bjfikky/carhov","commit_stats":null,"previous_names":["bjfikky/carhov"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bjfikky%2Fcarhov","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bjfikky%2Fcarhov/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bjfikky%2Fcarhov/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bjfikky%2Fcarhov/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bjfikky","download_url":"https://codeload.github.com/bjfikky/carhov/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245175358,"owners_count":20572781,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hibernate-jpa","java","postgresql","spring","spring-boot","spring-data-jpa","spring-security"],"created_at":"2025-01-29T05:20:12.633Z","updated_at":"2026-04-10T23:04:10.585Z","avatar_url":"https://github.com/bjfikky.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CarHov - Modern Carpooling Platform\n\n[![Java](https://img.shields.io/badge/Java-21-orange)](https://www.oracle.com/java/technologies/javase/jdk21-archive-downloads.html)\n[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.4.1-brightgreen)](https://spring.io/projects/spring-boot)\n\n## Table of Contents\n- [Overview](#overview)\n- [Features](#features)\n- [Architecture](#architecture)\n- [Technology Stack](#technology-stack)\n- [API Documentation](#api-documentation)\n- [Setup and Installation](#setup-and-installation)\n- [Development Guidelines](#development-guidelines)\n- [Testing](#testing)\n- [Security](#security)\n- [Contributing](#contributing)\n- [License](#license)\n- [Reference Documentation](#reference-documentation)\n\n## Overview\n**Still a work in progress, but core functionalities added ...**\n\nCarHov is a modern carpooling application designed to bridge the gap between drivers and passengers, making commuting more efficient, cost-effective, and environmentally friendly. The platform allows users to create and join rides effortlessly by leveraging real-time geolocation, secure payment integration, and smart matching algorithms.\n\nWhether you're a driver with empty seats or a passenger looking for a convenient ride, CarHov streamlines the process with an intuitive interface and powerful backend services built on Spring Boot. Users can easily search for rides based on their origin, destination, and timing preferences, making daily commuting or intercity travel a seamless experience.\n\nThis repository contains the backend API and services. The front-end repository can be found here [link to be updated].\n\n## Features\n\n### Core Functionality\n- **User Management**\n  - Registration, authentication, and profile management\n  - Role-based access control (User, Admin, Super Admin)\n  - JWT-based authentication with refresh tokens\n\n- **Ride Management**\n  - Create, update, and delete ride schedules\n  - Recurring ride scheduling (daily, weekly patterns)\n  - Seat availability management\n\n- **Search \u0026 Matching**\n  - Geolocation-based ride search with customizable radius\n  - Advanced filtering by departure time and available seats\n  - Matching algorithm based on proximity and schedules\n\n- **Geographic Services**\n  - Distance calculation using the Haversine formula\n  - Proximity checks for ride search\n  - Location validation\n\n- **Ride Booking**\n  - [ _still under development_ ]\n\n### Security Features\n- Secure password management with encryption\n- HTTPS support for all communications\n- Role-based endpoint protection\n- User ownership validation for profile modifications\n- Aspect-oriented security implementation\n\n## Architecture\n\nCarHov follows a layered architecture pattern:\n\n```\n┌───────────────────┐\n│   Security Layer  │ ← Authentication, authorization, and security filters\n├───────────────────┤\n│   API Layer       │ ← RESTful controllers and DTOs\n├───────────────────┤\n│   Business Layer  │ ← Business logic and service implementations\n├───────────────────┤\n│   Data Layer      │ ← JPA repositories and entities\n└───────────────────┘\n```\n\n### Key Components\n- **Security Layer**: Authentication, authorization, JWT handling, and security aspects\n- **API Layer**: RESTful controllers, DTOs, and request/response mapping\n- **Service Layer**: Core business logic, validation, and service implementation\n- **Data Layer**: Entities, repositories, and database interactions\n\n## Technology Stack\n\n- **Backend**\n  - Java 21\n  - Spring Boot 3.4.1\n  - Spring Security with JWT\n  - Spring Data JPA\n  - Hibernate\n  - PostgreSQL / MySQL\n\n- **Build Tools**\n  - Maven\n\n- **Testing**\n  - JUnit 5\n  - Mockito\n  - Testcontainers for Integration Tests\n\n- **DevOps \u0026 Infrastructure**\n  - Docker\n  - Swagger/OpenAPI for API documentation\n\n## API Documentation\n\nWhile the application is running, the Swagger UI is available at:\n```\nhttp://localhost:8080/swagger-ui/index.html\n```\n\n### Key Endpoints\n\n#### Authentication\n- `POST /api/auth/signup` - Register a new user\n- `POST /api/auth/signin` - Authenticate and receive JWT token\n- `POST /api/auth/refreshtoken` - Refresh an existing token\n\n#### User Management\n- `GET /api/users/{userId}` - Get user profile\n- `PUT /api/users/{userId}` - Update user profile (owner only)\n- `DELETE /api/users/{userId}` - Delete user profile (owner only)\n\n#### Admin Operations\n- `GET /api/admin/users` - Get all admin users\n- `POST /api/admin/users/create` - Create admin user\n- `GET /api/admin/users/{id}` - Get admin user by ID\n- `PUT /api/admin/users/{id}` - Update admin user\n- `DELETE /api/admin/users/{id}` - Delete admin user\n\n#### Ride Scheduling\n- `POST /api/rides` - Create a new ride schedule\n- `GET /api/rides/search` - Search for rides based on location and criteria\n- `GET /api/rides/{id}` - Get a specific ride schedule\n- `PUT /api/rides/{id}` - Update a ride schedule\n- `DELETE /api/rides/{id}` - Delete a ride schedule\n\n#### Vehicle Management\n- `POST /api/vehicles` - Create a new vehicle\n- `PUT /api/vehicles/{vehicleid}` - Update a vehicle. Just the color\n- `DELETE /api/vehicles/{id}` - Delete a vehicle\n\n#### Version\n- `GET /api/version` - Get current application version\n\n## Setup and Installation\n\n### Prerequisites\n- Java Development Kit (JDK) 21\n- Maven or Gradle (build tools)\n- MySQL/PostgreSQL database server\n- IDE (IntelliJ IDEA recommended)\n\n### Step 1: Clone the Repository\n```bash\ngit clone \u003crepository-url\u003e\ncd carhov\n```\n\n### Step 2: Database Configuration\nConfigure your database connection in `src/main/resources/application.properties`:\n\n```properties\n# Database settings\nspring.datasource.url=jdbc:mysql://localhost:3306/carhov_db\nspring.datasource.username=your_username\nspring.datasource.password=your_password\nspring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver\n\n# Hibernate settings\nspring.jpa.hibernate.ddl-auto=update\nspring.jpa.show-sql=true\nspring.jpa.properties.hibernate.dialect=org.hibernate.dialect.MySQL8Dialect\n```\n\n### Step 3: JWT Configuration\nSet up your JWT configuration in the same properties file:\n\n```properties\n# JWT settings\ncarhov.app.jwtSecret=your_jwt_secret_key\ncarhov.app.jwtExpirationMs=86400000\ncarhov.app.jwtRefreshExpirationMs=604800000\n```\n\n### Step 4: Build and Run\nUsing Maven:\n```bash\nmvn clean install\nmvn spring-boot:run\n```\n\nUsing your IDE:\n- Open the project in your IDE\n- Run the `CarhovApplication.java` main class\n\n### Step 5: Verify Installation\nOnce the application is running, access:\n```\nhttp://localhost:8080/api/version\n```\n\nExpected response:\n```json\n{\n    \"application\": \"carhov\",\n    \"version\": \"0.0.1-SNAPSHOT\"\n}\n```\n\n### Step 6: Run Tests\nUsing Maven, while docker desktop is also running on your computer:\n```bash\nmvn clean test\n```\n\n## Development Guidelines\n\n### Coding Standards\n- Follow Java naming conventions\n- Use descriptive names for classes, methods, and variables\n- Apply proper exception handling\n\n### Git Workflow\n- Create feature branches from `main`\n- Use meaningful commit messages\n- Submit PRs for code review before merging\n\n### DTO Pattern\n- Use DTOs for all API requests and responses\n- Use mappers to convert between DTOs and entities\n- Validate DTOs at the controller level\n\n## Testing\n\n### Unit Testing\nUnit tests should be written for:\n- Service classes\n- Repository custom methods\n- Utility classes\n- Security components\n\nExample running tests:\n```bash\nmvn test\n```\n\n### Integration Testing\nIntegration tests use Testcontainers to spin up databases:\n```bash\nmvn verify\n```\n\n## Security\n\nCarHov implements several security measures:\n\n1. **Authentication**: JWT-based with refresh tokens\n2. **Authorization**: Role-based access control\n3. **Resource Protection**: Aspect-based user ownership validation\n4. **Password Security**: BCrypt password encoding\n5. **Input Validation**: Request validation via annotations\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n6. Wait for my review \n\n\n## Reference Documentation\n\nFor further reference, please consider the following sections:\n\n* [Official Apache Maven documentation](https://maven.apache.org/guides/index.html)\n* [Spring Boot Maven Plugin Reference Guide](https://docs.spring.io/spring-boot/3.4.1/maven-plugin)\n* [Spring Boot Testcontainers support](https://docs.spring.io/spring-boot/3.4.1/reference/testing/testcontainers.html#testing.testcontainers)\n* [Spring Data JPA](https://docs.spring.io/spring-boot/3.4.1/reference/data/sql.html#data.sql.jpa-and-spring-data)\n* [Spring Security](https://docs.spring.io/spring-boot/3.4.1/reference/web/spring-security.html)\n* [Spring Web](https://docs.spring.io/spring-boot/3.4.1/reference/web/servlet.html)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbjfikky%2Fcarhov","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbjfikky%2Fcarhov","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbjfikky%2Fcarhov/lists"}