Overview

Staff Track is a lightweight workforce management system designed to keep employee, project, and payroll data consistent and auditable — without relying on spreadsheets.

The system provides a structured way to manage employees, projects, roles, levels, and salary rates, while maintaining clear auditability of changes and historical data. It is intended for small to mid-sized teams where transparency, correctness, and maintainability matter more than complex enterprise workflows.

Core Capabilities

Staff Track focuses on a small but well-defined feature set:

  • Track monthly hours per project and employee
  • Calculate payroll using level-based salary rates
  • Export reports to XLSX and PDF formats
  • Manage roles, levels, statuses, and audit logs

Each feature is designed to be explicit, predictable, and easy to test.

System Architecture

Staff Track is built as a classic frontend–backend split system:

  • Backend: FastAPI (REST API)
  • Frontend: React with Bootstrap-based UI
  • Database: PostgreSQL
  • Authentication: JWT-based auth with email verification

The backend acts as a single source of truth, while the frontend remains a thin client responsible for presentation and user interactions.

[ React UI ] → [ FastAPI API ] → [ PostgreSQL ]

Backend Design

API Layer

  • RESTful endpoints grouped by domain (users, employees, projects, rates)
  • Explicit request/response schemas using Pydantic
  • Centralized error handling with clear HTTP status codes

Data Model

The domain model is intentionally normalized:

  • Employees are linked to levels, roles, and statuses
  • Projects are managed independently and assigned explicitly
  • Salary rates are defined per level
  • Logs provide historical tracking of important changes

This avoids hidden coupling and makes data changes traceable.

Frontend Design

The frontend is built with React + Bootstrap, focusing on clarity rather than visual complexity.

Key UI decisions:

  • Sidebar-based navigation for domain separation
  • Forms with explicit validation and feedback
  • Calendar widgets for date-based logs
  • No business logic in the UI — all calculations live in the backend

Authentication & Security

  • JWT-based authentication (access tokens)
  • Email verification during sign-up
  • Token expiration and refresh handled server-side
  • Role-based access prepared at the API level

Security decisions favor simplicity and auditability over advanced identity flows.

Testing Strategy

Testing is treated as a first-class concern.

Backend Tests

  • Unit tests for services and business logic
  • Integration tests for API endpoints
  • Database isolation using a test database
  • Pytest as the main test framework

Example focus areas:

  • Payroll calculation correctness
  • Permission checks
  • Data consistency across related entities

Code Quality

  • Black and isort for backend formatting
  • Prettier and ESLint for frontend
  • Consistent CI-friendly test execution

Why This Design

The goal of Staff Track is not to be a feature-heavy HR system, but a reliable internal tool:

  • Easy to understand for developers
  • Predictable behavior for users
  • Simple to extend without rewriting core logic
  • Straightforward to test and maintain

Most complexity is avoided deliberately.

Future Improvements

Planned or possible extensions include:

  • Advanced reporting and dashboards
  • Fine-grained role permissions
  • Import/export automation
  • Multi-organization support

All future features are evaluated against the same principle:
clarity over cleverness.

Conclusion

Staff Track is a practical example of building a focused internal system with:

  • Clear domain boundaries
  • Explicit business rules
  • Strong testing discipline
  • Minimal but intentional architecture

It reflects an engineering-first approach to product development.