Recruitment App

📌 Requirements Summary & BA Implementation Guide

Requirements Summary (What the business needs)

  • Purpose: End-to-end recruitment management from job posting to offer and hire, with auditable workflow and strict role-based access.

  • Actors/Roles: Manager/TeamLead, HR/RecruitmentManager, Employee (referrals), Interviewer, Finance, Admin, Vendor (external agencies, no login rights), Contractor (future).

  • Core Entities: JobPosting, Candidate, EmployeeReferral, VendorReferral, Vendor, Application, Interview, Offer, Employee (result of successful hire), OrgAccount, UserAccount, AccountabilityMatrix.

  • Key Workflows:

    • JobPosting: Draft → Published → Closed → Archived

    • Candidate: Created → UnderReview → Shortlisted → InterviewScheduled → InterviewCompleted → Selected → OfferSent → Hired

    • EmployeeReferral: Submitted → UnderReview → Approved/Rejected → ConvertedToApplication

    • VendorReferral: Submitted → Approved/Rejected → ConvertedToApplication

    • Application: Created → Screened → InterviewScheduled → InterviewCompleted → OfferMade → Rejected

    • Interview: Scheduled → Completed/Cancelled

    • Offer: Created → Approved → Accepted/Rejected/Withdrawn

  • Access Control: Each transition is role-gated (e.g., HR can close published postings; Interviewer can complete only assigned interviews; Candidate accepts/ rejects offers).

  • Approvals: Multi-level approvals for job postings and offers (HR → Manager → Director/VP → CEO/Finance as applicable) with timeouts and escalation.

  • Organizational Hierarchy: OrgAccount and UserAccount structure for managing organizational relationships and accountability matrix.

  • Integrations/Future: Background checks, email/notifications, contractor imports; all designed for later enablement.

  • Reporting & Audit: Full audit trail of state transitions, approvals, and key events; metrics on pipeline throughput.

  • Non-Functional: Security, configurability (dynamic workflow rules), scalability, and maintainability.

  • Out of Scope (current): Public candidate self-service portal; full contractor module execution.

🎯 Application Overview

This document demonstrates how to implement a comprehensive employee recruitment application using the Flexbase framework, featuring domain models, workflow states, multi-level approval processes, and enterprise-grade role-based access control.


📋 Business Requirements

Core Entities:

  • Job Posting - Open positions with requirements

  • Candidate - Potential candidates managed by HR/Recruiters

  • Employee Referral - Employee referrals for candidates

  • Vendor Referral - External vendor/agency referrals for candidates

  • Vendor - External vendors/agencies that can refer candidates

  • Application - Candidate's application for a position (created by HR/Recruiter)

  • Interview - Interview sessions and feedback

  • Offer - Job offers and negotiations

  • Employee - Successfully hired candidates

  • OrgAccount - Organizational accounts for hierarchy management

  • UserAccount - User accounts for personal information management

  • AccountabilityMatrix - Responsibility relationships between entities

  • Contractor - External contractors for recruitment (future)

Workflow Requirements:

  • Multi-level Approval - HR → Manager → Director → CEO

  • Interview Process - Phone → Technical → Final → HR

  • Background Check - Reference verification

  • Offer Management - Salary negotiation and approval

  • Onboarding - New employee setup

Role-Based Access Control:

  • Manager/TeamLead - Create and manage job postings

  • HR/RecruitmentManager - Approve postings, manage candidates, create applications, manage vendor referrals

  • Employee - Submit referrals for candidates

  • Interviewer - Conduct interviews, provide feedback

  • Finance - Approve salary offers

  • Vendor - External vendors/agencies (no login rights; managed by HR)

  • Contractor - External recruitment services (future)

  • Admin - Full system access


🏗️ Application Modules and Features Mapping

Module Structure Overview

The recruitment application is organized into 8 core modules, each containing multiple features (controllers) that map to specific domain objects and actions.

Module
Features (Controllers)
Domain Objects
Primary Actions

JobPostings

JobPostingsController

JobPosting

Create, Update, Publish, Close, Archive

Candidates

CandidatesController

Candidate

Create, Update, Search, View, Manage

EmployeeReferrals

EmployeeReferralsController

EmployeeReferral

Submit, Update, View, Approve

Vendors

