Architecture - OpenATS

System Overview

OpenATS is built as a modern monorepo containing two primary applications:

web/ - Next.js frontend application
api/ - Express.js backend API

The architecture follows a traditional client-server model with clear separation of concerns, type-safe database operations, and real-time capabilities.

Tech Stack

Frontend (`web/`)

The frontend is a modern Next.js application built with the latest React features.

Next.js 16

React framework with App Router, server components, and server actions

React 19

Latest React with improved concurrent features and automatic batching

TypeScript

Full type safety across the entire frontend codebase

Tailwind CSS 4

Utility-first CSS framework for rapid UI development

shadcn/ui

High-quality React components built with Radix UI and Tailwind

WSO2 Asgardeo

Enterprise SSO and authentication with @asgardeo/nextjs

Key Frontend Dependencies

package.json

{
  "dependencies": {
    "next": "16.1.6",
    "react": "19.2.3",
    "react-dom": "19.2.3",
    "@asgardeo/nextjs": "^0.1.79",
    "shadcn": "^3.8.4",
    "lucide-react": "^0.575.0",
    "next-themes": "^0.4.6",
    "react-dnd": "^16.0.1",
    "react-dnd-html5-backend": "^16.0.1",
    "recharts": "2.15.4",
    "sonner": "^2.0.7"
  }
}

Frontend Features

Server Components: Optimized page loads with React Server Components
Drag & Drop: Candidate pipeline management with react-dnd
Dark Mode: System-aware theming with next-themes
Charts & Analytics: Hiring metrics visualization with Recharts
Toast Notifications: User feedback with Sonner
Responsive Design: Mobile-first approach with Tailwind breakpoints

Backend (`api/`)

The backend is a TypeScript-based Express application with comprehensive API documentation.

Express.js 5

Fast, unopinionated web framework for Node.js

TypeScript

Type-safe backend with full IDE autocomplete support

Drizzle ORM

Type-safe ORM with automatic TypeScript types from schema

PostgreSQL

Robust relational database with ACID compliance

Socket.io

Real-time bidirectional communication for live updates

Swagger UI

Interactive API documentation at /api-docs

Key Backend Dependencies

package.json

{
  "dependencies": {
    "express": "^5.2.1",
    "drizzle-orm": "^0.45.1",
    "pg": "^8.19.0",
    "socket.io": "^4.8.3",
    "cors": "^2.8.6",
    "dotenv": "^17.2.4",
    "zod": "^4.3.6",
    "@aws-sdk/client-s3": "^3.1000.0",
    "multer": "^2.1.0",
    "resend": "^6.9.3",
    "swagger-ui-express": "^5.0.1"
  },
  "devDependencies": {
    "drizzle-kit": "^0.31.9",
    "nodemon": "^3.1.11",
    "tsx": "^4.21.0"
  }
}

Backend Features

RESTful API: Standard HTTP methods for all resources
Request Validation: Schema validation with Zod
Error Handling: Centralized error middleware in api/src/middlewares/error.middleware.ts:4
File Uploads: Resume handling with Multer and S3-compatible storage
Real-time Events: WebSocket notifications via Socket.io
API Documentation: Auto-generated Swagger docs from OpenAPI spec

Database Schema

OpenATS uses PostgreSQL with Drizzle ORM for type-safe database operations. The schema is defined in TypeScript and located in api/src/db/schema/.

Core Tables

Jobs
Candidates
Assessments
Pipeline

jobs table (api/src/db/schema/jobs.ts)Stores job postings with comprehensive details:

{
  id: serial,
  slug: varchar (unique),
  title: varchar,
  departmentId: integer → departments.id,
  employmentType: enum, // full-time, part-time, contract, internship, temporary
  location: varchar,
  description: text,
  salaryType: enum, // fixed, range
  currency: varchar(3), // ISO 4217
  payFrequency: enum, // hourly, weekly, monthly, yearly
  salaryFixed: numeric,
  salaryMin: numeric,
  salaryMax: numeric,
  status: enum, // draft, published
  createdBy: integer → users.id,
  createdAt: timestamp,
  updatedAt: timestamp
}

Related table: job_skills for required skills per job

candidates table (api/src/db/schema/candidates.ts)Stores candidate applications:

