Skip to content

Latest commit

Β 

History

History
357 lines (307 loc) Β· 14.5 KB

PROJECT_STRUCTURE.md

File metadata and controls

357 lines (307 loc) Β· 14.5 KB

Payroll Check System - Project Structure

Overview

This document provides a comprehensive overview of the Payroll Check System architecture and components.

System Architecture

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚                   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)     β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

Directory Structure

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

Core Components

1. Domain Models (Entities)

Company

  • Represents a business entity using the payroll system
  • Key Fields: name, EIN, address, contact info
  • Relationships: One-to-Many with Employee and Payroll

Employee

  • 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

Payroll

  • 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

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

2. Services

CompanyService

  • CRUD operations for companies
  • Company search and filtering
  • Active/inactive status management

EmployeeService

  • Employee lifecycle management (hire, update, terminate)
  • Employee queries by various criteria
  • Department and employment type filtering

PayrollService

  • Payroll creation and management
  • Payroll item generation
  • Payroll processing workflow
  • Year-to-date calculations

TaxCalculationService

  • Federal income tax calculation (2024 brackets)
  • FICA tax calculation (Social Security and Medicare)
  • State income tax calculation
  • Wage base limit tracking

3. Repositories

All repositories extend JpaRepository and provide:

  • Standard CRUD operations
  • Custom query methods
  • Complex queries using @Query annotations
  • Optimized data access patterns

4. Controllers (REST API)

CompanyController

  • POST /api/companies - Create company
  • GET /api/companies/{id} - Get company
  • PUT /api/companies/{id} - Update company
  • PATCH /api/companies/{id}/activate - Activate
  • DELETE /api/companies/{id} - Delete

EmployeeController

  • POST /api/companies/{companyId}/employees - Create employee
  • GET /api/companies/{companyId}/employees - List employees
  • PUT /api/companies/{companyId}/employees/{id} - Update employee
  • PATCH /api/companies/{companyId}/employees/{id}/terminate - Terminate

PayrollController

  • POST /api/companies/{companyId}/payrolls - Create payroll
  • POST /api/companies/{companyId}/payrolls/{id}/generate-items - Generate items
  • POST /api/companies/{companyId}/payrolls/{id}/process - Process payroll
  • GET /api/companies/{companyId}/payrolls - List payrolls

PayrollItemController

  • PUT /api/payroll-items/{id} - Update item
  • GET /api/payroll-items/employee/{employeeId} - Get by employee

5. Configuration

SecurityConfig

  • Basic authentication setup
  • CORS configuration
  • Public endpoints for Swagger and H2 console

ModelMapperConfig

  • DTO to Entity mapping
  • Entity to DTO mapping
  • Custom mapping rules

OpenApiConfig

  • Swagger/OpenAPI documentation
  • API metadata
  • Security scheme configuration

DataInitializer

  • Sample data creation for development
  • Pre-populates companies and employees
  • Only runs in non-production profiles

Database Schema

Core Tables

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

Key Features

Tax Calculation Engine

  • Progressive federal tax brackets
  • Social Security wage base limit tracking
  • Medicare and Additional Medicare tax
  • State-specific tax rates
  • Year-to-date accumulation

Payroll Processing Workflow

  1. DRAFT - Payroll created, editable
  2. PENDING - Ready for review
  3. PROCESSING - Being processed
  4. PROCESSED - Completed
  5. COMPLETED - Payments made
  6. CANCELLED - Cancelled before processing
  7. FAILED - Processing failed

Validation & Error Handling

  • Bean Validation (JSR 380)
  • Custom business rule validation
  • Global exception handler
  • Structured error responses

API Documentation

  • OpenAPI 3.0 specification
  • Interactive Swagger UI
  • Request/response examples
  • Authentication documentation

Technology Highlights

  • 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

Statistics

  • 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

Design Patterns Used

  1. Repository Pattern - Data access abstraction
  2. Service Layer Pattern - Business logic separation
  3. DTO Pattern - Data transfer between layers
  4. Builder Pattern - Complex object construction
  5. Dependency Injection - Loose coupling
  6. Strategy Pattern - Tax calculation strategies

Best Practices Implemented

  • 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