VendorsController

Vendor

GetVendorsForLookup (HR-managed)

VendorReferrals

VendorReferralsController

VendorReferral

Submit, Update, View, Approve (via features)

Applications

ApplicationsController

Application

Create, Screen, ScheduleInterview, Reject

Interviews

InterviewsController

Interview

Schedule, Complete, Reschedule, Cancel

Offers

OffersController

Offer

Create, Approve, Accept, Reject, Withdraw


📋 Detailed Module and Feature Mapping

1. JobPostings Module

JobPostingsController Features:

  • CreateJobPosting (POST) → JobPosting.CreateJobPosting()

  • UpdateJobPosting (PUT) → JobPosting.UpdateJobPosting()

  • PublishJobPosting (POST) → JobPosting.PublishJobPosting()

  • CloseJobPosting (POST) → JobPosting.CloseJobPosting()

  • ArchiveJobPosting (POST) → JobPosting.ArchiveJobPosting()

  • GetJobPosting (GET) → JobPosting (Read-only)

  • GetJobPostings (GET) → JobPosting (List with filtering)

  • GetJobPostingsByDepartment (GET) → JobPosting (Filtered by department)

  • GetJobPostingsByStatus (GET) → JobPosting (Filtered by status)

Domain Object: JobPosting

  • State Machine: JobPostingWorkflowState

  • States: Draft → Published → Closed → Archived

  • Role-Based Actions:

    • Manager/TeamLead: Create, Update, Publish, Close (Draft state)

    • HR/RecruitmentManager: Publish, Close, Archive (Published state)

    • Admin: All actions across all states


2. Candidates Module

CandidatesController Features:

  • CreateCandidate (POST) → Candidate.CreateCandidate()

  • UpdateCandidateProfile (PUT) → Candidate.UpdateProfile()

  • GetCandidate (GET) → Candidate (Read-only)

  • GetCandidates (GET) → Candidate (List with filtering)

  • SearchCandidates (GET) → Candidate (Search by skills, experience)

  • GetCandidateApplications (GET) → Candidate.Applications (Related data)

  • UploadResume (POST) → Candidate (File upload)

  • DeleteCandidate (DELETE) → Candidate (Soft delete)

  • ImportCandidates (POST) → Candidate (Bulk import from contractors)

Domain Object: Candidate

  • State Machine: CandidateManagementState

  • States: Created → UnderReview → Shortlisted → InterviewScheduled → InterviewCompleted → Selected → OfferSent → Hired

  • Integration with Vendor Referrals:

    • Candidates can be created with vendor referral information in a single operation

    • HR users can select a vendor and job posting during candidate creation

    • Vendor referral is automatically created and linked to the candidate

  • Role-Based Actions:

    • HR/RecruitmentManager: All candidate management operations, create vendor referrals during candidate creation

    • Employee: View candidates for referral purposes

    • Interviewer: View candidate profiles for assigned interviews

    • Manager: View candidates for their job postings

    • Contractor: Submit candidate profiles (future)


3. Vendors Module

VendorsController Features:

  • GetVendorsForLookup (GET) → Vendor (Lookup for autocomplete/dropdowns)

Domain Object: Vendor

  • Purpose: Represents external vendors/agencies that can refer candidates

  • Key Relationships:

    • OrgAccount (required) - One OrgAccount per Vendor (vendor organization)

    • VendorReferrals - Collection of referrals made by this vendor

  • Key Properties:

    • OrgAccountId - Foreign key to OrgAccount (vendor name comes from OrgAccount.Name)

    • ContactPersonName - Primary contact person

    • ContactEmail - Primary contact email

    • ContactPhone - Primary contact phone

    • DefaultCommissionPercentage - Default commission rate

    • Status - Vendor status

    • Notes - Additional notes

  • Access Control:

    • HR/RecruitmentManager: View vendors, select vendors for candidate creation

    • Vendors: No login rights; vendors are managed by HR in the candidate creation flow

  • Integration:

    • Vendors are selected by HR users during candidate creation

    • Vendor referrals are created alongside candidates in a single operation

    • Vendor name is displayed from the associated OrgAccount


4. Vendor Referrals Module

VendorReferralsController Features:

  • Note: Business actions (Submit, Approve, Reject, Update) will be created through features and modules later

  • Current Implementation: VendorReferral creation is integrated into Candidate creation flow

