{"id":28332044,"url":"https://github.com/brunoliratm/votify-api","last_synced_at":"2026-04-14T15:32:12.648Z","repository":{"id":288557448,"uuid":"967514705","full_name":"brunoliratm/Votify-API","owner":"brunoliratm","description":"This project is a Rest API developed in java with Spring Boot to manage and participate in voting sessions","archived":false,"fork":false,"pushed_at":"2025-06-01T01:24:55.000Z","size":277,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-02-08T20:57:54.711Z","etag":null,"topics":["docker","docker-compose","java","jwt","open-source","spring-boot","voting-application"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"Exploit-Experts/Votify-Api","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/brunoliratm.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"zenodo":null}},"created_at":"2025-04-16T15:13:16.000Z","updated_at":"2025-09-02T17:27:41.000Z","dependencies_parsed_at":null,"dependency_job_id":"1d1ca561-1f19-4cb5-bc79-855d2eea9c7a","html_url":"https://github.com/brunoliratm/Votify-API","commit_stats":null,"previous_names":["brunoliratm/votify-api"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/brunoliratm/Votify-API","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brunoliratm%2FVotify-API","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brunoliratm%2FVotify-API/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brunoliratm%2FVotify-API/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brunoliratm%2FVotify-API/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/brunoliratm","download_url":"https://codeload.github.com/brunoliratm/Votify-API/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brunoliratm%2FVotify-API/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31803244,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-14T11:13:53.975Z","status":"ssl_error","status_checked_at":"2026-04-14T11:13:53.299Z","response_time":153,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["docker","docker-compose","java","jwt","open-source","spring-boot","voting-application"],"created_at":"2025-05-26T19:26:26.380Z","updated_at":"2026-04-14T15:32:12.643Z","avatar_url":"https://github.com/brunoliratm.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\" text-align=\"center\"\u003e\n    \u003cimg src=\"https://capsule-render.vercel.app/api?type=waving\u0026height=200\u0026color=gradient\u0026text=Votify%20API\u0026reversal=false\"\u003e\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n![GitHub pull requests](https://img.shields.io/github/issues-pr/brunoliratm/Votify-API)\n![GitHub contributors](https://img.shields.io/github/contributors/brunoliratm/Votify-API)\n\n\u003c/div\u003e\n\n## 📋 Overview\n\nVotify-Api is a REST API developed with Spring Boot for managing voting systems in cooperatives. The platform allows creating voting sessions, managing agendas, and controlling the voting process by associates.\n\n## 👥 Credits\n\n| \u003ca href=\"https://github.com/brunoliratm\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/114788642?v=4\" float=\"left\" width=\"40px\" height=40px\u003e\u003cp\u003eBruno Magno\u003c/p\u003e\u003c/a\u003e | \u003ca href=\"https://github.com/Paulo-Araujo-Jr\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/127964717?v=4\" float=\"left\" width=\"40px\" height=\"40px\"\u003e\u003cp\u003ePaulo Araujo\u003c/p\u003e\u003c/a\u003e | \u003ca href=\"https://github.com/MrMesquita\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/126338859?v=4\" float=\"left\" width=\"40px\" height=40px\u003e\u003cp\u003eMarcelo Mesquita\u003c/p\u003e\u003c/a\u003e |\n| --- | --- | --- |\n\n## ✨ Features\n\n- Authentication and authorization with different access levels (ADMIN, ORGANIZER, ASSOCIATE)\n- Creation and management of voting sessions with defined time periods\n- Management of agendas within sessions\n- Secure voting system (Yes/No) with user validation\n- Logical deletion (soft delete) for historical data preservation\n- Robust exception handling and comprehensive validations\n- Integrated API documentation via Swagger/OpenAPI\n\n## 🚀 Installation\n\n### Prerequisites\n\n- Java 21\n- PostgreSQL\n- Maven 3.9+\n\n### Setup\n\n1. Clone the repository\n\n```bash\ngit clone https://github.com/Exploit-Experts/Votify-Api.git\ncd Votify-Api\n```\n\n2. Configure environment variables\n\n```\nPOSTGRES_URL=localhost:5432/votify\nPOSTGRES_USER=your_username\nPOSTGRES_PASSWORD=your_password\nJWT_SECRET=your_jwt_secret_key\nMAIL_USERNAME=your_email@gmail.com\nMAIL_PASSWORD=your_email_password\nAPI_BASEURL=http://localhost:8080/api/v1\nADMIN_DEFAULT_EMAIL=admin@votify.com\nADMIN_DEFAULT_PASSWORD=admin123@\n```\n\n3. Build the project\n\n```bash\nmvn clean install\n```\n\n4. Run the application\n\n```bash\nmvn spring-boot:run\n# or\njava -jar target/votify-0.0.1-SNAPSHOT.jar\n```\n\n## 🔌 API Endpoints\n\n### Authentication\n\n- `POST /api/v1/auth/login` - User authentication\n- `POST /api/v1/auth/forgot-password` - Request password reset\n- `POST /api/v1/auth/reset-password` - Reset password with received code\n\n### Users\n\n- `POST /api/v1/users` - Create a new user\n- `GET /api/v1/users` - List users\n  - Query Parameters:\n    - `page` (optional, default: 1) - Page number\n    - `name` (optional) - Filter by name\n    - `role` (optional) - Filter by role (ADMIN, ORGANIZER, ASSOCIATE)\n- `GET /api/v1/users/{id}` - Find user by ID\n- `PUT /api/v1/users/{id}` - Update user\n- `DELETE /api/v1/users/{id}` - Delete user (soft delete)\n\n### Sessions\n\n- `POST /api/v1/sessions` - Create a new session\n- `GET /api/v1/sessions` - List all sessions\n  - Query Parameters:\n    - `page` (optional, default: 1) - Page number\n    - `sort` (optional, default: id) - Field to sort\n    - `direction` (optional, default: ASC) - Sort direction (ASC, DESC)\n- `GET /api/v1/sessions/{id}` - Find session by ID\n- `PUT /api/v1/sessions/{id}` - Update session\n- `DELETE /api/v1/sessions/{id}` - Delete session (soft delete)\n\n### Agendas\n\n- `POST /api/v1/agendas` - Create a new agenda\n- `GET /api/v1/agendas` - List all agendas\n  - Query Parameters:\n    - `page` (optional, default: 1) - Page number\n    - `sort` (optional, default: id) - Field to sort\n    - `direction` (optional, default: ASC) - Sort direction (ASC, DESC)\n- `GET /api/v1/agendas/{id}` - Find agenda by ID\n- `PUT /api/v1/agendas/{id}` - Update agenda\n- `DELETE /api/v1/agendas/{id}` - Delete agenda (soft delete)\n- `PATCH /api/v1/agendas/{id}/start-voting` - Start voting on an agenda\n  - Query Parameters:\n    - `durationSeconds` (optional) - Voting duration in seconds\n- `PATCH /api/v1/agendas/{id}/stop-voting` - Stop voting on an agenda\n\n### Votes\n\n- `POST /api/v1/votes` - Register a vote (only for associates)\n- `PATCH /api/v1/votes` - Update an existing vote (only for associates)\n\n## 🛠️ Technologies\n\n- Java 21\n- Spring Boot 3.3.5\n- Spring Security with JWT\n- Spring Data JPA\n- Spring Mail for email sending\n- Hibernate/JPA\n- PostgreSQL\n- Lombok\n- BCrypt for password encryption\n- Swagger/OpenAPI for documentation\n- Maven\n- Docker \u0026 Docker Compose\n\n## 🐳 Docker Support\n\nThe application includes Docker support for easy deployment in any environment. The Dockerfile sets up the appropriate Java runtime environment and configures the application for production use.\n\n### Dockerfile Features\n\n- Multi-stage build for optimized image size\n- Maven build in the first stage with Eclipse Temurin 21 Alpine\n- Slim JRE-based Alpine runtime image in the second stage\n- Proper layer caching for faster builds\n- Exposes port 8080 for the application\n- Includes curl for health check capabilities\n\n### Environment Variables\n\nThe application supports configuration through environment variables, which can be passed when running the Docker container. Spring Boot will automatically map these environment variables to application properties.\n\nCommon environment variables you can configure:\n\n- `POSTGRES_URL`: Database URL (e.g., localhost:5432/votify)\n- `POSTGRES_USER`: Database username\n- `POSTGRES_PASSWORD`: Database password\n- `JWT_SECRET`: Secret key used for JWT token signing\n- `MAIL_USERNAME`: Email address for sending notifications\n- `MAIL_PASSWORD`: Password for the email account\n- `API_BASEURL`: Base URL for the API (defaults to http://localhost:8080/api/v1)\n- `ADMIN_DEFAULT_EMAIL`: Email for the default admin user (default: admin@votify.com)\n- `ADMIN_DEFAULT_PASSWORD`: Password for the default admin user (default: admin123@)\n- `SPRING_PROFILES_ACTIVE`: Set to your desired Spring profile (default, dev, prod)\n- `SERVER_PORT`: The port on which the application runs (default: 8080)\n\nWhen running in a Docker container, use `host.docker.internal` to connect to a database running on your host machine, for example:\n\n```bash\ndocker run --add-host=host.docker.internal:host-gateway \\\n  -e POSTGRES_URL=host.docker.internal:5432/votify \\\n  votify-api\n```\n\n### Docker Run Examples\n\n#### Basic run with default settings:\n\n```bash\ndocker build -t votify-api .\ndocker run -p 8080:8080 votify-api\n```\n\n#### Run with environment variables from a file:\n\n```bash\ndocker run -p 8080:8080 --env-file .env votify-api\n```\n\n#### Run with custom environment variables:\n\n```bash\ndocker run -p 8080:8080 \\\n  -e POSTGRES_URL=jdbc:postgresql://127.0.0.1:5432/votify \\\n  -e POSTGRES_USER=postgres \\\n  -e POSTGRES_PASSWORD=password \\\n  -e JWT_SECRET=your_secure_jwt_secret \\\n  -e ADMIN_DEFAULT_EMAIL=admin@votify.com \\\n  -e ADMIN_DEFAULT_PASSWORD=secure_admin_password \\\n  -e SPRING_PROFILES_ACTIVE=prod \\\n  -e API_BASEURL=http://localhost:8080/api/v1 \\\n  -e MAIL_USERNAME=your_email@gmail.com \\\n  -e MAIL_PASSWORD=your_email_password \\\n  votify-api\n```\n\n### Docker Compose\n\nFor a complete development environment with both the API and PostgreSQL database, use Docker Compose:\n\n```bash\ndocker compose up -d\n```\n\nThis will start both the Votify API and a PostgreSQL database with the appropriate configurations.\n\n#### Customizing Docker Compose Environment\n\nYou can customize the environment variables in Docker Compose using several approaches:\n\n1. **Using a .env file:**\n\n   Create a `.env` file in the same directory as your `docker-compose.yml`:\n\n   ```bash\n   # .env file\n   POSTGRES_USER=customuser\n   POSTGRES_PASSWORD=secretpassword\n   JWT_SECRET=your_custom_secret\n   ADMIN_DEFAULT_EMAIL=custom@votify.com\n   ADMIN_DEFAULT_PASSWORD=custom_password\n   ```\n\n   Docker Compose will automatically read this file and use these values.\n\n2. **Command line environment variables:**\n\n   ```bash\n   POSTGRES_PASSWORD=strongpassword JWT_SECRET=supersecret docker compose up -d\n   ```\n\n3. **Using the --env-file flag:**\n\n   ```bash\n   docker compose --env-file ./custom.env up -d\n   ```\n\n4. **Modifying `docker-compose.yml` directly:**\n\n   Edit the environment variables directly in the `docker-compose.yml` file.\n\nThese methods allow you to customize the environment for both development and production scenarios while keeping sensitive credentials out of version control.\n\n## 🔒 Security\n\n- Authentication via JWT (JSON Web Tokens)\n- Role-based access control (ADMIN, ORGANIZER, ASSOCIATE)\n- Passwords encrypted with BCrypt\n- Protection against common attacks\n- Data validation on all requests\n\n## 📚 Documentation\n\nThe API documentation is available at `http://localhost:8080/swagger-ui/index.html` when the application is running.\n\n## 📐 Architecture\n\nThe application follows a layered architecture:\n\n- **Controllers**: Handling HTTP requests and responses\n- **Facades**: Intermediaries between controllers and services\n- **Services**: Business logic\n- **Repositories**: Data access\n- **Models**: Domain entities\n- **DTOs**: Data transfer objects\n\nIt also implements several design patterns such as:\n\n- Facade\n- Repository\n- DTO\n- Service Layer\n- Soft Delete\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrunoliratm%2Fvotify-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrunoliratm%2Fvotify-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrunoliratm%2Fvotify-api/lists"}