Mini-ATS - Backend

Modern Applicant Tracking System built with Spring Boot, Supabase Auth, and PostgreSQL. Features JWT authentication, multi-tenant architecture, and a Kanban-style recruitment pipeline.

---

📋 Table of Contents

• Overview
• Features
• Architecture
• Getting Started
• Authentication
• API Documentation
• Project Structure
• Configuration
• Security
• Deployment

---

🎯 Overview

Mini-ATS is a modern recruitment management platform that helps organizations track job candidates through a visual Kanban pipeline. Built with Spring Boot and Supabase, it features enterprise-grade authentication, multi-tenancy, and role-based access control.

Key Capabilities

• 🔐 Supabase Authentication: JWT-based auth with ES256 validation
• 🏢 Multi-tenant Architecture: Complete organization-level data isolation
• 📊 Kanban Pipeline: Visual tracking (NEW → SCREENING → INTERVIEW → OFFER / REJECTED)
• 👥 User Management: Admin users can create organizations and manage users
• 📝 Candidate Scorecards: 5-category rating system with auto-calculated averages
• 🔒 Secure by Default: JWT validation, CORS protection, security headers

---

✨ Features

🔐 Authentication & Authorization

• ✅ Supabase Auth Integration

  • JWT token validation using JWKS (ES256)
  • Automatic user creation in both auth.users and public.users
  • Session management with secure tokens

• ✅ Role-Based Access Control

  • ADMIN: Full system access, create users/orgs, manage all data
  • USER: Organization-scoped access only

• ✅ Security Features

  • JWT validation on all protected endpoints
  • CORS configuration for allowed origins
  • Spring Security integration
  • Service Role Key for admin operations

👥 User Management

