PayChecker Overview

PayChecker is a web application that helps federal air traffic controllers verify backpay calculations during government shutdowns. The system parses Leave & Earnings Statements (LES) from employeeexpress.gov and compares actual pay against expected pay calculations based on the NATCA-FAA contract (Slate Book).

Historical Context

During the 2018-2019 government shutdown, many federal air traffic controllers experienced pay calculation errors when service resumed. PayChecker addresses this by providing an automated verification system to help members ensure they received correct backpay.

Current Version: 0.2.0 (Active Development)

Key Features

Implemented Features

• LES PDF Parser - Coordinate-based extraction of pay data from federal LES PDFs

  • Extracts pay period information, pay rates, hours worked, earnings, deductions, leave balances
  • Uses pdfplumber for precise coordinate-based text extraction
  • Parser version: 1.0.1

• Shift Tracking System

  • Create, read, update, delete (CRUD) operations for shifts
  • Three shift types: Regular, TOS (Time Off Station), TNW (Time Not Worked)
  • RDO (Regular Day Off) represented by absence of shift records

• Premium Time Tracking

  • OJTI (On-the-Job Training Instructor) time tracking
  • CIC (Controller-in-Charge) time tracking
  • TOS entries (Overtime, Credit Hours Earned)
  • TNW entries (Annual Leave, Sick Leave, LWOP, etc.)

• Pay Period Management

  • 26 biweekly pay periods per year (PP 01-26)
  • Current period detection and historical range queries
  • Pay period reference data with start/end/pay dates

• Data Aggregation & Summaries

  • Aggregated shift data with nested premium time per pay period
  • Summary calculations (total hours by category)
  • Hours/minutes overflow handling

• Database Integration

  • Two-schema architecture (public + pay schemas)
  • Cross-schema foreign keys to platform member data
  • Row-Level Security (RLS) policies for data isolation

• Authorization System

  • Employee-scoped access (users access own data)
  • Facility data management permissions for FacReps
  • Development mode bypass for local testing

In Progress

• Multi-Pay-Period Verification
• Pay Calculation Engine (verify expected vs actual pay)
• User Authentication (Auth0 integration)
• Frontend UI enhancements

Planned Features

• Frontend Vue.js dashboard for members
• Shift tracking with manual entry
• Reporting and export functionality
• Admin dashboard for NATCA staff

Technology Stack

Architecture Overview

┌─────────────────┐
│   Vue.js SPA    │ ← Frontend (Vite + Vue 3)
│   (Browser)     │
└────────┬────────┘
         │ HTTPS/REST
         ↓
┌─────────────────┐
│  FastAPI Server │ ← Backend (Python 3.12 + FastAPI)
│   (Railway)     │
└────────┬────────┘
         │ PostgreSQL
         ↓
┌─────────────────┐
│    Supabase     │ ← Database + Auth
│   (PostgreSQL)  │
└─────────────────┘

Project Structure

pay_checker/
├── pay_checker/                # Python package (backend)
│   ├── api/                    # FastAPI REST API (12 modules)
│   ├── pdf_parser/             # LES PDF parser (12 modules)
│   ├── verification/           # Pay verification engine (5 modules)
│   ├── payperiod/              # Pay period calculations (4 modules)
│   └── scripts/                # Utility scripts
├── frontend/                   # Vue.js application
│   ├── src/
│   │   ├── components/         # Vue components (27 files)
│   │   ├── services/           # API service layer
│   │   └── utils/              # Utility functions
│   └── public/                 # Static assets
├── supabase/                   # Database migrations
│   ├── migrations/             # 11 SQL migration files
│   ├── scripts/                # DB utility scripts
│   └── seed.sql                # Seed data (regions, facilities)
├── tests/                      # Test suite (10 directories)
├── docs/                       # Documentation (15 markdown files)
└── specs/                      # Feature specifications

Database Schema

PayChecker uses a two-schema architecture:

public Schema (Platform - READ-ONLY)

• public.members - NATCA member directory
• public.facilities - ATC facilities (towers, centers, TRACONs)
• public.positions - Member facility assignments and roles
• public.regions - NATCA regions (9 regions)
• public.grants - Permission grants

pay Schema (PayChecker - READ-WRITE)

• pay.pay_periods - Pay period reference (PP 01-26)
• pay.les_pay_periods - Parsed LES data (main table)
• pay.les_earnings - Earnings line items
• pay.les_deductions - Deduction line items
• pay.les_paid_by_govt - Government-paid benefits
• pay.les_leave_balances - Leave balances
• pay.les_remarks - LES remarks
• pay.shifts - Shift tracking with audit fields
• pay.cic_time - CIC time tracking
• pay.ojti_time - OJTI time tracking
• pay.tos_tnw - TOS/TNW tracking

Benefits of Two-Schema Design:

• Database-level enforcement of read-only access to platform data
• Direct foreign key relationships ensure data integrity
• Clear separation of platform vs application data
• Simpler queries (JOIN across schemas)

Security Features

• Authentication: Auth0 integration (in progress)
• Authorization: Row-Level Security (RLS) policies
• Data Isolation: Employee-scoped access to shift/premium time data
• Facility Access: FacReps can view members at their facility
• PII Protection: LES PDFs deleted after parsing
• HTTPS/TLS: All communication encrypted in transit
• Secrets Management: Environment variables, never committed

Development Workflow

The project uses git worktrees for parallel feature development:

pay_checker/
├── main/          # Main branch (or bare repo)
├── 001/           # Feature 001: LES PDF Parser
├── 002/           # Feature 002: Multi-Pay-Period Verification
└── 012/           # Current worktree

Benefits:

• Work on multiple features simultaneously
• No branch switching required
• Each worktree has independent working directory

Code Quality Standards

Python

• PEP 8 compliant
• Ruff for formatting and linting (line length: 120)
• MyPy for strict type checking
• Decimal for all monetary calculations (never float)
• Google-style docstrings required
• Minimum 90% code coverage required
• 100% coverage for pay calculation functions

Vue.js

• Composition API (not Options API)
• <script setup> syntax
• PascalCase for components
• camelCase for functions

Pre-commit Hooks

• Ruff Format (auto-format)
• Ruff Lint (code issues)
• MyPy (type checking)
• Branch Protection (blocks commits to main)

Deployment

Development Environment

Local Machine:
├── Supabase (Docker) - Port 54321
├── FastAPI (uvicorn) - Port 8000
└── Vite Dev Server - Port 5173

Production Environment

┌───────────────────┐
│  Vercel (CDN)     │ ← Frontend (Vue.js SPA)
│  Global Edge      │
└────────┬──────────┘
         │ HTTPS
         ↓
┌───────────────────┐
│  Railway          │ ← Backend (FastAPI container)
│  US East Region   │
└────────┬──────────┘
         │ PostgreSQL (SSL)
         ↓
┌───────────────────┐
│  Supabase Cloud   │ ← Database + Auth
│  US East Region   │
└───────────────────┘

Cost Estimate

• Supabase: $0 (free tier, 500MB database, 2GB bandwidth)
• Railway: $5-10/month (free $5 credit + overage)
• Vercel: $0 (free tier, 100GB bandwidth)
• Total: ~$5-10/month for ~100 users

Related Documentation

• Architecture Details
• Setup & Configuration
• API Reference
• Database Schema
• Platform Integration

PayChecker helps ensure NATCA members receive correct backpay during and after government shutdowns. For setup instructions, see the Setup & Configuration guide.