High-Level Overview and Main Entrypoints#

The StudentHub backend is a multi-application Yii2 monorepo. It uses the Yii2 "advanced" template structure, with shared code in common/, multiple application folders (such as admin/, candidate/, company/, etc.), and CLI tooling in console/. Each application (API surface) is a standalone Yii2 app with its own controllers, models, views, config, and web entrypoint.

Web Entrypoints:
Web entrypoints are environment-specific and live under environments/<env>/<app>/web/index.php (e.g., environments/dev/admin/web/index.php). These scripts define YII_ENV, merge configuration from common/config/main.php, common/config/main-local.php, the app's own config/main.php, and config/main-local.php, and then boot a yii\web\Application instance.
Example:

// environments/dev/admin/web/index.php
$config = yii\helpers\ArrayHelper::merge(
    require(__DIR__ . '/../../common/config/main.php'),
    require(__DIR__ . '/../../common/config/main-local.php'),
    require(__DIR__ . '/../config/main.php'),
    require(__DIR__ . '/../config/main-local.php')
);
(new yii\web\Application($config))->run();

Source

Console Entrypoint:
The main console entrypoint is environments/<env>/yii (e.g., environments/dev/yii). This script merges common/config and console/config and runs a yii\console\Application. It is used for cron jobs, migrations, and CLI tasks.
Source

Directory Structure#

There is no top-level backend/ or frontend/ folder. Instead, the repo is organized as follows:

• common/: Shared code, including models (common/models/), components (common/components/), configuration (common/config/), messages, and fixtures. All applications inherit from this codebase.
• admin/, candidate/, company/, manager/, staff/, inspector/, status/, verification/: Each is a standalone Yii2 application with its own config/, controllers/, models/, views/, modules/, web/ (entrypoint and assets), runtime/, and tests/.
• console/: Contains CLI controllers in console/controllers/ (e.g., CronController.php, AlgoliaController.php), and database migrations in console/migrations/.
• environments/: Contains per-environment folders (dev/, prod/, etc.), each with their own copies of entry scripts, config, and vendor assets. This structure also holds the yii CLI scripts and environment-specific overrides.
• modules/: Not a top-level folder. Each app may have its own modules under app/modules/v1 or similar (e.g., admin/modules/v1/).
• components/: Shared components are under common/components/ (see below).
• migrations/: All database migrations are under console/migrations/ (e.g., console/migrations/m240528_164946_candidate_civil_need_verification.php).
• runtime/: Each app has its own runtime/ directory for caches and logs. There is also common/runtime/ for shared runtime artifacts.
• tests/: Each app has its own tests/ directory (e.g., admin/tests/, common/tests/). Tests use Codeception and there is a root codeception.yml.

Examples of important files:

• common/models/Candidate.php: Core candidate entity.
• common/components/WalletManager.php: Wallet/payment manager.
• console/controllers/CronController.php: Main cron/console jobs.
• console/migrations/: All DB migrations.
• environments/dev/admin/web/index.php: Web entrypoint for admin app in dev.
• admin/config/main.php: Admin app config.