Domain Object: VendorReferral

  • Purpose: Represents a candidate referral from an external vendor/agency

  • State Machine: VendorReferralWorkflowState

  • States: Submitted → Approved → Rejected → ConvertedToApplication

  • Key Relationships:

    • Vendor (required) - The vendor making the referral

    • Candidate (required) - The candidate being referred

    • JobPosting (required) - The job posting for this referral

    • Applications - Applications created from this referral

  • Key Properties:

    • VendorId - Foreign key to Vendor

    • CandidateId - Foreign key to Candidate

    • JobPostingId - Foreign key to JobPosting

    • ReferralReason - Reason for referral

    • AdditionalNotes - Additional notes

    • CommissionAmount - Commission amount (vendor-specific)

    • CommissionPercentage - Commission percentage

    • CommissionPaidDate - Date commission was paid

    • Status - Referral status

    • ApprovedBy, ApprovedDate - Approval tracking

    • RejectedBy, RejectedDate, RejectionReason - Rejection tracking

  • Integration with Candidate Creation:

    • Vendor referrals can be created alongside candidates in a single operation

    • HR users select vendor and job posting during candidate creation

    • Vendor referral information is captured in CreateCandidateVendorReferralDto

    • The referral is automatically linked to the candidate using SetCandidateId() and SetVendorId() methods

  • Role-Based Actions:

    • HR/RecruitmentManager: Create vendor referrals during candidate creation, approve/reject referrals (via features)

    • Vendors: No direct access; referrals are created by HR on behalf of vendors


5. Employee Referrals Module

EmployeeReferralsController Features:

  • SubmitReferral (POST) → EmployeeReferral.SubmitReferral()

  • UpdateReferral (PUT) → EmployeeReferral.UpdateReferral()

  • GetReferral (GET) → EmployeeReferral (Read-only)

  • GetReferrals (GET) → EmployeeReferral (List with filtering)

  • GetReferralsByEmployee (GET) → EmployeeReferral (Filtered by employee)

  • ApproveReferral (POST) → EmployeeReferral.ApproveReferral()

  • RejectReferral (POST) → EmployeeReferral.RejectReferral()

  • GetReferralStatus (GET) → EmployeeReferral (Status tracking)

Domain Object: EmployeeReferral

  • State Machine: EmployeeReferralState

  • States: Submitted → UnderReview → Approved → Rejected → ConvertedToApplication

  • Role-Based Actions:

    • Employee: Submit, Update, View own referrals

    • HR/RecruitmentManager: Review, Approve, Reject, Convert to application

    • Manager: View referrals for their department

    • Admin: All referral management operations


6. Applications Module

ApplicationsController Features:

  • CreateApplication (POST) → Application.CreateApplication()

  • ScreenApplication (POST) → Application.ScreenApplication()

  • ScheduleInterview (POST) → Application.ScheduleInterview()

  • CompleteInterview (POST) → Application.CompleteInterview()

  • MakeOffer (POST) → Application.MakeOffer()

  • RejectApplication (POST) → Application.RejectApplication()

  • GetApplication (GET) → Application (Read-only)

  • GetApplications (GET) → Application (List with filtering)

  • GetApplicationsByJobPosting (GET) → Application (Filtered by job posting)

  • GetApplicationsByCandidate (GET) → Application (Filtered by candidate)

  • GetApplicationsByStatus (GET) → Application (Filtered by status)

  • ConvertFromReferral (POST) → Application.ConvertFromReferral()

Domain Object: Application

  • State Machine: ApplicationWorkflowState

  • States: Created → Screened → InterviewScheduled → InterviewCompleted → OfferMade → Rejected

  • Role-Based Actions:

    • HR/RecruitmentManager: Create, Screen, ScheduleInterview, MakeOffer, Reject, Convert from referral

    • Interviewer: CompleteInterview (for assigned interviews)

    • Manager: View applications for their job postings

    • Employee: View applications created from their referrals


7. Interviews Module

