A recruitment system can quickly become a complex application. It must manage forms, job profiles, applications, documents, selection criteria, and personal data while allowing recruiters to compare candidates.
However, these features do not necessarily require a relational database, an application framework, or a SaaS platform.
The recruitment system developed by Palks Studio relies on a self-hosted architecture built with PHP 8.x, vanilla JavaScript, and JSON storage. Its deterministic scoring engine evaluates candidate responses against criteria configured by the recruiter, without artificial intelligence or automated resume analysis.
The technical interest of this architecture lies in the separation between campaign configuration, application processing, score calculation, and data management.
1. General Architecture
The system is divided into two distinct areas:
- A public layer containing interfaces and HTTP endpoints
- A private layer containing configurations, the scoring engine, and candidate data
This separation makes the application form publicly accessible without exposing configuration files, uploaded documents, or personal data.
The documented project structure is as follows:
candidate-system/
β
βββ public/
β βββ panel.php
β βββ record.php
β βββ finalize.php
β βββ success.php
β βββ overview.php
β βββ file.php
β βββ extract.php
β βββ form.php
β βββ campaign.php
β βββ process.php
β
βββ core/
βββ settings/
β βββ init.php
β βββ profile.php
β
βββ presets/
β βββ fields.json
β βββ template.php
β
βββ storage/
β βββ batch_1/
β βββ settings/
β β βββ fields.json
β β βββ template.php
β β
β βββ records/
β βββ entries/
β βββ files/
β βββ archives/
β βββ logs/
β βββ closed.lock
β
βββ engine.php
βββ notify.php
βββ LICENCE.md
βββ docs/
The public/ directory contains the candidate application form, recruiter dashboard, administration interfaces, and processing endpoints.
The core/ directory contains internal components, configuration templates, campaigns, and persistent data.
Production files and private data are not exposed in the public documentation.
2. The Application Processing Lifecycle
The general workflow relies on a relatively short processing pipeline.
Candidate application form
β
βΌ
process.php
β
βββ Campaign status verification
βββ Response validation
βββ Conditional field validation
βββ Duplicate detection
βββ Document validation
β
βΌ
engine.php
β
βββ Question score calculation
βββ Section aggregation
βββ Weight application
βββ Penalty application
β
βΌ
JSON + file storage
β
βββ Confirmation email
β
βΌ
Recruiter dashboard
The form collects structured responses. The backend validates the submitted information and passes the responses to the scoring engine.
The result is stored alongside the application, allowing the dashboard to display scores without systematically recalculating every application.
Business logic remains independent of the presentation layer.
3. The Three-Level Scoring Engine
The scoring engine is the core of the system.
It does not attempt to interpret a resume or predict a candidate's future performance. Instead, it calculates a matching score from structured responses and rules defined in the campaign configuration.
The calculation relies on three levels of weighting.
| Level | Parameter | Role |
|---|---|---|
| Section | global_weight |
Importance of the section in the final score |
| Question | weight |
Importance of the question within its section |
| Answer | scores |
Value assigned to each possible answer |
The contribution of an answer to the final score is calculated using the following formula:
contribution = scores[answer]
Γ (weight / 100)
Γ (global_weight / 100)
The default weight distribution is as follows:
| Section | Global weight |
|---|---|
| Education | 20% |
| Experience | 60% |
| Skills | 15% |
| Availability | 5% |
| Total | 100% |
These values are fully configurable through the administration interface.
A campaign targeting an experienced candidate can therefore assign greater weight to professional experience, while another campaign can prioritize specific technical skills.
Section Score Calculation Example
Consider an Experience section representing 60% of the final score, with three questions:
| Question | Internal weight | Raw score |
|---|---|---|
| Years of experience | 50% | 80 |
| Experience with similar projects | 30% | 100 |
| Ability to work independently | 20% | 60 |
The section score is calculated as follows:
(80 Γ 0.50) + (100 Γ 0.30) + (60 Γ 0.20)
= 40 + 30 + 12
= 82
The section then contributes to the final score according to its global weight:
82 Γ 0.60 = 49.2
The same calculation is performed for every section.
Final Score Example
| Section | Section score | Global weight | Contribution |
|---|---|---|---|
| Education | 75 | 20% | 15 |
| Experience | 82 | 60% | 49.2 |
| Skills | 90 | 15% | 13.5 |
| Availability | 100 | 5% | 5 |
| Final score | - | 100% | 82.7 / 100 |
The candidate receives a score of 82.7 out of 100 before any penalties are applied.
This method preserves the distinction between the score obtained within a section and its actual contribution to the final ranking.
4. Implementing the Calculation in PHP
The scoring engine is centralized in engine.php.
It processes the question configuration, section weights, candidate responses, and rules associated with the job profile.
The following example illustrates the calculation principle. It is an educational representation, not the production source code.
function calculateScore(
array $sections,
array $rawScores,
float $penalty = 0
): array {
$finalScore = 0.0;
$details = [];
foreach ($sections as $sectionId => $section) {
$sectionScore = 0.0;
foreach ($section['questions'] as $question) {
$questionId = $question['id'];
$rawScore = $rawScores[$questionId] ?? 0;
$sectionScore +=
$rawScore * ($question['weight'] / 100);
}
$contribution =
$sectionScore * ($section['global_weight'] / 100);
$details[$sectionId] = [
'score_section' => $sectionScore,
'contribution' => $contribution
];
$finalScore += $contribution;
}
return [
'score_final' => round(
max(0, $finalScore + $penalty),
1
),
'score_detail' => $details
];
}
In this example, raw scores are assumed to have already been calculated and validated from the candidate's responses.
The actual engine must also account for different question types, allowed values, and configuration rules.
Separating raw score calculation from aggregation makes it possible to maintain a common weighting mechanism even when questions use different evaluation methods.
Penalty Management
The system allows penalties to be associated with specific answers.
For example, a campaign may define a 10-point penalty when an answer does not match an essential job requirement.
Initial score : 82.7
Penalty : -10
Final score : 72.7
The result is bounded at zero in the calculation example presented above.
Penalties distinguish ordinary weighting from specific deductions. An answer can therefore affect the final score beyond its contribution to a section.
This flexibility requires the rules to remain consistent, relevant to the position, and understandable to the recruiter.
5. Dynamic Question and Skill Configuration
Questions are not embedded directly in the engine as job-specific conditional statements.
They are defined in the campaign configuration files.
This separation allows the form, available answers, and associated scores to be modified without changing the PHP scoring engine.
A simplified educational configuration could look like this:
{
"id": "experience",
"section": "experience",
"weight": 50,
"type": "radio",
"scores": {
"junior": 30,
"intermediate": 70,
"senior": 100
}
}
The engine then retrieves the value associated with the selected answer.
Multiple-choice questions, particularly those related to technical skills, require specific processing.
Each selected technology can be matched against the values defined in the question configuration.
{
"id": "technical_stack",
"type": "checkbox",
"scores": {
"PHP": 100,
"JavaScript": 80,
"Python": 70,
"SQLite": 60
}
}
The benefit of this approach is that the list of technologies does not need to be hardcoded into the business logic.
One campaign can evaluate a PHP stack, while another can be configured for a Python or JavaScript environment.
The engine remains the same. The criteria change.
For multiple-choice responses, however, the aggregation method must be explicitly defined to prevent an accumulation of answers from exceeding the maximum contribution allowed for the question.
6. Conditional Fields: Synchronizing Frontend and Backend
Application forms do not necessarily display the same fields to every candidate.
Certain answers trigger additional fields.
For example:
- A positive answer to a portfolio question reveals a URL field
- A positive answer to a certification question may reveal a PDF upload field
A conditional field configuration can be represented as follows:
{
"id": "portfolio",
"trigger": {
"value": "Yes",
"field_id": "portfolio_url",
"field_type": "url",
"field_label": "Portfolio URL",
"required": true
}
}
The frontend uses vanilla JavaScript to show or hide the field depending on the selected answer.
However, this display logic is not a security mechanism.
A user can disable JavaScript, modify the DOM, or send an HTTP request directly to the backend.
The server must therefore independently verify whether the conditional field is expected and required.
Educational example:
$portfolio = $responses['portfolio'] ?? null;
$portfolioUrl = $responses['portfolio_url'] ?? '';
if ($portfolio === 'Yes') {
if (!filter_var(
$portfolioUrl,
FILTER_VALIDATE_URL
)) {
throw new InvalidArgumentException(
'Invalid portfolio URL'
);
}
$scheme = parse_url(
$portfolioUrl,
PHP_URL_SCHEME
);
if (!in_array($scheme, ['http', 'https'], true)) {
throw new InvalidArgumentException(
'Protocol not allowed'
);
}
}
In a complete implementation, the server must also validate the allowed answers and determine how to handle fields submitted when their triggering condition is not satisfied.
The fundamental rule remains the same: the frontend improves the user experience, but the backend determines which data can be accepted.
7. Multi-Campaign Architecture
Each campaign has its own settings, job profile, and storage area.
core/storage/
β
βββ batch_1/
β βββ settings/
β β βββ fields.json
β β βββ template.php
β βββ records/
β βββ entries/
β βββ files/
β
βββ batch_2/
βββ settings/
β βββ fields.json
β βββ template.php
βββ records/
βββ entries/
βββ files/
This organization allows multiple independent recruitment campaigns to coexist without introducing a complex relational structure.
Campaign creation relies on the templates available in core/presets/.
The system generates a new configuration and storage area, then associates a dedicated application form with the campaign.
Each campaign therefore has:
- Its own job profile
- Its own questions and answers
- Its own weights and penalties
- Its own applications and documents
- Its own open or closed status
Isolation is important because two campaigns may use completely different criteria.
A candidate receiving 80 points in one campaign does not necessarily have the same matching level in another.
Scores must always be interpreted within the context of the job profile they relate to.
Path and Access Isolation
A directory-based architecture requires particular attention to campaign identifiers.
An identifier received through an HTTP request must not be used directly to construct an arbitrary server path.
The campaign should be identified from an allowed value and resolved within a known storage area.
This precaution helps reduce the risk of directory traversal and unauthorized access to files belonging to another campaign.
8. JSON-Based Application Storage
Each application is stored as a JSON file.
The public documentation presents a structure similar to the following:
{
"id": "20260514_143000_abc123",
"date": "2026-05-14 14:30:00",
"poste": "Job title",
"prenom": "First name",
"nom": "Last name",
"email": "candidate@example.com",
"score_final": 74.5,
"score_label": "Good fit",
"score_detail": {},
"reponses": {},
"trigger_fields": {}
}
Uploaded documents are stored separately in the campaign's dedicated file directory.
This structure offers several advantages:
- Each application is an independent record
- Responses and scoring results remain associated
- Data can be read without an ORM or database server
- Documents are not embedded directly in JSON
- Campaigns can be isolated at the filesystem level
The dashboard can load a campaign's records, sort them by final score, and display the results.
Candidate Ranking
The ranking principle can be illustrated in PHP:
usort(
$applications,
static function (array $a, array $b): int {
return $b['score_final'] <=> $a['score_final'];
}
);
The system also uses score categories:
| Score | Category |
|---|---|
| β₯ 80 | Excellent |
| β₯ 60 | Good fit |
| β₯ 40 | Partial fit |
| < 40 | Insufficient |
These categories help recruiters interpret the results. They should not be understood as an absolute measure of a candidate's professional value.
Limitations of File-Based Storage
JSON storage is suitable for moderately sized campaigns, particularly when operations primarily involve reading, ranking, and reviewing applications.
The intended usage described for the system is typically between 20 and 200 applications per campaign.
At this scale, a file-based architecture can remain straightforward to operate. However, this does not constitute a performance guarantee across all hosting environments.
As volume increases, several operations become more expensive:
- Loading large numbers of files
- Searching and filtering across multiple criteria
- Sorting all applications
- Handling concurrent writes
- Managing indexes and relationships between records
Migrating to SQLite could become relevant if these requirements exceed the reasonable capabilities of file-based storage.
The absence of a database is therefore a choice suited to a specific scope, not an objective that must be maintained regardless of how the system evolves.
9. Concurrency, Duplicate Prevention, and Data Consistency
The system prevents multiple applications using the same email address within a campaign.
This introduces an important question in a database-free architecture: how can uniqueness be guaranteed when two requests arrive simultaneously?
A simple check followed by a write operation may not be sufficient.
Request A: email not found
Request B: email not found
Request A: save application
Request B: save application
Result: two applications
This scenario illustrates a race condition between verification and persistence.
One possible approach is to use a shared lock for campaign write operations.
$lock = fopen($lockPath, 'c');
if ($lock === false) {
throw new RuntimeException(
'Unable to open lock file'
);
}
try {
if (!flock($lock, LOCK_EX)) {
throw new RuntimeException(
'Unable to lock campaign'
);
}
// Verify campaign status.
// Verify email uniqueness.
// Save the application.
} finally {
flock($lock, LOCK_UN);
fclose($lock);
}
This example illustrates a possible protection strategy. The public documentation does not specify the exact internal synchronization mechanism used by the system.
It is also important to distinguish locking a single operation from maintaining consistency across multiple files.
If an application contains a JSON record and several PDF documents, an interruption may occur between their respective write operations.
A robust architecture must account for incomplete saves, temporary files, and write errors.
10. Administration and Business Configuration
The system allows recruiters to configure campaigns through an administration interface without directly editing JSON or PHP files.
Configurable parameters include:
- Job profile
- Questions and available answers
- Scores assigned to answers
- Question weights
- Global section weights
- Penalty rules
- Communication settings
The interface also displays the total weight distribution.
When global weights do not add up to 100%, a visual indicator allows the recruiter to identify the inconsistency.
This validation must also be performed server-side.
A JavaScript indicator does not guarantee that a saved configuration complies with the constraints of the scoring engine.
To maintain an interpretable score out of 100, weights must comply with the rules defined for each calculation level.
Changing Criteria During a Campaign
Another consideration is what happens when criteria are modified after the first applications have been received.
If scores are stored at submission time, changing weights can make old and new results difficult to compare.
Several strategies are possible:
- Preserve the initial configuration until the campaign closes
- Version configurations and associate each score with its configuration version
- Recalculate existing applications when criteria change
The public documentation does not specify which strategy is used for this scenario.
Nevertheless, this is an important consideration for any configurable scoring engine: traceability concerns not only the result, but also the rules that produced it.
11. The Recruiter Dashboard and Exports
The overview.php dashboard displays applications ranked by score.
Recruiters can review individual applications through record.php, including candidate responses, section scores, and identified technical skills.
This distinction between the overview and detailed record provides two levels of analysis.
Recruiter dashboard
β
βββ Application list
βββ Score-based ranking
βββ Matching categories
β
βΌ
Individual application record
β
βββ Candidate information
βββ Form responses
βββ Section scores
βββ Matched technical skills
βββ Uploaded documents
Documents are accessed through a dedicated endpoint, file.php, rather than by directly exposing the storage directory.
The system also provides CSV exports through extract.php, using UTF-8 BOM encoding and a semicolon separator to improve compatibility with Excel.
Exports must maintain the same access control requirements as the dashboard.
CSV formula injection must also be considered when user-submitted values are exported to spreadsheet applications.
Data that is acceptable in a web form is not necessarily safe when interpreted in another environment.
12. Campaign Lifecycle
The system allows campaigns to be opened, closed, and reopened from the dashboard.
The closed state is represented by the closed.lock file.
Campaign creation
β
βΌ
Open
β
βββ Receive applications
βββ Calculate scores
βββ Review results
β
βΌ
Closed
β
βββ Block new applications
βββ Finalize recruitment
βββ Notify candidates
βββ Purge application data
β
βΌ
Optional reopening
Campaign closure is handled by finalize.php.
The system also provides closure emails to applicants and the deletion of application data.
The closed.lock file represents a business state. It should not be confused with a concurrency lock used to synchronize multiple PHP processes.
This state must be checked during server-side processing, not only when displaying the application form.
A candidate who opened the form before the campaign closed must not be able to bypass the campaign status by submitting the application afterward.
Campaign Closure and Data Deletion
Purging applications is a sensitive operation.
In a recruitment system, stored data may include contact details, personal responses, resumes, and supporting documents.
Campaign closure must therefore account for several considerations:
- Applicable data retention policies
- Potential legal obligations
- Documents associated with applications
- Previously generated exports
- Backups and technical logs
- Errors that may occur during deletion
Reopening a campaign after its data has been purged does not mean that previous applications can be restored.
The distinction between closure, archiving, and deletion must remain explicit.
13. Application Security Without a Framework
The system uses PHP 8.x and vanilla JavaScript without an application framework or Composer and npm dependencies.
This approach requires security mechanisms to be handled directly.
The public documentation describes the following protections:
| Protection | Objective |
|---|---|
| Public/private separation | Prevent direct access to configurations and data |
| CSRF protection | Secure application form submissions |
| Administration sessions | Restrict access to recruiter interfaces |
| Input validation | Control submitted data |
| Upload validation | Restrict documents to PDF files up to 5 MB |
| Duplicate prevention | Limit repeated applications by email |
| Anti-flood protection | Reduce abusive form submissions |
| HTTP security headers | Strengthen browser-side protection |
Options -Indexes |
Disable directory listing |
| Configuration export code | Restrict access to exported settings |
The presence of these mechanisms does not eliminate the need to evaluate their implementation and verify that they cover every sensitive endpoint.
Session and Authorization Protection
The dashboard, detailed application views, downloads, exports, and campaign closure operations must be protected server-side.
Hiding a link in the interface does not constitute access control.
Every sensitive endpoint must verify the session and the permissions required for the requested operation.
Operations that modify application state must also have appropriate protection against forged requests.
PDF Upload Validation
File uploads represent a particular attack surface.
Validation based solely on the file extension is insufficient.
The MIME type, file size, and storage conditions must also be controlled.
A basic validation example:
if ($file['error'] !== UPLOAD_ERR_OK) {
throw new RuntimeException(
'Upload error'
);
}
if ($file['size'] > 5 * 1024 * 1024) {
throw new RuntimeException(
'File too large'
);
}
$finfo = new finfo(FILEINFO_MIME_TYPE);
$mime = $finfo->file($file['tmp_name']);
if ($mime !== 'application/pdf') {
throw new RuntimeException(
'Unsupported file format'
);
}
This validation represents only an initial step. A file identified as a PDF may still contain malicious content.
A complete strategy must also account for storage filenames, permissions, prevention of server-side execution, access controls, and document scanning where appropriate.
Protecting Data During Rendering
Information submitted by candidates is subsequently displayed in the dashboard.
Values must be encoded according to their output context to reduce XSS risks.
echo htmlspecialchars(
$candidate['prenom'],
ENT_QUOTES | ENT_SUBSTITUTE,
'UTF-8'
);
Input validation and output encoding are two different operations.
A framework-free architecture must maintain this distinction across all its interfaces.
14. Deterministic Scoring and Human Decision-Making
The system operates without artificial intelligence.
This distinction matters because the engine does not generate an assessment from a probabilistic interpretation of a candidate's professional background.
It applies configured rules to structured responses.
Job configuration
+
Candidate responses
+
Weights and penalties
β
βΌ
Deterministic score
With identical configurations and responses, the calculation should produce the same result.
This approach makes the score easier to understand, particularly because individual section contributions are preserved.
However, it does not guarantee that the selected criteria are relevant, fair, or free from bias.
A deterministic engine can reproduce biases introduced through its configuration rules, just as an AI-based system can reproduce biases present in its data or models.
Criteria must therefore remain relevant to the professional requirements of the position, proportionate, and regularly reviewed.
The ranking is a decision-support tool. It should not replace human assessment or automatically reject a candidate solely on the basis of their score.
The absence of AI does not eliminate applicable obligations concerning personal data protection, transparency, and automated decision-making.
The value of the system depends as much on the quality of its rules as on the accuracy of its calculations.
15. Deployment and Technical Environment
The architecture is designed to operate in a standard Apache and PHP environment.
The documented requirements are as follows:
PHP 8.x
Apache with mod_rewrite
FTP or SSH access
JSON file-based storage
Vanilla JavaScript
The system does not require a database server, Composer, or npm.
This simplicity reduces the number of components that need to be installed and maintained.
However, it does not eliminate hosting responsibilities:
- Updating PHP and the web server
- Configuring HTTPS
- Managing file and directory permissions
- Protecting the private layer
- Managing backups and restoration
- Logging and monitoring
- Configuring email delivery
The autonomy of the architecture requires these responsibilities to remain controlled at the deployment level.
Conclusion
This architecture illustrates how a structured recruitment system can be built using native PHP, JavaScript, and JSON files without an application framework or database.
Its architecture relies on a configurable scoring engine, independent campaigns, separation between public interfaces and private processing, and an explicit application lifecycle.
The value of this approach is not limited to reducing dependencies.
It also lies in the ability to understand precisely how a score is calculated, which rules are applied, and where data is stored.
This architectural freedom nevertheless requires direct responsibility for security, write consistency, personal data protection, and system maintenance.
A scoring engine can facilitate candidate ranking, but it cannot replace the relevance of recruitment criteria or human judgment.
The objective remains to build a system whose rules, data, and technical decisions are understandable, traceable, and controlled.
Technical Documentation
The public architecture, features, campaign structure, and scoring engine principles are described in the project documentation.
View the technical documentation on GitHub

Top comments (2)
A perfect practice of 'Local-First' and data sovereignty! Using pure, robust PHP logic and flat JSON files completely breaks the extortion of expensive SaaS. Zero messy dependencies, just ultimate architectural certainty. This is true independent engineering that runs anywhere while keeping data fully under control.
Thank you, I really appreciate that.
Iβm not against modern technology or connected systems at all.
But today, many stacks have become extremely fragmented and over-connected, which also increases complexity, dependencies and attack surface.
For some business-critical systems, I believe robustness, maintainability and long-term predictability matter more than constantly adding layers of infrastructure.
Thatβs the philosophy behind these projects.