Important Models (common/models/*)#

Key domain entities include:

• Candidate (common/models/Candidate.php): Represents a candidate profile, including personal info, assignments, notifications, and relations to work logs and transfers. Implements yii\web\IdentityInterface for authentication.
• Company (common/models/Company.php): Represents an employer, with helpers for payroll, followups, and statistics.
• CandidateWorkingHour (common/models/CandidateWorkingHour.php): Represents individual working hour records (timesheet entries) for candidates, including start/end times, total time, and status.
• CandidateWorkingDate (common/models/CandidateWorkingDate.php): Aggregates daily work logs for a candidate, including total approved/rejected/pending hours.
• Transfer (common/models/Transfer.php): Represents a payroll batch or payment transfer, including company, contract, totals, and status.
• TransferCandidate (common/models/TransferCandidate.php): Represents an individual candidate's payment in a transfer, including hours, rates, bonuses, payment status, and relations to Candidate, Transfer, Company, Bank, Invoice, Store, Contract, and TransferFile.
• Invoice (common/models/Invoice.php): Represents billing and revenue tracking for transfers.
• WalletUser (common/models/WalletUser.php), WalletTransfer (common/models/WalletTransfer.php): Manage internal wallet/balance accounts and transfers.
• Request (common/models/Request.php), RequestInterview (common/models/RequestInterview.php), Suggestion (common/models/Suggestion.php), Job (common/models/Job.php), Story (common/models/Story.php): Capture business requests, interview scheduling, and candidate suggestions.
• Contract (common/models/Contract.php): Represents employment contracts.
• CandidateEvaluation (common/models/CandidateEvaluation.php), CandidateWorkHistory (common/models/CandidateWorkHistory.php), TransferFile (common/models/TransferFile.php), CandidateStats (common/models/CandidateStats.php), CompanyStats (common/models/CompanyStats.php): Support payroll, candidate lifecycle, and reporting.

Timesheet/WorkLog: There is no entity named "Timesheet"; timesheet functionality is implemented via CandidateWorkingHour and CandidateWorkingDate.
If you expect a model named "Timesheet", it is Unknown / Verify.

Key Services and Components (common/components/)#

• WalletManager (common/components/WalletManager.php): Manages wallet entries for users. The addEntry method is currently a no-op; wallet integration is disabled but the component is kept for compatibility.
• PhpExcel (common/components/PhpExcel.php), Excel (common/components/Excel.php): Wrappers for exporting reports, used in cron jobs for generating Excel files.
• EventManager (common/components/EventManager.php): Integrates with analytics/event tracking (e.g., Segment). Used by cron jobs to track and flush events.
• S3ResourceManager (common/components/S3ResourceManager.php), CloudinaryManager (common/components/CloudinaryManager.php): Abstract storage for uploads (photos, IDs, etc.), used across apps.
• Algolia (common/components/Algolia.php): Handles search index synchronization for candidates, companies, etc.
• JWT (common/components/JWT.php): Handles JWT authentication.
• SMSComponent (common/components/SMSComponent.php): Sends SMS notifications.
• ReCaptcha (common/components/ReCaptcha.php): Integrates Google reCAPTCHA.
• SlackLogger (common/components/SlackLogger.php): Sends logs to a Slack webhook.
• JiraComponent (common/components/JiraComponent.php): Integrates with Jira for issue tracking.
• Ipstack (common/components/Ipstack.php): IP geolocation.
• Auth0 (common/components/Auth0.php): Auth0 integration.
• Config (common/components/Config.php): Centralized configuration helper.

Mailer, cache, logging, and URL managers are configured in common/config/main.php and inherited by all apps. Shared services are wired up in common/config/bootstrap.php.

Config and Environments#

Configuration is split as follows:

• common/config/main.php: Defines shared components (db, cache, mailer, logger, URL managers, etc.) and parameters used by all apps.
• common/config/main-local.php: Environment-specific overrides for shared config (e.g., database credentials, debug settings).
• app/config/main.php: Per-app configuration (e.g., admin/config/main.php).
• app/config/main-local.php: Per-app, environment-specific overrides.
• environments/: Each environment (e.g., dev/, prod/) contains its own copies of entry scripts, config, and vendor assets. The environments/index.php manifest maps each deployment target to a per-app config tree.
• Config merging order:
  • For web: common/config/main.php, common/config/main-local.php, app/config/main.php, app/config/main-local.php
  • For console: common/config/main.php, common/config/main-local.php, console/config/main.php, console/config/main-local.php
• Environment variables (e.g., GOOGLE_MAPS_API_KEY) are used in config for components like googleMap.

Console / Cron Commands#

All CLI commands live under console/controllers/. The main cron controller is console/controllers/CronController.php, which implements scheduled jobs such as:

• cron/daily: Sends transfer success emails, deletes expired tokens, checks civil ID expiry, updates firing hit maps, and logs the run time.
• cron/summary: Generates and sends summary reports.
• cron/payable-candidate-notification: Generates reports and sends emails for payable candidates with bank info.
• cron/check-daily-attendance: Sends daily attendance notifications to staff.
• cron/every-minute: Runs every minute for time-sensitive notifications.
• cron/process-transfer-files: Processes pending transfer files.
• cron/fill-civil-id-expiry-date, cron/validate-civil-id, cron/check-if-candidate-total-mismatch, cron/gen-hit-map, cron/process-campaign, cron/weekly, cron/mid-month, cron/end-of-month, cron/remove-duplicate, cron/kuwait-mom-check, cron/segment-transfer, cron/segment-suggestion, cron/segment-expense, cron/update-candidate-stats, cron/update-company-stats, cron/fix-work-logs, cron/fix-work-log-dates, cron/fix-education, and more.

Each action logs to CronLog and interacts with models like Candidate, TransferCandidate, Company, Contract, EmailCampaign, Suggestion, Expense, CandidateStats, CompanyStats, CandidateWorkingHour, CandidateWorkingDate, and MailLog.

Other console controllers include:

• AlgoliaController (console/controllers/AlgoliaController.php): Rebuilds search indexes.
• CentralDbController.php, EventController.php (analytics), ReportController.php, ResourceController.php, XeroController.php (payroll sync).

Database migrations are in console/migrations/ and are run via php yii migrate from the environment directory.

Example cron schedule (see docs/cron-jobs.md):

30 13 * * * php ~/www/yii cron/daily > /dev/null 2>&1
0 8 * * * php ~/www/yii cron/summary > /dev/null 2>&1
0 8 * * * php ~/www/yii cron/payable-candidate-notification > /dev/null 2>&1
30 10 * * 0-4 php ~/www/yii cron/check-daily-attendance > /dev/null 2>&1
* * * * * php ~/www/yii cron/every-minute > /dev/null 2>&1

Tests and Migrations#

• Migrations: All database migrations are in console/migrations/ and are run via the console yii migrate command.
• Tests: Each app has its own tests/ directory (e.g., admin/tests/, common/tests/). Tests use Codeception and there is a root codeception.yml.

Note:
If you expect a model or folder (such as backend/, frontend/, or a model named Timesheet) that is not present, treat it as Unknown / Verify. Timesheet functionality is implemented via CandidateWorkingHour and CandidateWorkingDate.
Modules are not top-level; look inside each app for modules/v1/ or similar.