{
  id: serial,
  firstName: varchar,
  lastName: varchar,
  email: varchar,
  phone: varchar,
  resumeUrl: varchar, // Cloudflare R2 URL
  jobId: integer → jobs.id,
  currentStageId: integer → job_pipeline_stages.id,
  appliedAt: timestamp,
  updatedAt: timestamp
}

Related tables:

candidate_stage_history - Track movement through pipeline
candidate_custom_answers - Answers to job-specific questions
candidate_cv_analysis - AI-powered resume analysis with match scores

assessments table (api/src/db/schema/assessments.ts)Custom skills assessments:

{
  id: serial,
  jobId: integer → jobs.id,
  title: varchar,
  description: text,
  duration: integer, // minutes
  passingScore: numeric, // percentage
  isActive: boolean,
  createdAt: timestamp
}

Related tables:

assessment_questions - Questions with types (multiple choice, checkbox, text)
assessment_question_options - Answer options with correct flags and points
candidate_assessment_attempts - Candidate attempt tracking with scores
candidate_assessment_answers - Individual answers per attempt

job_pipeline_stages table (api/src/db/schema/pipeline.ts)Customizable hiring pipeline:

{
  id: serial,
  name: varchar,
  order: integer,
  isDefault: boolean,
  createdAt: timestamp
}

Default stages seeded via api/src/db/seed.ts:

Applied
Screening
Interview
Offer
Hired

Database Migrations

OpenATS uses Drizzle Kit for schema migrations:

Define Schema

Edit TypeScript schema files in api/src/db/schema/

Generate Migration

pnpm drizzle-kit generate

Creates SQL migration files in api/drizzle/

Apply Migration

pnpm drizzle-kit migrate

Executes migrations against your database

Always commit generated migration files along with schema changes. This ensures database consistency across environments.

Authentication Flow

OpenATS uses WSO2 Asgardeo for enterprise-grade authentication:

Authentication Features

OAuth 2.0 / OIDC: Industry-standard authentication protocol
SSO Support: Single sign-on with existing enterprise identity providers
Session Management: Secure session handling with @asgardeo/nextjs
Role-Based Access: User roles and permissions (future enhancement)

File Storage Architecture

Resumes and documents are stored in Cloudflare R2 (S3-compatible storage):

Upload

Client uploads file via multer middleware in Express

Process

Backend validates file type and size

Store

File uploaded to R2 bucket using AWS SDK v3

Save URL

Public R2 URL stored in candidates.resumeUrl field

Access

Frontend retrieves file via public R2 URL

Configuration

.env

R2_ENDPOINT=https://your-account.r2.cloudflarestorage.com
R2_ACCESS_KEY_ID=your_access_key
R2_SECRET_ACCESS_KEY=your_secret_key
R2_BUCKET_NAME=openats-resumes
R2_PUBLIC_URL=https://your-r2-domain.com

Real-time Communication

Socket.io enables real-time features for collaborative hiring:

api/src/server.ts

import http from "http";
import app from "./app";
import { socketService } from "./services/socket.service";

const server = http.createServer(app);
socketService.initialize(server);

server.listen(8080, () => {
  console.log(`OpenATS Backend running on port 8080`);
  console.log(`Socket.io initialized and listening on the same port.`);
});

Real-time Features

Candidate Updates: Live notifications when candidates move through pipeline
Application Alerts: Real-time alerts for new applications
Collaborative Hiring: Multiple recruiters can see live updates
System Events: Broadcast system-wide notifications

Email Infrastructure

OpenATS integrates with Resend for transactional emails:

.env

RESEND_API_KEY=re_your_api_key
RESEND_FROM_EMAIL=noreply@yourdomain.com

Email Use Cases

Assessment invitations with unique tokens
Application confirmations
Interview scheduling
Offer letters
Pipeline status updates

API Architecture

The Express API is organized with clear separation of concerns:

api/src/
├── server.ts          # Entry point, HTTP server setup
├── app.ts             # Express app configuration
├── routes/            # API route definitions
├── controllers/       # Request handlers
├── services/          # Business logic
├── middlewares/       # Express middlewares
├── db/
│   ├── schema/       # Drizzle ORM schemas
│   └── seed.ts       # Database seeding
└── config/           # Configuration files