• ✅ Admin and User roles
• ✅ Organization-based access control
• ✅ Admin impersonation (view any org's data)
• ✅ User creation via Admin Panel:
  • Creates user in Supabase Auth
  • Creates matching record in public.users
  • Links with same UUID
  • Password management

💼 Job Management

• ✅ Create and manage job postings
• ✅ Filter by status (ACTIVE/CLOSED/DRAFT)
• ✅ Search by title and department
• ✅ Track applications per job
• ✅ Department-based organization

👤 Candidate Management

• ✅ Complete candidate profiles
• ✅ LinkedIn profile integration
• ✅ Skills management (array field)
• ✅ Contact information storage
• ✅ Search and filter capabilities
• ✅ Scorecard System:
  • Technical Skills (1-5)
  • Communication (1-5)
  • Culture Fit (1-5)
  • Experience (1-5)
  • Leadership (1-5)
  • Auto-calculated overall rating
  • Real-time updates
• ✅ Activity Timeline:
  • Track all candidate interactions
  • Notes and comments
  • Status changes

📊 Kanban Pipeline

• ✅ Visual tracking across 5 stages
• ✅ Drag-and-drop status updates
• ✅ Enriched data (candidate + job info)
• ✅ Filter by job or candidate
• ✅ Pipeline statistics and metrics
• ✅ Stage-specific business logic

---

🏗️ Architecture

Design Patterns

Pattern	Usage
Builder	Immutable domain entities (Lombok)
Repository	Data access abstraction layer
DTO	Immutable records for API contracts
Service	Business logic separation
Filter	JWT authentication via Spring Security

System Layers

┌─────────────────────────────────────┐
│  REST Controllers (8)               │
│  - CORS protected                   │
│  - JWT authenticated                │
├─────────────────────────────────────┤
│  Security Layer                     │
│  - JwtAuthenticationFilter          │
│  - JwtTokenValidator (ES256)        │
├─────────────────────────────────────┤
│  Service Layer (7)                  │
│  - UserService                      │
│  - CandidateService                 │
│  - JobService                       │
│  - ApplicationService               │
│  - ScorecardService                 │
│  - ActivityService                  │
│  - SupabaseAuthService ⭐ (NEW)     │
├─────────────────────────────────────┤
│  Repository Layer (7)               │
│  - Supabase implementations         │
│  - Direct REST API calls            │
├─────────────────────────────────────┤
│  Supabase                           │
│  - PostgreSQL Database              │
│  - Auth System (JWT)                │
│  - JWKS Endpoint                    │
└─────────────────────────────────────┘

Database Schema

Key Tables:

• auth.users - Supabase Auth users (managed by Supabase)
• public.users - Application user profiles (linked to auth.users)
• public.organizations - Tenant organizations
• public.jobs - Job postings
• public.candidates - Candidate profiles
• public.applications - Pipeline stage tracking
• public.scorecards - Candidate evaluations
• public.activities - Audit trail

---

🛠️ Tech Stack

Core

Technology	Version	Purpose
Spring Boot	3.2.2	Application Framework
Java	17	Programming Language
Maven	3.8+	Build Tool
PostgreSQL	15+	Database (via Supabase)

Key Dependencies

Library	Purpose
spring-boot-starter-web	REST API
spring-boot-starter-security	Security & Auth
jjwt (0.12.5)	JWT validation (ES256)
postgresql	Database driver
lombok	Boilerplate reduction
jackson	JSON serialization
httpclient5	Supabase API calls
dotenv-java	Environment configuration

---

🚀 Getting Started

Prerequisites

java -version    # Java 17+
mvn -version     # Maven 3.8+

Quick Start

1. Clone Repository

git clone <your-repo-url>
cd mini-ATS

2. Configure Environment

Create .env file in project root:

# Supabase Configuration
SUPABASE_URL=https://xlrbdnnferxnitillzmt.supabase.co
SUPABASE_ANON_KEY=your_anon_key_here
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key_here

# Database Configuration
DB_URL=jdbc:postgresql://aws-0-eu-central-2.pooler.supabase.com:6543/postgres?user=postgres.xlrbdnnferxnitillzmt&password=YOUR_PASSWORD&pgbouncer=true
DB_USERNAME=postgres
DB_PASSWORD=your_db_password

# Application Configuration
SPRING_PROFILES_ACTIVE=dev
SERVER_PORT=8080

# JWT Configuration
SUPABASE_JWT_JWKS_URL=https://xlrbdnnferxnitillzmt.supabase.co/auth/v1/.well-known/jwks.json
JWT_EXPIRATION=86400000

# CORS Configuration (Frontend URLs)
CORS_ALLOWED_ORIGINS=http://localhost:5173,http://localhost:3000,https://your-frontend.vercel.app

# Admin Configuration
ADMIN_DEFAULT_EMAIL=admin@acme.com
ADMIN_DEFAULT_PASSWORD=ChangeThisPassword123!

3. Build & Run

# Build
mvn clean install

# Run
mvn spring-boot:run

API available at: http://localhost:8080/api

4. Verify

curl http://localhost:8080/api/health

Expected response:

{
  "success": true,
  "data": "OK",
  "error": null,
  "timestamp": "2026-02-09T14:00:00Z"
}

---

🔐 Authentication

Supabase JWT Authentication (ES256)

This application uses Supabase Authentication with JWT tokens validated using ES256 (Elliptic Curve) cryptography.

How It Works

┌──────────┐         ┌──────────┐         ┌──────────┐
│ Frontend │         │  Backend │         │ Supabase │
└────┬─────┘         └────┬─────┘         └────┬─────┘
     │                    │                     │
     │ 1. Login           │                     │
     ├───────────────────────────────────────>  │
     │                    │                     │
     │ 2. JWT Token       │                     │
     │ <──────────────────────────────────────  │
     │                    │                     │
     │ 3. API Request     │                     │
     │    + Bearer Token  │                     │
     ├──────────────────> │                     │
     │                    │                     │
     │                    │ 4. Fetch JWKS       │
     │                    ├──────────────────>  │
     │                    │                     │
     │                    │ 5. Public Keys      │
     │                    │ <──────────────────  │
     │                    │                     │
     │                    │ 6. Validate Token   │
     │                    │    (ES256)          │
     │                    │                     │
     │ 7. Response        │                     │
     │ <──────────────────│                     │
     │                    │                     │

Implementation Details

1. JwtTokenValidator.java

• Fetches JWKS (JSON Web Key Set) from Supabase
• Validates ES256 signatures using public keys
• Extracts user email and ID from claims
• Caches JWKS for performance

2. JwtAuthenticationFilter.java

• Intercepts all HTTP requests
• Extracts JWT from Authorization: Bearer <token> header
• Validates token and sets Spring Security context
• Fetches user role from database

3. SupabaseAuthService.java ⭐ NEW

• Creates users in Supabase Auth via Admin API
• Uses Service Role Key for privileged operations
• Deletes users (rollback on errors)
• Auto-confirms email

Creating New Users

Flow:

1. Admin calls POST /api/users with user data + password
2. Backend calls Supabase Admin API to create auth user
3. Supabase returns auth user ID (UUID)
4. Backend creates public.users record with same UUID
5. User can immediately log in with credentials

Code Example:

@Service
public class UserService {
    
    @Transactional
    public UserDTO createUser(UserDTO userDTO) {
        // 1. Create in Supabase Auth
        String authUserId = supabaseAuthService.createAuthUser(
            userDTO.getEmail(),
            userDTO.getPassword()
        );
        
        // 2. Create in public.users with same ID
        User user = User.builder()
            .id(UUID.fromString(authUserId))  // ← Same ID!
            .email(userDTO.getEmail())
            .role(UserRole.fromString(userDTO.getRole()))
            .build();
        
        return UserDTO.fromEntity(userRepository.save(user));
    }
}

Security Features

• ✅ ES256 Signatures: Asymmetric cryptography (public/private keys)
• ✅ JWKS Validation: Fetch and verify public keys from Supabase
• ✅ Token Expiration: Tokens expire after configured time
• ✅ Role-Based Access: Extract user role from database
• ✅ Spring Security Integration: Automatic authentication context
• ✅ CORS Protection: Only allowed origins can call API

---

📚 API Documentation

Base URL

http://localhost:8080/api

Response Format

Success:

{
  "success": true,
  "data": { ... },
  "error": null,
  "timestamp": "2026-02-09T14:00:00Z"
}

Error:

{
  "success": false,
  "data": null,
  "error": "Error message here",
  "timestamp": "2026-02-09T14:00:00Z"
}

Authentication

All protected endpoints require JWT token:

curl -H "Authorization: Bearer eyJhbGci..." \
  http://localhost:8080/api/users

Endpoints Summary

Resource	Endpoints	Description
Organizations	6	CRUD operations
Users	10	User management, authentication
Jobs	14	Job postings
Candidates	9	Candidate profiles
Applications	20	Kanban pipeline
Scorecards	8	Candidate evaluations ⭐
Activities	6	Audit trail ⭐
Health	4	System monitoring

Total: ~77 REST endpoints

Key Endpoints

Authentication & Users

# Get user by email (after login)
GET /api/users/email/{email}
Authorization: Bearer <token>

# Create new user (admin only)
POST /api/users
{
  "email": "newuser@acme.com",
  "fullName": "New User",
  "role": "USER",
  "organizationId": "uuid",
  "password": "SecurePass123!"
}

# Create admin user
POST /api/users/admin
{
  "email": "newadmin@acme.com",
  "fullName": "New Admin",
  "organizationId": "uuid",
  "password": "AdminPass123!"
}

Candidates

# Get candidates for organization
GET /api/candidates/organization/{orgId}

# Create candidate
POST /api/candidates
{
  "organizationId": "uuid",
  "fullName": "Anna Andersson",
  "email": "anna@example.com",
  "phone": "+46701234567",
  "linkedinUrl": "https://linkedin.com/in/anna",
  "skills": ["React", "TypeScript", "Node.js"],
  "summary": "Senior developer with 5 years experience"
}

Scorecards ⭐

# Create scorecard
POST /api/scorecards
{
  "candidateId": "uuid",
  "technicalSkills": 4,
  "communication": 5,
  "cultureFit": 4,
  "experience": 3,
  "leadership": 4
}

# Get scorecards for candidate
GET /api/scorecards/candidate/{candidateId}

Kanban Pipeline

# Get all applications for organization
GET /api/applications/organization/{orgId}

# Create application (add to pipeline)
POST /api/applications
{
  "candidateId": "uuid",
  "jobId": "uuid",
  "status": "NEW"
}

# Update application status (move in pipeline)
PATCH /api/applications/{id}/status
{
  "status": "INTERVIEW",
  "notes": "Scheduled for technical interview"
}

---

📁 Project Structure

mini-ATS/
├── src/main/java/com/miniats/
│   ├── MiniAtsApplication.java          # Application entry point
│   │
│   ├── config/
│   │   ├── SecurityConfig.java          # Spring Security + JWT
│   │   ├── SupabaseConfig.java          # Supabase client
│   │   ├── WebConfig.java               # CORS configuration
│   │   └── DotenvConfig.java            # Environment variables
│   │
│   ├── security/                        # ⭐ Authentication Layer
│   │   ├── JwtAuthenticationFilter.java # Intercepts requests
│   │   ├── JwtTokenValidator.java       # Validates ES256 tokens
│   │   └── SupabaseUserPrincipal.java   # User identity
│   │
│   ├── controller/                      # REST API Controllers
│   │   ├── BaseController.java          # Common response methods
│   │   ├── UserController.java          # User management
│   │   ├── OrganizationController.java  # Organizations
│   │   ├── JobController.java           # Jobs
│   │   ├── CandidateController.java     # Candidates
│   │   ├── ApplicationController.java   # Pipeline
│   │   ├── ScorecardController.java     # Scorecards ⭐
│   │   └── ActivityController.java      # Activity timeline ⭐
│   │
│   ├── service/                         # Business Logic
│   │   ├── UserService.java
│   │   ├── OrganizationService.java
│   │   ├── JobService.java
│   │   ├── CandidateService.java
│   │   ├── ApplicationService.java
│   │   ├── ScorecardService.java        # ⭐
│   │   ├── ActivityService.java         # ⭐
│   │   └── SupabaseAuthService.java     # ⭐ NEW: User creation
│   │
│   ├── repository/                      # Data Access Layer
│   │   ├── UserRepository.java
│   │   ├── OrganizationRepository.java
│   │   ├── JobRepository.java
│   │   ├── CandidateRepository.java
│   │   ├── ApplicationRepository.java
│   │   ├── ScorecardRepository.java     # ⭐
│   │   ├── ActivityRepository.java      # ⭐
│   │   └── impl/                        # Supabase implementations
│   │       ├── SupabaseUserRepository.java
│   │       ├── SupabaseOrganizationRepository.java
│   │       ├── SupabaseJobRepository.java
│   │       ├── SupabaseCandidateRepository.java
│   │       ├── SupabaseApplicationRepository.java
│   │       ├── SupabaseScorecardRepository.java
│   │       └── SupabaseActivityRepository.java
│   │
│   ├── domain/
│   │   ├── model/                       # Domain Entities (Immutable)
│   │   │   ├── User.java
│   │   │   ├── Organization.java
│   │   │   ├── Job.java
│   │   │   ├── Candidate.java
│   │   │   ├── Application.java
│   │   │   ├── Scorecard.java           # ⭐
│   │   │   └── Activity.java            # ⭐
│   │   └── enums/
│   │       ├── UserRole.java
│   │       ├── JobStatus.java
│   │       ├── ApplicationStatus.java
│   │       └── ActivityType.java        # ⭐
│   │
│   ├── dto/                             # Data Transfer Objects (Records)
│   │   ├── UserDTO.java
│   │   ├── OrganizationDTO.java
│   │   ├── JobDTO.java
│   │   ├── CandidateDTO.java
│   │   ├── ApplicationDTO.java
│   │   ├── ScorecardDTO.java            # ⭐
│   │   └── ActivityDTO.java             # ⭐
│   │
│   └── exception/                       # Error Handling
│       ├── GlobalExceptionHandler.java
│       └── ResourceNotFoundException.java
│
├── src/main/resources/
│   ├── application.yml                  # Spring Boot configuration
│   └── logback-spring.xml              # Logging configuration
│
├── .env                                 # Environment variables (gitignored)
├── .env.example                         # Example environment file
├── pom.xml                              # Maven dependencies
├── README.md                            # This file
└── .gitignore

---

⚙️ Configuration

Environment Variables

Required in .env:

# Supabase
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=your_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key

# Database
DB_URL=jdbc:postgresql://db.your-project.supabase.co:6543/postgres
DB_USERNAME=postgres
DB_PASSWORD=your_password

# JWT
SUPABASE_JWT_JWKS_URL=https://your-project.supabase.co/auth/v1/.well-known/jwks.json
JWT_EXPIRATION=86400000

# CORS (comma-separated)
CORS_ALLOWED_ORIGINS=http://localhost:5173,https://your-frontend.com

# Admin
ADMIN_DEFAULT_EMAIL=admin@acme.com
ADMIN_DEFAULT_PASSWORD=ChangeThisPassword123!

application.yml

Key configurations:

server:
  port: 8080
  servlet:
    context-path: /api

supabase:
  url: ${SUPABASE_URL}
  anon-key: ${SUPABASE_ANON_KEY}
  service-role-key: ${SUPABASE_SERVICE_ROLE_KEY}
  jwt:
    jwks-url: ${SUPABASE_JWT_JWKS_URL}
    expiration: ${JWT_EXPIRATION:86400000}

cors:
  allowed-origins: ${CORS_ALLOWED_ORIGINS}

logging:
  level:
    com.miniats: DEBUG
    org.springframework.security: DEBUG

---

🔒 Security

Authentication Flow

1. User logs in via frontend (Supabase Auth)
2. Frontend receives JWT token (ES256 signed)
3. Frontend sends token in Authorization: Bearer <token> header
4. JwtAuthenticationFilter intercepts request
5. JwtTokenValidator validates token:
   • Fetches JWKS from Supabase
   • Verifies ES256 signature
   • Checks expiration
6. Spring Security sets authentication context
7. Controller processes request with authenticated user

Security Headers

@Configuration
public class SecurityConfig {
    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) {
        http
            .cors(cors -> cors.configurationSource(corsConfigurationSource()))
            .csrf(csrf -> csrf.disable())
            .headers(headers -> headers
                .contentSecurityPolicy("default-src 'self'")
                .xssProtection()
                .frameOptions().deny()
            )
            .addFilterBefore(jwtAuthenticationFilter, 
                UsernamePasswordAuthenticationFilter.class);
    }
}

