Full-stack talent management system demonstrating Spec-Driven Development and responsible AI integration for enterprise-grade applications.
AIRails is a comprehensive talent management platform built with Ruby on Rails 8 and React 18, showcasing:
- ✅ Spec-Driven Development (SDD): All features start with clear, comprehensive specifications
- ✅ AI-Assisted Development: Strategic use of AI for rapid, quality development
- ✅ Enterprise-Grade Architecture: Clean code, design patterns, comprehensive testing
- ✅ Responsible AI Integration: Ethical AI usage with guardrails and audit trails
- Backend: Rails 8 API with Service Objects, Adapter Pattern, and comprehensive RSpec tests
- Frontend: React 18 with TypeScript, Chakra UI v3, TanStack Query, and Vitest tests
- AI Integration: OpenAI adapter with versioned prompts, validation, and audit logging
- Background Jobs: Sidekiq for async processing (candidate report generation)
- Advanced Features: Candidate filtering, pagination, AI-powered scoring, interview management
┌─────────────────────────────────────────────────────────────┐
│ Frontend (React + TypeScript) │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Pipeline │ │ Candidates │ │ Job Generator│ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │ │ │ │
│ └──────────────────┼──────────────────┘ │
│ │ │
└────────────────────────────┼───────────────────────────────┘
│ REST API
┌────────────────────────────┼───────────────────────────────┐
│ Backend (Rails 8 API) │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Controllers │→ │ Services │→ │ Models │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │ │ │ │
│ └──────────────────┼──────────────────┘ │
│ │ │
│ ┌──────────────┐ │ ┌──────────────┐ │
│ │ AI Adapters │──────────┼─────────→│ PostgreSQL │ │
│ └──────────────┘ │ └──────────────┘ │
│ │ │
│ ┌──────────────┐ │ ┌──────────────┐ │
│ │ Sidekiq │←─────────┼──────────│ Redis │ │
│ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────┘
This project follows a Spec-Driven Development (SDD) methodology:
- 📝 Specifications First (
ai-specs/specs/): Technical specs, API contracts, data models - 📋 Implementation Plans (
ai-specs/changes/): Detailed step-by-step implementation guides - 💻 Code Implementation: Following specifications and standards
- 📚 Documentation: Always updated with code changes
┌─────────────────┐
│ Jira Ticket │
└────────┬────────┘
│
▼
┌─────────────────┐
│ Plan Document │ ← Detailed implementation plan
│ (SCRUM-X.md) │
└────────┬────────┘
│
▼
┌─────────────────┐
│ Implementation │ ← Code following plan
│ (Backend/FE) │
└────────┬────────┘
│
▼
┌─────────────────┐
│ Tests + Docs │ ← Quality assurance
└─────────────────┘
See Spec-Driven Development Guide for details.
AI is used as a development accelerator, not a replacement for engineering judgment.
- Code Generation: Initial structure and boilerplate
- Documentation: Technical docs from specifications
- Test Generation: Test cases from requirements
- Code Review: AI-assisted review suggestions
- ✅ All AI-generated code is reviewed by developer
- ✅ All code is tested (unit, integration)
- ✅ All code follows project standards
- ✅ All changes are documented
- Implementation plans document AI usage
- Code comments explain AI-generated logic
- Audit logs maintained for AI interactions
See AI Usage Documentation for details.
- Ruby 3.3+
- Node.js 20+
- PostgreSQL 15
- Redis 7
cd backend
# Install dependencies
bundle install
# Setup database
cp env.example .env
# Edit .env with your database credentials
# Create and migrate database
rails db:create db:migrate
# Load demo data
rails db:seed
# or
bin/demo:seed
# Start server
rails serverBackend runs on http://localhost:3000
cd frontend
# Install dependencies
npm install
# Setup environment
cp env.example .env
# Edit .env with API URL
# Start dev server
npm run devFrontend runs on http://localhost:5173
# Start PostgreSQL and Redis
docker-compose up -d
# Then follow backend/frontend setup above- Backend Architecture: Rails API structure, services, models
- Frontend Architecture: React app structure, components, hooks
- Spec-Driven Development: SDD process and workflow
- Demo Functionalities: Feature overview
- Project Configuration: Tech stack and standards
- AI Usage: AI integration strategy
- Ruby on Rails 8 (API mode)
- PostgreSQL 15 (database)
- Redis 7 (caching, Sidekiq)
- Sidekiq (background jobs)
- Blueprinter (JSON serialization)
- RSpec (testing)
- FactoryBot (test data)
- React 18.3 with TypeScript 5.9
- Vite 5 (build tool)
- Chakra UI v3 (component library)
- TanStack Query (data fetching)
- React Router DOM 6 (routing)
- Zustand (state management)
- Vitest (testing)
- React Testing Library (component testing)
- ✅ Advanced filtering (education, experience, skills, recent applications)
- ✅ Search by name/email
- ✅ Pagination and sorting
- ✅ Candidate detail views
- ✅ Process reports with background job generation
- ✅ Position CRUD operations
- ✅ Interview flow configuration
- ✅ Candidate pipeline visualization
- ✅ Application tracking
- ✅ AI-powered candidate scoring
- ✅ Job description generation (planned)
- ✅ Executive summaries (planned)
- ✅ Sidekiq integration
- ✅ Async report generation
- ✅ Sidekiq Web UI for monitoring
- RSpec for unit and integration tests
- FactoryBot for test data
- Coverage: [X]% (run
bundle exec rspecto see)
- Vitest for unit tests
- React Testing Library for component tests
- Coverage: [X]% (run
npm testto see)
AIRails/
├── ai-specs/ # Spec-Driven Development
│ ├── specs/ # Technical specifications
│ └── changes/ # Implementation plans
├── backend/ # Rails API
│ ├── app/
│ │ ├── controllers/ # API controllers
│ │ ├── models/ # ActiveRecord models
│ │ ├── services/ # Service objects
│ │ ├── adapters/ # AI adapters
│ │ └── serializers/ # Blueprinter serializers
│ └── spec/ # RSpec tests
├── frontend/ # React app
│ ├── src/
│ │ ├── features/ # Feature modules
│ │ ├── components/ # Reusable components
│ │ ├── services/ # API services
│ │ └── stores/ # Zustand stores
│ └── src/tests/ # Vitest tests
└── documentation/ # Project documentation
- Service Objects: Business logic encapsulation
- Adapter Pattern: AI provider abstraction
- Repository Pattern: Data access abstraction (via ActiveRecord)
- Serializers: Consistent JSON responses
- Background Jobs: Async processing with Sidekiq
- Feature-Based Structure: Organized by features
- Custom Hooks: Reusable logic
- Service Layer: API communication abstraction
- State Management: TanStack Query (server) + Zustand (client)
- ✅ Input validation on all endpoints
- ✅ SQL injection prevention (ActiveRecord)
- ✅ CORS configuration
- ✅ Environment variables for secrets
- ✅ Rate limiting (AI endpoints)
- ✅ Audit logging (AI interactions)
MIT License - See LICENSE file for details
Vanessa Díaz
- GitHub: https://github.com/vd14z
- LinkedIn: https://www.linkedin.com/in/vane-diaz/
- Built with Ruby on Rails
- UI components from Chakra UI
- Icons from React Icons
⭐ If you find this project interesting, please give it a star!