API Endpoints

All API routes are prefixed with /api (defined in api/src/app.ts:13):

Health Check: GET /health - Server status
API Docs: GET /api-docs - Interactive Swagger UI
Jobs: GET|POST|PUT|DELETE /api/jobs
Candidates: GET|POST|PUT|DELETE /api/candidates
Assessments: GET|POST|PUT|DELETE /api/assessments
Pipeline: GET|POST|PUT|DELETE /api/pipeline

Visit http://localhost:8080/api-docs when running locally to explore the complete API documentation.

Development Workflow

# Terminal 1: Backend
cd api
pnpm dev  # Runs on :8080 with hot reload

# Terminal 2: Frontend  
cd web
pnpm dev  # Runs on :3000 with hot reload

Design Decisions

Why Drizzle ORM?

Drizzle provides the best balance of type safety, performance, and developer experience:

Full TypeScript inference from schema
Zero runtime overhead
SQL-like query builder
Automatic migration generation
No decorators or experimental features

Why Separate Frontend/Backend?

While Next.js could handle both, separating them provides:

Clear API boundaries
Independent scaling
Easier testing
Flexibility to add other clients (mobile apps, CLI)
Simpler deployment strategies

Why PostgreSQL?

PostgreSQL offers:

ACID compliance for data integrity
Rich data types (JSON, arrays)
Powerful indexing and query optimization
Excellent tooling ecosystem
Free and open source

Why WSO2 Asgardeo?

Asgardeo provides enterprise features without complexity:

OAuth 2.0 / OIDC compliance
Social login providers
Multi-factor authentication
Free tier for development
Easy integration with Next.js

Performance Considerations

Database Indexes: Key fields indexed for fast queries (see schema definitions)
Connection Pooling: PostgreSQL connections pooled via pg driver
Incremental Static Regeneration: Next.js ISR for optimized page loads
Code Splitting: Automatic route-based splitting in Next.js
Image Optimization: Next.js Image component for optimized images
WebSocket Efficiency: Socket.io rooms for targeted real-time updates

Security Measures

Input Validation

All API inputs validated with Zod schemas

SQL Injection Protection

Drizzle ORM parameterized queries

CORS Configuration

Configured CORS policies for API access

Environment Variables

Sensitive data in .env files (never committed)

Authentication

OAuth 2.0 via WSO2 Asgardeo

File Upload Limits

Multer validation for file types and sizes

Next Steps

Contributing Guide

Learn how to extend and customize OpenATS

API Reference

Explore detailed API endpoint documentation

Database Schema

Deep dive into the data model

Development Setup

Set up OpenATS for local development

Get Started

Core Features

User Guides

Development

Documentation Index

​System Overview

​Tech Stack

​Frontend (web/)

Next.js 16

React 19

TypeScript

Tailwind CSS 4

shadcn/ui

WSO2 Asgardeo

​Key Frontend Dependencies

​Frontend Features

​Backend (api/)

Express.js 5

TypeScript

Drizzle ORM

PostgreSQL

Socket.io

Swagger UI

​Key Backend Dependencies

​Backend Features

​Database Schema

​Core Tables

​Database Migrations

​Authentication Flow

​Authentication Features

​File Storage Architecture

​Configuration

​Real-time Communication

​Real-time Features

​Email Infrastructure

​Email Use Cases

​API Architecture

​API Endpoints

​Development Workflow

​Design Decisions

​Performance Considerations

​Security Measures

Input Validation

SQL Injection Protection

CORS Configuration

Environment Variables

Authentication

File Upload Limits

​Next Steps

Contributing Guide

API Reference

Database Schema

Development Setup

Build docs developers (and LLMs) love

System Overview

Tech Stack

Frontend (`web/`)

Key Frontend Dependencies

Frontend Features

Backend (`api/`)

Key Backend Dependencies

Backend Features

Database Schema

Core Tables

Database Migrations

Authentication Flow

Authentication Features

File Storage Architecture

Configuration

Real-time Communication

Real-time Features

Email Infrastructure

Email Use Cases

API Architecture

API Endpoints

Development Workflow

Design Decisions

Performance Considerations

Security Measures

Next Steps