CORS Configuration

Only allowed origins can access the API:

@Bean
public CorsConfigurationSource corsConfigurationSource() {
    CorsConfiguration configuration = new CorsConfiguration();
    configuration.setAllowedOrigins(Arrays.asList(
        corsAllowedOrigins.split(",")
    ));
    configuration.setAllowedMethods(Arrays.asList(
        "GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"
    ));
    configuration.setAllowCredentials(true);
    return source;
}

Production Checklist

• Use strong JWT secrets
• Enable HTTPS only
• Set secure CORS origins
• Enable rate limiting
• Configure firewall rules
• Set up monitoring/alerts
• Enable database backups
• Implement request logging

---

🚢 Deployment

Build

mvn clean package

Output: target/mini-ats-1.0.0.jar

Run

java -jar target/mini-ats-1.0.0.jar

Deployment Platforms

Railway

1. Push to GitHub
2. Connect Railway to repo
3. Set environment variables
4. Deploy automatically

Heroku

heroku create mini-ats-backend
git push heroku main
heroku config:set SUPABASE_URL=...

AWS Elastic Beanstalk

1. Upload JAR file
2. Configure environment
3. Deploy

Docker (Optional)

FROM eclipse-temurin:17-jre
COPY target/mini-ats-1.0.0.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "/app.jar"]

