This document provides a comprehensive overview of the Payroll Check System architecture and components.
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Presentation Layer β
β ββββββββββββββββ ββββββββββββββββ ββββββββββββββββ β
β β Company β β Employee β β Payroll β β
β β Controller β β Controller β β Controller β β
β ββββββββββββββββ ββββββββββββββββ ββββββββββββββββ β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β
βΌ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Service Layer β
β ββββββββββββββββ ββββββββββββββββ ββββββββββββββββ β
β β Company β β Employee β β Payroll β β
β β Service β β Service β β Service β β
β ββββββββββββββββ ββββββββββββββββ ββββββββββββββββ β
β ββββββββββββββββ β
β β Tax β β
β β Calculation β β
β β Service β β
β ββββββββββββββββ β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β
βΌ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Repository Layer (JPA) β
β ββββββββββββββββ ββββββββββββββββ ββββββββββββββββ β
β β Company β β Employee β β Payroll β β
β β Repository β β Repository β β Repository β β
β ββββββββββββββββ ββββββββββββββββ ββββββββββββββββ β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β
βΌ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Database Layer β
β H2 (Development) / PostgreSQL (Production) β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Payroll-Check/
β
βββ src/
β βββ main/
β β βββ java/com/payrollcheck/
β β β β
β β β βββ PayrollCheckApplication.java # Main application entry point
β β β β
β β β βββ config/ # Configuration classes
β β β β βββ DataInitializer.java # Sample data loader
β β β β βββ ModelMapperConfig.java # DTO mapping configuration
β β β β βββ OpenApiConfig.java # Swagger/OpenAPI configuration
β β β β βββ SecurityConfig.java # Security configuration
β β β β
β β β βββ controller/ # REST API Controllers
β β β β βββ CompanyController.java # Company endpoints
β β β β βββ EmployeeController.java # Employee endpoints
β β β β βββ PayrollController.java # Payroll endpoints
β β β β βββ PayrollItemController.java # Payroll item endpoints
β β β β
β β β βββ dto/ # Data Transfer Objects
β β β β βββ CompanyDTO.java
β β β β βββ EmployeeDTO.java
β β β β βββ PayrollDTO.java
β β β β βββ PayrollItemDTO.java
β β β β βββ CreatePayrollRequest.java
β β β β βββ UpdatePayrollItemRequest.java
β β β β
β β β βββ exception/ # Exception handling
β β β β βββ BusinessException.java
β β β β βββ DuplicateResourceException.java
β β β β βββ ResourceNotFoundException.java
β β β β βββ GlobalExceptionHandler.java
β β β β βββ ErrorResponse.java
β β β β βββ ValidationErrorResponse.java
β β β β
β β β βββ model/ # Domain entities
β β β β βββ BaseEntity.java # Base entity with audit fields
β β β β βββ Company.java # Company entity
β β β β βββ Employee.java # Employee entity
β β β β βββ Payroll.java # Payroll entity
β β β β βββ PayrollItem.java # PayrollItem entity
β β β β βββ enums/
β β β β βββ EmploymentType.java
β β β β βββ PayFrequency.java
β β β β βββ PayrollStatus.java
β β β β
β β β βββ repository/ # Data access layer
β β β β βββ CompanyRepository.java
β β β β βββ EmployeeRepository.java
β β β β βββ PayrollRepository.java
β β β β βββ PayrollItemRepository.java
β β β β
β β β βββ service/ # Business logic
β β β βββ CompanyService.java
β β β βββ EmployeeService.java
β β β βββ PayrollService.java
β β β βββ TaxCalculationService.java
β β β
β β βββ resources/
β β βββ application.yml # Main configuration
β β βββ application-prod.yml # Production configuration
β β
β βββ test/
β βββ java/ # Test classes (to be implemented)
β
βββ pom.xml # Maven dependencies
βββ README.md # Main documentation
βββ QUICKSTART.md # Quick start guide
βββ PROJECT_STRUCTURE.md # This file
βββ .gitignore # Git ignore rules
- Represents a business entity using the payroll system
- Key Fields: name, EIN, address, contact info
- Relationships: One-to-Many with Employee and Payroll
- Represents a person employed by a company
- Key Fields: personal info, SSN, compensation, tax withholding
- Relationships: Many-to-One with Company, One-to-Many with PayrollItem
- Represents a payroll run for a specific pay period
- Key Fields: period dates, pay date, status, totals
- Relationships: Many-to-One with Company, One-to-Many with PayrollItem
- Represents an individual employee's payment in a payroll run
- Key Fields: gross pay, taxes, deductions, net pay, YTD totals
- Relationships: Many-to-One with Payroll and Employee
- CRUD operations for companies
- Company search and filtering
- Active/inactive status management
- Employee lifecycle management (hire, update, terminate)
- Employee queries by various criteria
- Department and employment type filtering
- Payroll creation and management
- Payroll item generation
- Payroll processing workflow
- Year-to-date calculations
- Federal income tax calculation (2024 brackets)
- FICA tax calculation (Social Security and Medicare)
- State income tax calculation
- Wage base limit tracking
All repositories extend JpaRepository and provide:
- Standard CRUD operations
- Custom query methods
- Complex queries using @Query annotations
- Optimized data access patterns
POST /api/companies- Create companyGET /api/companies/{id}- Get companyPUT /api/companies/{id}- Update companyPATCH /api/companies/{id}/activate- ActivateDELETE /api/companies/{id}- Delete
POST /api/companies/{companyId}/employees- Create employeeGET /api/companies/{companyId}/employees- List employeesPUT /api/companies/{companyId}/employees/{id}- Update employeePATCH /api/companies/{companyId}/employees/{id}/terminate- Terminate
POST /api/companies/{companyId}/payrolls- Create payrollPOST /api/companies/{companyId}/payrolls/{id}/generate-items- Generate itemsPOST /api/companies/{companyId}/payrolls/{id}/process- Process payrollGET /api/companies/{companyId}/payrolls- List payrolls
PUT /api/payroll-items/{id}- Update itemGET /api/payroll-items/employee/{employeeId}- Get by employee
- Basic authentication setup
- CORS configuration
- Public endpoints for Swagger and H2 console
- DTO to Entity mapping
- Entity to DTO mapping
- Custom mapping rules
- Swagger/OpenAPI documentation
- API metadata
- Security scheme configuration
- Sample data creation for development
- Pre-populates companies and employees
- Only runs in non-production profiles
companies
βββ id (PK)
βββ name
βββ ein (UNIQUE)
βββ address, city, state, zip_code
βββ email, phone
βββ is_active
βββ created_at, updated_at, version
employees
βββ id (PK)
βββ company_id (FK)
βββ first_name, last_name
βββ ssn (UNIQUE)
βββ email (UNIQUE)
βββ phone, address, city, state, zip_code
βββ date_of_birth, hire_date, termination_date
βββ employment_type, job_title, department
βββ pay_frequency, salary, hourly_rate
βββ federal_allowances, state_allowances
βββ additional_federal_withholding, additional_state_withholding
βββ is_active
βββ created_at, updated_at, version
payrolls
βββ id (PK)
βββ company_id (FK)
βββ period_start_date, period_end_date, pay_date
βββ status
βββ total_gross_pay, total_net_pay, total_taxes, total_deductions
βββ processed_date, processed_by
βββ notes
βββ created_at, updated_at, version
payroll_items
βββ id (PK)
βββ payroll_id (FK)
βββ employee_id (FK)
βββ gross_pay, regular_hours, overtime_hours, bonus, commission
βββ federal_income_tax, state_income_tax
βββ social_security_tax, medicare_tax
βββ health_insurance, retirement_401k, other_deductions
βββ net_pay
βββ year_to_date_gross, year_to_date_tax
βββ notes
βββ created_at, updated_at, version- Progressive federal tax brackets
- Social Security wage base limit tracking
- Medicare and Additional Medicare tax
- State-specific tax rates
- Year-to-date accumulation
- DRAFT - Payroll created, editable
- PENDING - Ready for review
- PROCESSING - Being processed
- PROCESSED - Completed
- COMPLETED - Payments made
- CANCELLED - Cancelled before processing
- FAILED - Processing failed
- Bean Validation (JSR 380)
- Custom business rule validation
- Global exception handler
- Structured error responses
- OpenAPI 3.0 specification
- Interactive Swagger UI
- Request/response examples
- Authentication documentation
- Spring Boot 3.2.0 - Latest stable release
- Java 17 - Modern Java features
- JPA/Hibernate - ORM and data persistence
- H2/PostgreSQL - Flexible database support
- Lombok - Reduced boilerplate
- ModelMapper - DTO conversion
- Spring Security - Authentication
- SpringDoc OpenAPI - API documentation
- 37 Java source files
- 4 Controllers (REST endpoints)
- 4 Services (Business logic)
- 4 Repositories (Data access)
- 7 Domain entities
- 6 DTOs (Data transfer)
- 3 Enumerations
- 4 Configuration classes
- 6 Exception classes
- Repository Pattern - Data access abstraction
- Service Layer Pattern - Business logic separation
- DTO Pattern - Data transfer between layers
- Builder Pattern - Complex object construction
- Dependency Injection - Loose coupling
- Strategy Pattern - Tax calculation strategies
- Clear separation of concerns (MVC architecture)
- Comprehensive input validation
- Proper error handling and logging
- RESTful API design
- Transaction management
- Audit trail (created_at, updated_at)
- Optimistic locking (version field)
- Bidirectional relationship management
- Query optimization with indexes
Version: 1.0.0 Last Updated: 2024