Employee Creator Spring API + React App
A production-ready, full-stack HR management system built with Java Spring Boot and React TypeScript
Live Demo: Employee Creator App | ⚡ API: Employee Creator API
Project Overview
Employee Creator is a full-stack CRUD application for managing employee records and contracts. Built over 4 weeks as a solo project, it demonstrates enterprise-level development practices including comprehensive testing, CI/CD deployment, and scalable architecture.
Highlights
- ✅ Full-Stack: Java Spring Boot API + React TypeScript frontend
- ✅ Comprehensive Testing: 40+ automated tests (Unit, Integration, E2E)
- ✅ Production Deployed: Render + Neon (free tier); originally AWS EC2 + S3/CloudFront
- ✅ Enterprise Features: Employee management, contract tracking, form validation
- ✅ Modern Stack: TypeScript, Tailwind CSS, PostgreSQL, GitHub Actions
Key Features
Who this app is for:
-
For HR Teams: Streamline employee onboarding, track contract history, maintain compliance records
-
For Developers: Reference implementation showcasing modern full-stack patterns, testing strategies, and deployment practices
-
For Stakeholders: Production-ready system with scalable architecture and comprehensive audit trails
:man_office_worker: Employee Recordkeeping
- List of all employees at /employees
- Profile view with personal info and contracts
- Add (validated form), edit, and delete (with confirmation)
📄 Contracts Recordkeeping
- View all contracts per employee profile page
- Create contracts linked to an employee
- Delete contracts (WIP)
Note: An employee can have multiple contracts. Contracts are immutable by design: no update.
Tech Stack
A deliberately boring, industry-standard enterprise stack: scalable by design, with robust automated testing and safety checks at every layer.
| Layer | Technology | Benefit |
|---|
| DB | PostgreSQL, JPA | Relational integrity, portable data |
| Backend | Spring Boot, Java, Maven | Industry-standard, scalable APIs |
| Frontend | React, TypeScript, Vite | Fewer runtime bugs, fast builds |
| Testing | JUnit, Mockito, REST Assured, H2, Faker (Data seeding) | Catches regressions before release |
| Styling | Tailwind / SCSS | Consistent UI, faster styling |
| Deployment | Render + Neon (current); AWS EC2, S3 + CloudFront (archived) | Free-tier hosting, zero ops |
| CI/CD | GitHub Actions | Automated checks on every push |
| Monitoring | Log4j2 | Faster debugging in production |
Core Flow
flowchart LR
User --> React["React App"]
React -- "GET / POST / PATCH / DELETE /employees" --> API["Spring Boot API"]
API -- "SELECT / INSERT / UPDATE / DELETE" --> DB[(PostgreSQL)]
DB --> API --> React --> User
Database Design
- TDD approach: Tests written before implementation
- Entity separation: Employees vs Contracts for better organization
- One-to-Many relationship: Supports contract history tracking
- Immutable contracts: No update operations by design
Employees (1) → Contracts (Many)
Each employee can have multiple contracts over time. Contracts are immutable legal documents.
API Overview
| Method | Path | Purpose |
|---|
| GET | /employees | List employees |
| GET | /employees/{id} | Get one employee |
| POST | /employees | Create employee |
| PATCH | /employees/{id} | Update employee |
| DELETE | /employees/{id} | Delete employee |
| GET / POST | /contracts | List / create contracts |
| GET | /contracts/employee/{id} | List contracts for one employee |
| GET / DELETE | /contracts/{id} | Get / delete a contract |
Design Decisions
Backend (the behind-the-scenes part)
- Contracts stored separately. One employee can have many contracts over time. Editing a salary or end date touches only that contract.
- Status is calculated, not stored. An employee's status comes from their contracts each time it's read, so it can't go stale when a contract ends. Team leaders called this highly useful for HR workflows in their review.
- Delete is all-or-nothing. An employee and their contracts are deleted in one transaction, so a failure can't leave orphaned contracts.
- Saving your own email isn't a conflict. The duplicate check on update ignores the employee's own record, which fixed a false "email already taken" error.
- Known limit: loading contracts for status. Calculating status needs each employee's contracts, which reviewers flagged as a possible slowdown on larger databases. The plan is to load contracts only on single-employee views, then add pagination long term. Neither is built yet.
Live site safety
- Limited database access. The app reaches only its own data, so damage stays small if something goes wrong.
- Own website only. The backend accepts requests only from our front-end and requests are restricted to authorized users if server-side authorization is implemented.
- Secrets kept out of code. Passwords and keys are supplied at startup.
- Server limits. Memory is capped and crash retries stop after a few attempts.
Hosting on a budget
- Moved to free hosting for the demo. Moving from AWS to Render and Neon saves over $22/month. The cost is that the free Render service sleeps after 15 minutes without traffic.
- Uptime monitor over a scheduled GitHub job. UptimeRobot pings a health check every 5 minutes to keep the service awake. Scheduled workflows can be delayed or dropped, and they're disabled after 60 days of repo inactivity. UptimeRobot also emails on downtime, and needed no code changes.
Front-end (what people see and click)
- One form for add and edit. Less to maintain, consistent for users.
- Refresh and bookmarks work. Deep links no longer show an error.
Testing
| Type | Tools Used | Implementation |
|---|
| Spring Unit Tests | JUnit + Mockito | ✅ Service Layers |
| Spring E2E Tests | REST Assured, H2 | ✅ 40+ employees / contracts |
| React Component Tests | Vitest | ⏳ Basic |
To run tests, use the following commands:
./mvnw test # backend
npm run test # frontend (if added)
Quick Start
Prerequisites
- Java 21+
- Node.js 18+
- PostgreSQL 14+
Frontend (React)
cd front-end
npm install
npm run dev
# App available at: http://localhost:5173
Run Backend (Spring Boot)
cd employee
./mvnw clean install
./mvnw spring-boot:run
# API available at: http://localhost:8080
Database and environment (backend)
Install PostgreSQL (macOS: brew install postgresql && brew services start postgresql; Windows: download), then:
CREATE DATABASE your_database_name;
Create employee/.env:
DB_HOST=localhost
DB_PORT=5432
DB_NAME=your_database_name
SPRING_DATASOURCE_USERNAME=your_user
SPRING_DATASOURCE_PASSWORD=your_password
Create front-end/.env:
VITE_API_URL=http://localhost:8080
Other front-end commands: npm run build (production build), npm run preview (test the build).
Request examples
POST /employees
{
"firstName": "Timmy",
"lastName": "Turner",
"email": "[email protected]",
"phone": "0400000000",
"address": "123 Fairy Lane" //opt
}
PATCH /employees/{id} takes the same fields.
POST /contracts
{
"employeeId": 15,
"department": "SALES",
"contractType": "FULL_TIME",
"salaryAmount": 80000,
"hoursPerWeek": 38,
"startDate": "2023-01-10",
"endDate": null //opt
}
Redeploying (archived AWS setup)
# backend
./mvnw clean package -DskipTests
scp -i <key.pem> target/employee-creator.jar ubuntu@<EC2_IP>:/home/ubuntu/apps/employee-creator-spring/
ssh -i <key.pem> ubuntu@<EC2_IP> "sudo systemctl restart employee-creator"
# front-end
npm run build
aws s3 sync dist/ s3://<bucket-name> --delete
aws cloudfront create-invalidation --distribution-id <DIST_ID> --paths "/*"
Archived AWS details: the backend ran as a systemd service behind Nginx with Let's Encrypt TLS and a local PostgreSQL. The front-end ACM certificate had to be requested in us-east-1 (CloudFront requirement).
Deployment (archived AWS setup)
Backend API is deployed on AWS EC2. The frontend React app is deployed separately on S3 + CloudFront, and communicates with this backend via HTTPS.
| Layer | Service | Domain |
|---|
| Frontend (React) | S3 static site behind CloudFront | employeecreator.site |
| Backend (Spring Boot) | EC2 (Nginx reverse proxy → systemd service) | api.employeecreator.site |
| Database | PostgreSQL, local to the EC2 instance | — |
Note: Due to AWS costs, the long-term demo deployment has migrated to Render + Neon Postgres (free tier). Config: render.yaml. The AWS details above are kept for reference and the AWS workflows in .github/workflows/ are archived (not in use).
Skills and Lessons Learned
I built this employee management app on my own, as a practice run of how real business software gets made. The goal was to work the way a professional team would:
- Plan for growth = Modularity. Split the app into clear parts so each can be changed or scaled without disturbing the others. Keep each piece focused on a single responsibility, which makes problems easier to find and fix.
- Make it genuinely live. Put it on the internet the way a real product would be, not just on my own laptop.
- Keep good records. Write documentation and a running log of changes so anyone can see what changed and why.
Key Challenges of this project
| Area | Challenge | What I Did |
|---|
| Connecting the pieces | Frontend and backend wouldn't talk once hosted on AWS | Fixed access rules so only the website could reach the backend |
| Testing | Writing tests first slowed me down | Tried the app by hand first, then wrote tests. Better balance for a solo project |
| Going live | Automated releases were fiddly | Changed one small thing at a time and re-tested |
| Working like a team | Simulating team practice solo | Stable main plus dev, one branch per feature, tidied history before merging |
| Keeping it organised | Documenting a two-part project | Split front and back end by purpose; kept the change log updated |
Known issues
- [4/11/26] Employee whose only contract has ended shows as
NEW_HIRE instead of INACTIVE (#55)
- [5/08/25] Contract deletion is not fully implemented yet in front-end (WIP)
- [4/08/25] Pagination needed for employee list to reduce API load times and improve UX
- [4/08/25] Contract form should not have employee ID field - this is a UX issue (risk of human error)
- [25/07/25] React unit tests are still WIP
Future Goals
Full plan: docs/roadmap.md.
- Foundations: fix employee status (#55), CORS, profile config and seeding bugs
- Performance: pagination (#56), search and filtering, and status computed in SQL, with published before/after query counts
- Auth and roles: session login, admin and viewer roles, salary hidden from viewers, one-click demo logins
- UI: admin-only delete on the list, role title on the employee card, consistent states and spacing
Licensing Details
MIT License.