docker build -t mini-ats .
docker run -p 8080:8080 --env-file .env mini-ats

---

🐛 Troubleshooting

JWT Validation Fails

Problem: 401 Unauthorized errors

Solutions:

1. Check SUPABASE_JWT_JWKS_URL is correct
2. Verify token is not expired
3. Check backend logs for specific error
4. Verify user exists in both auth.users AND public.users

User Creation Fails

Problem: 400 Bad Request when creating users

Solutions:

1. Verify SUPABASE_SERVICE_ROLE_KEY is set
2. Check password meets requirements (min 6 chars)
3. Verify email doesn't already exist
4. Check Supabase dashboard for auth user creation

CORS Errors

Problem: Frontend can't connect

Solutions:

1. Add frontend URL to CORS_ALLOWED_ORIGINS
2. Restart backend after changing CORS
3. Verify format: http://localhost:5173,https://other.com

Database Connection Issues

Problem: Can't connect to Supabase

Solutions:

1. Verify DB_URL, DB_USERNAME, DB_PASSWORD
2. Check Supabase project is running
3. Verify network connectivity
4. Check if using pooler URL (port 6543)

---

📖 Related Documentation

• Frontend README: talentflow-pro/README.md
• Supabase Docs: supabase.com/docs
• Spring Security: spring.io/projects/spring-security