InterviewsController Features:

  • ScheduleInterview (POST) → Interview.ScheduleInterview()

  • CompleteInterview (POST) → Interview.CompleteInterview()

  • RescheduleInterview (POST) → Interview.RescheduleInterview()

  • CancelInterview (POST) → Interview.CancelInterview()

  • SubmitFeedback (POST) → Interview.SubmitFeedback()

  • GetInterview (GET) → Interview (Read-only)

  • GetInterviews (GET) → Interview (List with filtering)

  • GetInterviewsByApplication (GET) → Interview (Filtered by application)

  • GetInterviewsByInterviewer (GET) → Interview (Filtered by interviewer)

  • GetUpcomingInterviews (GET) → Interview (Filtered by date)

  • GetInterviewHistory (GET) → Interview (Historical data)

Domain Object: Interview

  • State Machine: InterviewWorkflowState

  • States: Scheduled → Completed → Cancelled

  • Role-Based Actions:

    • HR/RecruitmentManager: Schedule, Reschedule, Cancel, View all

    • Interviewer: Complete, SubmitFeedback (only for assigned interviews)

    • Manager: View interviews for their job postings

    • Candidate: View own interviews


8. Offers Module

OffersController Features:

  • CreateOffer (POST) → Offer.CreateOffer()

  • ApproveOffer (POST) → Offer.ApproveOffer()

  • AcceptOffer (POST) → Offer.AcceptOffer()

  • RejectOffer (POST) → Offer.RejectOffer()

  • WithdrawOffer (POST) → Offer.WithdrawOffer()

  • UpdateOffer (PUT) → Offer.UpdateOffer()

  • GetOffer (GET) → Offer (Read-only)

  • GetOffers (GET) → Offer (List with filtering)

  • GetOffersByApplication (GET) → Offer (Filtered by application)

  • GetOffersByStatus (GET) → Offer (Filtered by status)

  • GetPendingOffers (GET) → Offer (Filtered by pending status)

Domain Object: Offer

  • State Machine: OfferWorkflowState

  • States: Created → Approved → Accepted/Rejected/Withdrawn

  • Role-Based Actions:

    • HR/RecruitmentManager: Create, Approve, Withdraw, View all

    • Finance: Approve (for salary validation)

    • Admin: All actions across all states

    • Candidate: Accept, Reject (only for approved offers)


🔄 Complete Action-to-Domain Mapping

JobPostings Module Actions:

Action
HTTP Method
Controller Method
Domain Method
State Transition
Required Role

Create Job Posting

POST

CreateJobPosting

JobPosting.CreateJobPosting()

→ Draft

Manager, TeamLead

Update Job Posting

PUT

UpdateJobPosting

JobPosting.UpdateJobPosting()

Draft → Draft

Manager, TeamLead

Publish Job Posting

POST

PublishJobPosting

JobPosting.PublishJobPosting()

Draft → Published

Manager, TeamLead, HR

Close Job Posting

POST

CloseJobPosting

JobPosting.CloseJobPosting()

Published → Closed

HR, Admin, RecruitmentManager

Archive Job Posting

POST

ArchiveJobPosting

JobPosting.ArchiveJobPosting()

Closed → Archived

HR, Admin, RecruitmentManager

Get Job Posting

GET

GetJobPosting

-

-

All (with restrictions)

List Job Postings

GET

GetJobPostings

-

-

All (with restrictions)

Candidates Module Actions:

Action
HTTP Method
Controller Method
Domain Method
State Transition
Required Role

Create Candidate

POST

CreateCandidate

Candidate.CreateCandidate()

→ Created

HR, RecruitmentManager

Update Profile

PUT

UpdateCandidateProfile

Candidate.UpdateProfile()

Created → Created

HR, RecruitmentManager

Get Candidate

GET

GetCandidate

-

-

All (with restrictions)

Search Candidates

GET

SearchCandidates

-

-

HR, RecruitmentManager, Employee

Upload Resume

POST

UploadResume

Candidate.UploadResume()

-

HR, RecruitmentManager

Delete Candidate

DELETE

DeleteCandidate

Candidate.DeleteCandidate()

Created → Deleted

HR, Admin

Import Candidates

POST

ImportCandidates

Candidate.ImportCandidates()

-

HR, RecruitmentManager, Contractor

Employee Referrals Module Actions:

Action
HTTP Method
Controller Method
Domain Method
State Transition
Required Role

Submit Referral

POST

SubmitReferral

