{"id":29016401,"url":"https://github.com/urosengineer/timesheet-attendance-platform","last_synced_at":"2026-04-11T05:31:20.471Z","repository":{"id":301000114,"uuid":"1007856292","full_name":"urosengineer/timesheet-attendance-platform","owner":"urosengineer","description":"Production-grade, multi-tenant attendance \u0026 workflow backend built with Java 21 \u0026 Spring Boot 3.5+. Features RBAC, JWT security, audit logging, real-time notifications, GraphQL, observability, and fully documented REST API.","archived":false,"fork":false,"pushed_at":"2025-06-24T16:32:22.000Z","size":0,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-06-24T17:28:02.748Z","etag":null,"topics":["audit-loggin","ddd","docker","fly","gradle","grafana","graphql","i18n","java","jwt","mapstr","multi-tenant","pbac","postgresql","promethe","rbac","rest-api","spring-boot","swagger","websoc"],"latest_commit_sha":null,"homepage":"https://www.upwork.com/freelancers/~01fec0932cf5314b14?mp_source=share","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/urosengineer.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-06-24T16:28:10.000Z","updated_at":"2025-06-24T16:35:58.000Z","dependencies_parsed_at":"2025-06-24T17:38:47.373Z","dependency_job_id":null,"html_url":"https://github.com/urosengineer/timesheet-attendance-platform","commit_stats":null,"previous_names":["urosengineer/timesheet-attendance-platform"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/urosengineer/timesheet-attendance-platform","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urosengineer%2Ftimesheet-attendance-platform","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urosengineer%2Ftimesheet-attendance-platform/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urosengineer%2Ftimesheet-attendance-platform/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urosengineer%2Ftimesheet-attendance-platform/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/urosengineer","download_url":"https://codeload.github.com/urosengineer/timesheet-attendance-platform/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urosengineer%2Ftimesheet-attendance-platform/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261960448,"owners_count":23236575,"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":["audit-loggin","ddd","docker","fly","gradle","grafana","graphql","i18n","java","jwt","mapstr","multi-tenant","pbac","postgresql","promethe","rbac","rest-api","spring-boot","swagger","websoc"],"created_at":"2025-06-25T22:08:13.128Z","updated_at":"2026-04-11T05:31:20.463Z","avatar_url":"https://github.com/urosengineer.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# timesheet-attendance-platform\n\n\u003e **Curated and maintained by Uros — a backend engineer specializing in enterprise Java/Spring Boot solutions.  \n\u003e This repository demonstrates best practices in modern backend, identity management, workflow automation, and observability for business-critical SaaS applications.**\n\n---\n\n## About this Repository\n\nThis portfolio codebase presents a robust, production-grade backend platform for attendance, leave management, notification, and workflow automation in multi-tenant environments.  \nIt is designed for technical review, architectural demonstration, and professional code evaluation—not for direct production deployment.\n\n---\n\n## Features\n\n- 📊 **REST \u0026 GraphQL API** — Full business coverage, Swagger/OpenAPI 3 documentation, and live GraphiQL playground\n- 🔒 **JWT authentication \u0026 authorization** — Stateless, granular, and fully RBAC/PBAC compliant\n- 🛡️ **Role-based \u0026 permission-based access control** — Fine-grained security for all endpoints and business workflows\n- 🚀 **Domain-driven, modular architecture** — Clean separation of controller, service, handler, repository, and mapping layers\n- 🗂️ **Multi-tenancy** — Organizational data isolation, with tenant context on every request\n- 📝 **Audit logging \u0026 workflow event system** — Immutable, filterable audit trail for every sensitive operation\n- 🔔 **Notification system** — Extensible delivery (Email, WebSocket, Dummy/Test) with full observability and audit\n- 👥 **User, Organization, Role, Permission, Team, Attendance, Leave** — Rich, normalized entity model\n- 🗃️ **Soft deletion, restoration, and full traceability** — Data is never lost; every status transition is logged\n- 📨 **Internationalization (i18n)** — English \u0026 Serbian out-of-the-box, easy extension to other languages\n- 🖇️ **File export** — PDF, Excel, and CSV export endpoints for all core business data\n- 📦 **Production-grade containerization** — Docker Compose for DB, backend, Prometheus, Grafana (one-step onboarding)\n- 📈 **Observability \u0026 monitoring** — Micrometer, Prometheus, Grafana dashboards for all system \u0026 business KPIs\n- ✅ **Extensive unit tests for all key service layers and workflows**\n\n---\n\n## Technologies\n\n- Java 21+\n- Spring Boot 3.5+, Spring Security 6+\n- Spring Data JPA, Hibernate\n- Flyway (DB migrations)\n- PostgreSQL\n- MapStruct (DTO/entity mapping)\n- Micrometer, Prometheus, Grafana\n- Thymeleaf (email templating)\n- Docker \u0026 Docker Compose\n- Gradle (primary build tool; Maven build scripts available upon request)\n- WebSocket (STOMP)\n- OpenAPI / Swagger 3\n- JUnit 5, Mockito, AssertJ (testing)\n\n---\n\n## 🟢 Runnable Demo – Quick Start\n\nThis project is a fully runnable Spring Boot backend.\nYou can clone the repository, build the app, and launch all services using Docker Compose.\n\n**Instructions:**\n\nStart all services (build and run everything in Docker):\n\n```bash\ndocker-compose up --build\n```\n\nAll services (backend, PostgreSQL, Prometheus, Grafana) will start automatically.\n\n**Default ports:**\n\n- Backend: http://localhost:8081\n- Swagger UI: http://localhost:8081/swagger-ui.html\n- GraphiQL: http://localhost:8081/graphiql\n- Prometheus: http://localhost:9090\n- Grafana: http://localhost:3000 (admin/admin)\n\nAll credentials and demo secrets are intentionally visible for portfolio/demo use!\n\n---\n\n## Helper Script (Linux / MacOS)\n\nIf you are on Linux or MacOS, you can use the included helper script to automate the build and startup process:\n\n```\n./run-demo.sh\n```\n\nTip: If you get a \"Permission denied\" error, make the script executable:\n\n```\nchmod +x run-demo.sh\n```\n\n---\n\n## Windows users\n\nIf you are on Windows, you can use the included helper script:\n\n```cmd\nrun-demo.cmd\n```\n\n## Demo User Accounts\n\nUse the following demo accounts to authenticate via Swagger UI (`/swagger-ui.html`) or to test API endpoints:\n\n| Username         | Password     | Role(s)     | Organization | Description          |\n|------------------|--------------|-------------|--------------|----------------------|\n| uros             | admin123     | ADMIN       | CloudCore    | Full admin access    |\n| james.smith      | acmeadmin    | ADMIN       | Acme Ltd     | Admin for Acme Ltd   |\n| sophia.wilson    | gtadmin      | ADMIN       | GlobalTech   | Admin for GlobalTech |\n| alison.carter    | manager123   | MANAGER     | CloudCore    | Manager role         |\n| michael.evans    | employee123  | EMPLOYEE    | CloudCore    | Regular employee     |\n| lucy.taylor      | employee123  | EMPLOYEE    | CloudCore    | Regular employee     |\n| olivia.jones     | hrmanager    | MANAGER     | Acme Ltd     | Manager (Support)    |\n| daniel.moore     | acmedeveloper| EMPLOYEE    | Acme Ltd     | Product team member  |\n| liam.martin      | globalemp    | EMPLOYEE    | GlobalTech   | Marketing employee   |\n\n\u003e **Note:**  \n\u003e In this portfolio/demo configuration, the `ADMIN` role is intentionally granted full access to all endpoints to simplify testing and demonstration.  \n\u003e In production, RBAC/PBAC policies should be tailored to actual organizational requirements.\n\n---\n\n## Database ER Diagram\n\nEntity-Relationship (ER) diagram shows all core tables and relationships (User, Organization, Team, Role, Permission, Attendance, Leave, Notification, AuditLog, WorkflowLog).\n\n![Database ER Diagram](docs/database-er-diagram.png)\n*Entity-Relationship diagram: all core tables and relationships in the system.*\n\nMost business entities are organization-scoped for multi-tenant isolation (Role and Permission are global).  \nSoft delete and workflow status fields apply to all critical entities, enabling traceability and auditability.\n\n---\n\n## Configuration \u0026 Bootstrapping\n\n- **application.yml:** Developer-friendly defaults, parametrized for demo onboarding (dev profile, visible creds, open CORS)\n- **Database:** PostgreSQL, managed via Flyway migrations (`db/migration`)\n- **Connection pool:** HikariCP\n- **JPA:** Hibernate, `ddl-auto=validate` (safe for demo/review, recommend strict migration in prod)\n- **Internationalization:** All messages localized (EN, SR), easy extension (`messages.properties`)\n- **GraphQL:** REST \u0026 GraphQL endpoints, GraphiQL at `/graphiql`\n- **Security:** JWT config, strong secrets, RBAC/PBAC, method-level security\n- **Notifications:** Email (Thymeleaf, JavaMail), WebSocket (real-time)\n- **Swagger:** OpenAPI 3, full endpoint documentation, `swagger-ui.html`\n- **Spring Actuator:** Health, info, custom Prometheus metrics\n- **Monitoring:** Prometheus + Grafana dashboards, auto-wired\n- **Containerization:** Dockerfile, docker-compose.yml (DB, backend, Prometheus, Grafana, volume persistence)\n- **Helper scripts:** `run-demo.sh` / `run-demo.cmd` for one-step onboarding\n\n---\n\n## Security, Authentication, and Authorization\n\n- **JWT-based authentication:** Stateless access \u0026 refresh tokens, all claims (user/org/roles/perms) in JWT\n- **Refresh token blacklisting:** Prevents replay (in-memory for demo; swap to Redis for prod)\n- **RBAC/PBAC:** Dynamic @PreAuthorize checks, method-level security, granular role/permission resolution\n- **BCrypt password hashing**\n- **Custom exception handlers:** Localized, structured errors for forbidden/unauthorized access\n- **Open CORS for local/demo** (lock down in prod via config)\n- **All endpoints protected:** REST, GraphQL, WebSocket (JWT handshake)\n- **Multi-tenancy enforced:** Every request tied to org via JWT claim/context\n\n---\n\n## Domain Model \u0026 Multi-Tenancy\n\n- **Full entity coverage:** User, Organization, Team, Role, Permission, AttendanceRecord, LeaveRequest, Notification, AuditLog, WorkflowLog\n- **Multi-tenancy:** All critical business entities (User, AttendanceRecord, LeaveRequest, Notification, etc.) are organization-scoped via per-request tenant context (ThreadLocal). Role and Permission entities are global, enabling centralized access control definitions shared across all tenants\n- **Soft delete:** All critical entities use `deletedAt`, isDeleted/restore helpers, full audit trail\n- **Status-driven workflows:** Attendance \u0026 leave records managed by central workflow engine; all status changes audited and reversible\n- **Notification system:** Type-safe enum, channel-agnostic delivery, extensible for new business/event types\n- **Audit \u0026 WorkflowLog:** Immutably logs all sensitive ops, status changes, approvals, rejections, deletions, with actor/context info\n\n---\n\n## API Modeling \u0026 DTO Layer\n\n- **No entities exposed via API** — only DTOs, strictly versioned and organized per business domain\n- **Swagger/OpenAPI annotated:** All DTOs are auto-documented for clear frontend/backend contract\n- **Dedicated DTOs:** Create/Update, Response, Export, Audit, Notification, Auth\n- **UUIDs for all resource IDs**\n- **Request/response separation:** Enables API evolution and backward compatibility\n\n---\n\n## Mapping \u0026 Service Layer\n\n- **MapStruct-powered:** All DTO\u003c-\u003eentity transformations are compile-time, declarative, and testable\n- **Service orchestration:** Controllers delegate to services (transactional boundaries, validation, metrics, audit, notification)\n- **Handler pattern:** Business actions encapsulated per handler (approve, reject, delete, restore), supporting modularity and testability\n- **Workflow engine:** Centralized state machine validation for status-driven entities\n\n---\n\n## Controller/API Layer\n\n- **REST \u0026 GraphQL APIs:** Every core business object is exposed via REST endpoints (full CRUD \u0026 workflow actions) and via GraphQL queries (read-only).\n- **Versioned \u0026 discoverable:** All endpoints under `/api/v1/...`, full OpenAPI/Swagger coverage\n- **GraphiQL IDE:** For live GraphQL exploration (`/graphiql`)\n- **Export \u0026 reporting endpoints:** Download business data in CSV, Excel, or PDF for BI or compliance\n- **WebSocket (STOMP):** Real-time notifications, per-user or broadcast, secured with JWT\n- **Thin, maintainable controllers:** No business logic, only API contract/security/delegation\n\n---\n\n## Audit Logging \u0026 Workflow Events\n\n- **AuditLog entity:** Persists all sensitive events (login, create, delete, approve, reject, status change, etc.) with user/context/time\n- **WorkflowLog:** Tracks status transitions, approval/rejection, and comments per entity\n- **Immutable and queryable:** For compliance and regulatory review\n- **APIs:** Secure, paginated, and filterable log endpoints (by user, event type)\n- **All logs localized and fully DTO-encapsulated**\n\n---\n\n## Notification \u0026 Real-Time Messaging\n\n- **Email notifications:** HTML, branded, localized (Thymeleaf), demo SMTP config\n- **WebSocket notifications:** Real-time to users, JWT-secured handshake, per-user queues\n- **Dummy channel:** Test, mock, or non-delivery scenarios\n- **Type-safe NotificationType enum:** For business and delivery types\n- **All sends audited, instrumented, and visible in metrics**\n\n---\n\n## Exception Handling\n\n- **GlobalExceptionHandler:** All errors mapped to structured JSON with timestamp, status, message, and localization\n- **Domain-specific exceptions:** Export, workflow, validation, not found, forbidden/unauth, etc.\n- **No stack traces or sensitive data exposed**\n\n---\n\n## Database Seeder \u0026 Demo Data\n\n- **Turnkey onboarding:** On first run, all core data is seeded (orgs, users, roles, perms, teams, attendance, leave, audit, workflow, notifications)\n- **Idempotent \u0026 modular:** Each seeder is isolated and checks data presence before insert\n- **Realistic scenarios:** All workflow transitions, logs, notifications, and approvals are simulated\n- **Easy extension:** Add/modify scenarios in one class per domain\n\n---\n\n## Observability \u0026 Monitoring\n\n- **Prometheus:** Scrapes `/actuator/prometheus` every 15s, all system \u0026 business KPIs exported  \n- **Grafana:** Pre-wired dashboards (app readiness, users, attendance, orgs, roles)  \n- **Micrometer:** All custom metrics registered in code, extensible for new KPIs  \n- **One-step launch:** Monitoring stack included in Docker Compose\n\n**Quick access:**\n- Prometheus: [http://localhost:9090](http://localhost:9090)\n- Grafana: [http://localhost:3000](http://localhost:3000) (admin/admin)\n\n---\n\n### Example: Grafana Monitoring Dashboard\n\nThe platform ships with a production-style Grafana dashboard that visualizes live system and business KPIs exposed via Prometheus.\n\n![Grafana Dashboard](docs/grafana-main-dashboard.png)\n*Sample dashboard: Application readiness, total users, users by role/organization, attendance records by status/organization, and more.*\n\n- **All panels are fully wired:** Application health, user/attendance metrics, organizational segmentation.\n- **Demonstrates real-time observability** for business-critical SaaS applications.\n- **Ready for further extension** with any Prometheus/Micrometer-compatible metric.\n\n---\n\n## Testing\n\n- **JUnit 5 + Mockito/AssertJ:** Modular, isolated unit tests for all core services\n- **Coverage:** CRUD, soft-delete, restore, workflow, notification, audit, metrics, error handling\n- **Edge cases covered:** Permission/denied, DTO validation, transaction rollback\n- **Test data builders:** For maintainable test setup\n- **CI-ready:** Add JaCoCo for coverage enforcement as needed\n\n---\n\n## API Documentation\n\nAll endpoints are fully documented using Swagger/OpenAPI.\nBelow are example screenshots from the live Swagger UI:\n\n### API Endpoint Overview\n\n![API Endpoint Overview](docs/swagger-endpoint-overview-1.png)\n*Grouped endpoints – Attendance, Teams, Authentication, Notifications, Users*\n\n![API Endpoint Overview (continued)](docs/swagger-endpoint-overview-2.png)\n*Grouped endpoints – Audit Logs, Permissions, Roles, Organizations, Export, Leave Requests*\n\n### Example: Audit Log Query\n\n![Audit Log Query](docs/swagger-audit-log-query.png)\n*Paginated audit log querying with filters and sample response*\n\n### Example: Export Endpoint\n\n![Export PDF Endpoint](docs/swagger-export-pdf.png)\n*PDF export endpoint: parameters, response codes, and format selection*\n\n![Export Excel Endpoint](docs/swagger-export-excel.png)\n*Excel export endpoint: parameters, response codes, and format selection*\n\n---\n\n## GraphQL Playground Demo\n\nAn interactive GraphQL IDE is available at [`/graphiql`](http://localhost:8081/graphiql), providing live querying of key business entities:\n\n- **Users** (`user`, `users`)\n- **Organizations** (`organization`, `organizations`)\n- **Teams** (`team`, `teams`)\n- **Roles and Permissions** (`role`, `roles`)\n- **Attendance Records** (`attendanceRecord`, `attendanceRecordsForUser`)\n\n\u003e **Note:**  \n\u003e The GraphQL API is currently **read-only** (queries only), by design.  \n\u003e All mutations (create/update/delete, workflow actions) are provided exclusively via the REST API.\n\u003e \n\u003e This separation is intentional for portfolio/demo purposes, focusing on safe, query-driven exploration of the business model.  \n\u003e Write operations can be extended as needed for production scenarios.\n\n![GraphQL Playground Example](docs/graphql-playground-organizations.png)  \n*GraphQL playground: Example query for organizations and real-time result.*\n\n---\n\n## Project Structure\n\n```\n├── .gradle/\n├── .idea/\n├── build/\n├── docs/\n│   └── (ER diagrams, API screenshots, Grafana dashboards, etc.)\n├── monitoring/\n│   ├── application-ready-time-dashboard.json\n│   ├── application-started-time.json\n│   ├── attendance-records-by-organization.json\n│   ├── attendance-status-overview.json\n│   ├── prometheus.yml\n│   ├── total-users.json\n│   ├── users-by-role.json\n│   └── users-per-organization.json\n├── src/\n│   ├── main/\n│   │   ├── java/\n│   │   │   └── com/uros/timesheet/attendance/\n│   │   │        ├── auditlog/\n│   │   │        ├── config/\n│   │   │        ├── controller/\n│   │   │        ├── domain/\n│   │   │        ├── dto/\n│   │   │        ├── enums/\n│   │   │        ├── event/\n│   │   │        ├── exception/\n│   │   │        ├── graphql/\n│   │   │        ├── health/\n│   │   │        ├── i18n/\n│   │   │        ├── mapper/\n│   │   │        ├── metrics/\n│   │   │        ├── notification/\n│   │   │        ├── repository/\n│   │   │        ├── seeder/\n│   │   │        ├── security/\n│   │   │        ├── service/\n│   │   │        ├── util/\n│   │   │        ├── websocket/\n│   │   │        └── workflow/\n│   │   └── resources/\n│   │        ├── db/migration/\n│   │        ├── graphql/\n│   │        ├── templates/\n│   │        ├── application.yml\n│   │        ├── messages.properties\n│   │        └── messages_sr.properties\n│   └── test/\n│        └── java/com/uros/timesheet/attendance/\n│            ├── security/\n│            ├── service/\n│            └── ...\n├── .gitattributes\n├── .gitignore\n├── build.gradle\n├── docker-compose.yml\n├── Dockerfile\n├── gradlew\n├── gradlew.bat\n├── HELP.md\n├── README.md\n├── run-demo.cmd\n├── run-demo.sh\n└── settings.gradle\n```\n\n## Production Usage \u0026 Portfolio Notice\n\n\u003e ⚠️ **Portfolio/Demo Mode:**  \n\u003e This repository is provided strictly for portfolio and demonstration purposes.  \n\u003e All credentials, secrets, and configs are public for code review.  \n\u003e Not a production deployment — full business logic, proprietary modules, and advanced integrations remain private.  \n\u003e Build/run instructions are for local onboarding and review, not for direct prod use.\n\u003e\n\u003e **For full access (NDA/enterprise review):**  \n\u003e Contact via LinkedIn or Upwork to discuss private review, architecture consultations, or codebase deep-dive.\n\n---\n\n## Portfolio \u0026 Contact\n\nFor technical deep-dive, architecture consultations, or backend contract work, contact via  \n[LinkedIn](https://www.linkedin.com/in/uros-ilic-6a201436a/).\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](./LICENSE) file for details.\n\n## Contribution\n\nThis is a personal portfolio project; **external contributions are not being accepted** at this time.\n\n---\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Furosengineer%2Ftimesheet-attendance-platform","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Furosengineer%2Ftimesheet-attendance-platform","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Furosengineer%2Ftimesheet-attendance-platform/lists"}