---

🔄 Development Workflow

Git Branches

Main branches:

• main - Production-ready code

Completed features:

• ✅ candidate-detail-view - Scorecards, notes, activity
• ✅ integrate-jwt-auth - Supabase JWT authentication
• ✅ admin-user-creation - User creation via Admin API

Making Changes

# Create feature branch
git checkout -b feature/my-feature

# Make changes and commit
git add .
git commit -m "feat: add my feature"

# Push to GitHub
git push origin feature/my-feature

# Merge when ready
git checkout main
git merge feature/my-feature
git push origin main

---

📊 System Statistics

Code Metrics:

• REST Controllers: 8
• Service Classes: 7
• Repository Implementations: 7
• Domain Entities: 7
• DTOs: 7
• Total Endpoints: ~77
• Lines of Code: ~8,000

Test Coverage: (Add when tests are implemented)

• Unit Tests: TBD
• Integration Tests: TBD
• Coverage: TBD%

---

📄 License

MIT License

---

🙏 Acknowledgments

Built with:

• Spring Boot & Spring Security
• Supabase for authentication & database
• PostgreSQL
• Maven
• Lombok
• Love ❤️ and coffee ☕

---

Questions or issues? Open an issue on GitHub or contact the development team.

---

📝 Changelog

v1.0.0 (2026-02-09)

• ✅ Initial release
• ✅ Supabase JWT authentication (ES256)
• ✅ Multi-tenant architecture
• ✅ Kanban pipeline
• ✅ Candidate scorecards
• ✅ Activity timeline
• ✅ User management with Admin API
• ✅ Complete CRUD operations

Upcoming Features

• Email notifications
• File upload (resumes, cover letters)
• Calendar integration
• Advanced search
• Analytics dashboard
• Export capabilities