EmployeeReferral.SubmitReferral()

→ Submitted

Employee

Update Referral

PUT

UpdateReferral

EmployeeReferral.UpdateReferral()

Submitted → Submitted

Employee

Approve Referral

POST

ApproveReferral

EmployeeReferral.ApproveReferral()

Submitted → Approved

HR, RecruitmentManager

Reject Referral

POST

RejectReferral

EmployeeReferral.RejectReferral()

Submitted → Rejected

HR, RecruitmentManager

Get Referral

GET

GetReferral

-

-

All (with restrictions)

List Referrals

GET

GetReferrals

-

-

HR, RecruitmentManager, Employee

Vendors Module Actions:

Action
HTTP Method
Controller Method
Domain Method
State Transition
Required Role

Get Vendors For Lookup

GET

GetVendorsForLookup

-

-

HR, RecruitmentManager

Vendor Referrals Module Actions:

Action
HTTP Method
Controller Method
Domain Method
State Transition
Required Role

Create Vendor Referral (via Candidate)

POST

CreateCandidate

Candidate.CreateCandidate()

-

HR, RecruitmentManager

Note: Business actions (Submit, Approve, Reject, Update) will be created through features and modules later

Applications Module Actions:

Action
HTTP Method
Controller Method
Domain Method
State Transition
Required Role

Create Application

POST

CreateApplication

Application.CreateApplication()

→ Created

HR, RecruitmentManager

Convert from Referral

POST

ConvertFromReferral

Application.ConvertFromReferral()

→ Created

HR, RecruitmentManager

Screen Application

POST

ScreenApplication

Application.ScreenApplication()

Created → Screened/Rejected

HR, RecruitmentManager

Schedule Interview

POST

ScheduleInterview

Application.ScheduleInterview()

Screened → InterviewScheduled

HR, RecruitmentManager

Complete Interview

POST

CompleteInterview

Application.CompleteInterview()

InterviewScheduled → InterviewCompleted

Interviewer (assigned)

Make Offer

POST

MakeOffer

Application.MakeOffer()

InterviewCompleted → OfferMade

HR, RecruitmentManager

Reject Application

POST

RejectApplication

Application.RejectApplication()

Any → Rejected

HR, RecruitmentManager

Get Application

GET

GetApplication

-

-

All (with restrictions)

List Applications

GET

GetApplications

-

-

HR, RecruitmentManager, Employee

Interviews Module Actions:

Action
HTTP Method
Controller Method
Domain Method
State Transition
Required Role

Schedule Interview

POST

ScheduleInterview

Interview.ScheduleInterview()

→ Scheduled

HR, RecruitmentManager

Complete Interview

POST

CompleteInterview

Interview.CompleteInterview()

Scheduled → Completed

Interviewer (assigned)

Reschedule Interview

POST

RescheduleInterview

Interview.RescheduleInterview()

Scheduled → Scheduled

HR, Interviewer

Cancel Interview

POST

CancelInterview

Interview.CancelInterview()

Scheduled → Cancelled

HR, Interviewer

Submit Feedback

POST

SubmitFeedback

Interview.SubmitFeedback()

Completed → Completed

Interviewer (assigned)

Get Interview

GET

GetInterview

-

-

All (with restrictions)

List Interviews

GET

GetInterviews

-

-

HR, RecruitmentManager

Offers Module Actions:

Action
HTTP Method
Controller Method
Domain Method
State Transition
Required Role

Create Offer

POST

CreateOffer

Offer.CreateOffer()

→ Created

HR, RecruitmentManager

Approve Offer

POST

ApproveOffer

Offer.ApproveOffer()

Created → Approved

HR, Finance, Admin

Accept Offer

POST

AcceptOffer

Offer.AcceptOffer()

Approved → Accepted

Candidate

Reject Offer

POST

RejectOffer

Offer.RejectOffer()

Approved → Rejected

Candidate

Withdraw Offer

POST

WithdrawOffer

Offer.WithdrawOffer()

Created/Approved → Withdrawn

HR, RecruitmentManager

Update Offer

PUT

UpdateOffer

Offer.UpdateOffer()

Created → Created

HR, RecruitmentManager

Get Offer

GET

GetOffer

-

-

All (with restrictions)

List Offers

GET

GetOffers

-

-

HR, RecruitmentManager


🎯 State Machine Integration

Complete State Flow with Actions:


🏗️ Domain Models

1. Job Posting Domain Model

2. Candidate Domain Model

3. Employee Referral Domain Model

4. Application Domain Model

4. Interview Domain Model

5. Offer Domain Model


🔄 Enhanced Workflow State Machines with Role-Based Access Control

1. Job Posting Workflow States with Role Validation

2. Employee Referral Workflow States with Role Validation

3. Application Workflow States with Role Validation

4. Interview Workflow States with Role Validation

5. Offer Workflow States with Role Validation


🔄 Dynamic Workflow Configuration

1. Workflow Configuration System

2. Enhanced State Machine with Workflow Engine

3. Configure Job Posting Workflow

4. Enhanced Domain Methods with Workflow Engine


🔐 Approval Process Implementation

1. Approval Configuration


🧪 Testing the Role-Based System


🎯 Key Benefits of This Enhanced Design

1. Complete Recruitment Workflow

  • End-to-End Process: From job posting to employee onboarding

  • Multi-Level Approval: HR → Manager → Director → CEO

  • State Management: Clear workflow states for each entity

  • Audit Trail: Complete tracking of all actions and approvals

2. Enterprise-Grade Security

  • Role-Based Access Control: Fine-grained permissions for each state transition

  • Dynamic Workflow Configuration: Workflow rules can be changed without code changes

  • Conditional Transitions: Business rules drive automatic state changes

  • Interviewer Isolation: Interviewers can only access their assigned interviews

  • Organizational Hierarchy: OrgAccount and UserAccount structure for managing organizational relationships

  • Accountability Matrix: Responsibility relationships between entities for audit and compliance

3. Flexbase Framework Integration

  • Auto-Generated APIs: REST endpoints for all operations

  • Database Management: Automatic migrations and schema updates

  • Message Bus: Event-driven communication between services

  • Security: Built-in authentication and authorization

4. Scalable Architecture

  • Modular Design: Each domain model is independent

  • Workflow Engine: Configurable approval processes

  • Role-Based Access: Fine-grained permissions

  • Event-Driven: Loose coupling between components

5. Business Value

  • Faster Development: 60-70% reduction in development time

  • Consistent Quality: Framework-enforced patterns

  • Easy Maintenance: Clear separation of concerns

  • Future-Proof: Easy to extend and modify


🚀 Implementation Summary

This enhanced recruitment application design demonstrates how the Flexbase framework can be used to create a comprehensive, enterprise-grade recruitment system with:

  • 8 Core Modules: JobPostings, Candidates, EmployeeReferrals, Vendors, VendorReferrals, Applications, Interviews, Offers

  • 12 Domain Models: JobPosting, Candidate, EmployeeReferral, VendorReferral, Vendor, Application, Interview, Offer, Employee, OrgAccount, UserAccount, AccountabilityMatrix

  • 6 Enhanced Workflow State Machines: Complete state management with role-based access control (JobPosting, EmployeeReferral, VendorReferral, Application, Interview, Offer)

  • Employee Referral System: Internal employee referrals with approval workflow

  • Vendor Referral System: External vendor/agency referrals managed by HR with commission tracking

  • Organizational Hierarchy: OrgAccount and UserAccount structure for managing organizational relationships and accountability matrix

  • HR-Managed Candidate Pipeline: Candidates managed by HR/Recruiters, not self-service

  • Vendor Integration: Vendors selected by HR during candidate creation; no vendor login required

  • Multi-Level Approval Process: Configurable approval workflows

  • Role-Based Security: Fine-grained access control for each state transition

  • Dynamic Workflow Configuration: Workflow rules defined in configuration, not code

  • Event-Driven Architecture: Loose coupling and scalability

  • Complete Audit Trail: Full tracking of all operations

  • Future Contractor Integration: Ready for external contractor candidate submissions

The framework handles all the infrastructure complexity while developers focus on business logic and workflow design, resulting in a robust, maintainable, and scalable recruitment application with enterprise-grade security and role-based access control.


This enhanced design showcases the power of the Flexbase framework in creating complex, workflow-driven applications with minimal development effort while maintaining enterprise-grade quality, consistency, and security.

Last updated