| Server IP : 167.235.224.122 / Your IP : 216.73.216.110 Web Server : Apache/2.4.58 (Ubuntu) System : Linux newplayground 6.8.0-136-generic #136-Ubuntu SMP PREEMPT_DYNAMIC Wed Jul 1 21:33:11 UTC 2026 aarch64 User : deploy ( 1000) PHP Version : 8.4.23 Disable Function : NONE MySQL : OFF | cURL : ON | WGET : ON | Perl : ON | Python : OFF | Sudo : ON | Pkexec : OFF Directory : /var/www/html/emaji/ |
Upload File : |
# Emaji Project Architecture Documentation
**Last Updated:** November 24, 2025
## Table of Contents
1. [Project Overview](#project-overview)
2. [System Architecture](#system-architecture)
3. [Database Structure](#database-structure)
4. [Authentication & User Management](#authentication--user-management)
5. [Recent Changes](#recent-changes)
6. [Migration Guide](#migration-guide)
7. [Table Reference](#table-reference)
---
## Project Overview
The Emaji ecosystem consists of **two separate Laravel applications** sharing a single MariaDB database:
### 1. **Emaji** (This Repository)
- **Purpose:** Platform for education providers and hiring organizations in healthcare
- **Users:** Organization staff (hospitals, clinics, training providers)
- **User Table:** `organization_users`
- **Core Features:**
- Job posting and management
- Healthcare profession definitions
- Training course offerings
- Qualification/credential management (reference data)
### 2. **Emajiwallet** (Separate Repository)
- **Purpose:** Personal wallet for healthcare workers' credentials and career pathways
- **Users:** Healthcare workers/job seekers
- **User Table:** `users`
- **Core Features:**
- Digital credential storage (verifiable credentials)
- Career pathway tracking
- Language proficiency records
- Job application matching
---
## System Architecture
```
┌──────────────────────────────────────────────────────────────┐
│ SHARED DATABASE: emaji_db36 (MariaDB) │
└──────────────────────────────────────────────────────────────┘
│ │
│ │
┌───────▼────────┐ ┌───────▼────────┐
│ EMAJI APP │ │ EMAJIWALLET │
│ (This Repo) │ │ (Separate) │
└────────────────┘ └────────────────┘
│ │
│ │
┌───────────────▼────────────┐ ┌─────────▼──────────────┐
│ ORGANIZATION USERS │ │ WALLET USERS │
├────────────────────────────┤ ├────────────────────────┤
│ organization_users table │ │ users table │
│ - id │ │ - id │
│ - name │ │ - name │
│ - email │ │ - email │
│ - password │ │ - pin │
│ - email_verified_at │ │ - contact_method │
│ - remember_token │ │ - country │
│ - timestamps │ │ - privacy_accepted_at │
└────────────────────────────┘ └────────────────────────┘
│ │
┌───────────────▼────────────┐ ┌─────────▼──────────────┐
│ ORGANIZATION DATA │ │ WALLET DATA │
├────────────────────────────┤ ├────────────────────────┤
│ • organizations │ │ • user_credentials │
│ • organization_user │ │ • user_identifiers │
│ • jobs │ │ • pathways │
│ • professions │ │ • pathway_requirements │
│ • trainings │ │ • user_languages │
│ • training_instances │ │ • user_qualification │
└────────────────────────────┘ └────────────────────────┘
│ │
└──────────┬────────────────┘
│
┌──────────▼────────────┐
│ SHARED REFERENCE DATA │
├───────────────────────┤
│ • qualifications │
│ • languages │
│ • countries │
│ • credential_mappings │
│ • issuers │
│ • recognition_rules │
└───────────────────────┘
```
---
## Database Structure
### Emaji Tables (33 Total Tables)
#### **Organization Management**
| Table | Purpose | Key Relationships |
|-------|---------|-------------------|
| `organization_users` | Organization staff accounts | Primary auth table for emaji |
| `organizations` | Healthcare organizations | Linked via `organization_user` pivot |
| `organization_user` | Pivot: users ↔ organizations | Foreign keys to both tables + role |
| `organization_kinds` | Organization types | Links to `organizations` |
#### **Job Management**
| Table | Purpose | Key Relationships |
|-------|---------|-------------------|
| `jobs` | Job postings | `organization_id`, `profession_id`, `created_by_organization_user_id`, `organization_user_id` |
| `job_qualifications` | Job qualification requirements | `job_id`, `qualification_id`. Pivot fields: `required`, `level` (CEFR), `informal` (bool: 0=must prove, 1=experience-based — employer's choice, valid for any skill), `notes`, `source_kind` (profession_baseline/language/job_specific) |
| `job_qualification_requirement` | **(Legacy/unused)** Superseded by `job_qualifications` | Only 2 rows remain. No active code uses this. |
#### **Profession Management**
| Table | Purpose | Key Relationships |
|-------|---------|-------------------|
| `professions` | Healthcare professions | Referenced by jobs. Has `summative_qualification_id` (FK to qualifications) — a single degree that covers the profession |
| `profession_qualification` | Profession-qualification links | Pivot table |
| `profession_qualification_requirements` | Individual competencies for a profession | `profession_id`, `qualification_id`. All rows have `required=true`. Fields: `min_level` (CEFR), `notes` |
#### **Training/Education**
| Table | Purpose | Key Relationships |
|-------|---------|-------------------|
| `trainings` | Training courses | `qualification_id`, `provider_id` (org) |
| `training_instances` | Specific training sessions | `training_id` |
| `provider_qualification` | Provider offerings | `organization_id`, `qualification_id` |
#### **Reference Data (Shared)**
| Table | Purpose | Managed By |
|-------|---------|------------|
| `qualifications` | Master qualification list. Types: `skill`, `qualification`, `language`, `certificate`, `clearance`, `license`, `degree`. Has `is_credentialable` flag, `uuid`, `external_uuid`/`external_source`/`external_url` | Emaji (read by both) |
| `languages` | Language reference | Emaji (read by both) |
| `countries` | Country reference | Emaji (read by both) |
| `country_language` | Country-language mapping | Emaji (read by both) |
| `recognition_rules` | Cross-border recognition | Emaji (read by both) |
| `credential_mappings` | Maps credential `achievement_id` to qualifications. Has `cefr_level` for language proficiency, `issuer_id`, `valid_from`/`valid_to` | Emaji (read by both) |
| `issuers` | Credential issuing organizations (`issuer_identifier` in DID format) | Emaji (read by both) |
| `provider_qualification` | Training providers offering qualifications | Emaji (read by both) |
#### **Infrastructure (Shared)**
| Table | Purpose |
|-------|---------|
| `cache`, `cache_locks` | Application caching |
| `sessions` | User sessions (both apps) |
| `password_resets` | Password reset tokens |
| `migrations` | Migration tracking |
---
### Emajiwallet Tables (NOT Accessed by Emaji)
| Table | Purpose |
|-------|---------|
| `users` | Wallet user accounts (password/WebAuthn/PIN auth). Has `encryption_master_key` |
| `user_credentials` | Verifiable credentials (JWT, JSON-LD, OpenBadges, ELM). Maps to qualifications via `achievement_id` → `credential_mappings`. `recipient_identifier` is TEXT (DIDs can be 300+ chars). `vc_location` tracks source (e.g. `source:vc_import`) |
| `user_identifiers` | Multi-identity support: email, phone, DID, national_id. `identifier` is VARCHAR(500) |
| `user_languages` | User language proficiencies |
| `user_qualification` | User qualifications (pivot: `user_id`, `qualification_id`) |
| `pathways` | User career pathways (polymorphic `pathable` → Job or Profession) |
| `pathway_requirements` | Pathway requirement tracking. Has `informal` flag, `source_kind` |
| `identifier_verification_tokens` | Verification tokens for identifiers |
| `shares` / `shared_credentials` | Credential sharing with selective disclosure |
| `skill_endorsements` | Future: peer/employer skill endorsements |
---
## Authentication & User Management
### Emaji Authentication
**Config:** `config/auth.php`
```php
'guards' => [
'web' => [
'driver' => 'session',
'provider' => 'organization_users',
],
],
'providers' => [
'organization_users' => [
'driver' => 'eloquent',
'model' => App\Models\OrganizationUser::class,
],
],
```
**Login Flow:**
1. User submits email + password at `/login`
2. `LoginController@login` validates credentials against `organization_users` table
3. Email verification check (if enabled)
4. Redirect to `employer.jobs` route
**Registration Flow:**
1. User submits organization registration form at `/register/org`
2. `OrgRegisterController@store` creates:
- New `OrganizationUser` record
- New `Organization` record
- Links them via `organization_user` pivot with 'admin' role
3. Auto-login and redirect to `employer.jobs`
**Key Models:**
- **OrganizationUser** (`app/Models/OrganizationUser.php`)
- Extends `Authenticatable`
- Implements `MustVerifyEmail`
- Relationships: `organizations()`, `createdJobs()`, `assignedJobs()`
- **Organization** (`app/Models/Organization.php`)
- Relationships: `users()`, `jobs()`, `kinds()`
- Methods: `isEmployer()`, `isEducationProvider()`
---
## Recent Changes
### Phase 1: Wallet Functionality Removal (Nov 2025)
**Deleted Controllers:**
- `WalletLoginController.php` - Wallet PIN authentication
- `WalletRegisterController.php` - Wallet user registration
- `PathwayController.php` - Pathway management
- `DemoController.php` - Old demo functionality
**Deleted Models:**
- `Wallet.php`, `WalletQualification.php`, `WalletLanguage.php`, `WalletCredential.php`
- `Pathway.php`, `PathwayRequirement.php`
- `UserCredential.php`, `UserIdentifier.php`
- `User.php` (replaced with OrganizationUser)
**Updated Controllers:**
- `ProfessionController.php` - Removed wallet/pathway references
- `QualificationController.php` - Changed views from `wallet.*` to `qualifications.*`
- `Auth/LoginController.php` - Standard email/password only, org users only
**Updated Views:**
- Changed `layouts.wallet` to `layouts.app` in: `terms.blade.php`, `auth/verify.blade.php`, `auth/register.blade.php`
**Configuration Changes:**
- Removed `wallet_domain` from `config/app.php`
- Removed wallet middleware from `bootstrap/app.php`
### Phase 2: Separate User Tables Implementation (Nov 24, 2025)
**Created Migrations:**
1. **`2025_11_24_160916_create_organization_users_table.php`**
```php
Schema::create('organization_users', function (Blueprint $table) {
$table->id();
$table->string('name');
$table->string('email')->unique();
$table->timestamp('email_verified_at')->nullable();
$table->string('password');
$table->rememberToken();
$table->timestamps();
});
```
2. **`2025_11_24_161040_update_organization_user_to_use_organization_users.php`**
- Renames `organization_user.user_id` → `organization_user.organization_user_id`
- Updates foreign key to point to `organization_users` table
3. **`2025_11_24_161106_update_jobs_table_to_use_organization_users.php`**
- Renames `jobs.created_by` → `jobs.created_by_organization_user_id`
- Renames `jobs.user_id` → `jobs.organization_user_id`
- Updates foreign keys to point to `organization_users` table
**Created Models:**
- `OrganizationUser.php` - Main authenticatable model for emaji
- `OrganizationUserPivot.php` - Renamed from old OrganizationUser (pivot model)
**Updated Models:**
- `Organization.php` - `users()` relationship now uses `OrganizationUser`
- `Job.php` - Updated fillable fields and added `createdBy()`, `assignedTo()` relationships
**Updated Controllers:**
- `Auth/LoginController.php` - Uses `OrganizationUser` model
- `Auth/OrgRegisterController.php` - Fully implemented registration logic
**Updated Configuration:**
- `config/auth.php` - All providers changed to `organization_users`
---
## Migration Guide
### ⚠️ Before Running Migrations
**CRITICAL:** These migrations modify foreign key relationships and rename columns. **Backup your database first!**
### Steps to Apply Changes
1. **Backup Database**
```bash
mysqldump -h iu6h.your-database.de -u relevy_36 -p emaji_db36 > backup_$(date +%Y%m%d).sql
```
2. **Review Existing Data**
```sql
-- Check how many org users exist
SELECT COUNT(*) FROM users u
INNER JOIN organization_user ou ON u.id = ou.user_id;
-- Check jobs with user references
SELECT COUNT(*) FROM jobs WHERE created_by IS NOT NULL OR user_id IS NOT NULL;
```
3. **Run Migrations**
```bash
php artisan migrate
```
4. **Data Migration** (if needed)
If you have existing data in the `users` table that needs to move to `organization_users`:
```sql
-- Copy org users from users to organization_users
INSERT INTO organization_users (id, name, email, email_verified_at, password, remember_token, created_at, updated_at)
SELECT u.id, u.name, u.email, u.email_verified_at, u.password, u.remember_token, u.created_at, u.updated_at
FROM users u
INNER JOIN organization_user ou ON u.id = ou.user_id;
-- Update organization_user pivot table
UPDATE organization_user ou
INNER JOIN users u ON ou.user_id = u.id
SET ou.organization_user_id = u.id;
-- Update jobs table
UPDATE jobs j
INNER JOIN users u ON j.created_by = u.id
SET j.created_by_organization_user_id = u.id
WHERE j.created_by IS NOT NULL;
UPDATE jobs j
INNER JOIN users u ON j.user_id = u.id
SET j.organization_user_id = u.id
WHERE j.user_id IS NOT NULL;
```
5. **Test Authentication**
```bash
# Try logging in
php artisan tinker
>>> $user = \App\Models\OrganizationUser::first();
>>> Auth::guard('web')->login($user);
>>> Auth::check();
```
6. **Clean Up Old Data** (Optional)
```sql
-- ONLY after verifying everything works
-- Remove org users from old users table
DELETE u FROM users u
INNER JOIN organization_user ou ON u.id = ou.organization_user_id;
```
---
## Table Reference
### Foreign Key Relationships
```
organization_users
└─ organization_user.organization_user_id (many-to-many with organizations)
└─ jobs.created_by_organization_user_id (one-to-many)
└─ jobs.organization_user_id (one-to-many, nullable)
organizations
└─ organization_user.organization_id (many-to-many with organization_users)
└─ jobs.organization_id (one-to-many)
└─ organization_kinds.organization_id (one-to-many)
└─ trainings.provider_id (one-to-many, as provider)
jobs
├─ profession_id → professions.id
├─ organization_id → organizations.id
├─ created_by_organization_user_id → organization_users.id
└─ organization_user_id → organization_users.id (nullable)
professions
└─ jobs.profession_id (one-to-many)
└─ profession_qualification_requirements (many-to-many with qualifications)
└─ summative_qualification_id → qualifications.id (single degree covering profession)
qualifications (SHARED - READ BY BOTH APPS)
└─ job_qualifications.qualification_id
└─ profession_qualification_requirements.qualification_id
└─ trainings.qualification_id
└─ credential_mappings.qualification_id
└─ user_qualification.qualification_id (emajiwallet)
users (EMAJIWALLET ONLY - DO NOT ACCESS FROM EMAJI)
└─ user_credentials.user_id (emajiwallet)
└─ user_identifiers.user_id (emajiwallet)
└─ pathways.user_id (emajiwallet)
└─ user_languages.user_id (emajiwallet)
└─ user_qualification.user_id (emajiwallet)
```
---
## Key Design Principles
1. **Separation of Concerns**
- Emaji manages **organizations and job postings**
- Emajiwallet manages **individual user credentials and pathways**
- Reference data is managed by emaji but read by both
2. **Data Isolation**
- Emaji NEVER accesses wallet-specific tables (`user_*`, `pathways`, etc.)
- Emajiwallet NEVER modifies organization data
- Shared reference data is read-only for emajiwallet
3. **Authentication Independence**
- Emaji: Email/password authentication
- Emajiwallet: PIN/DID/phone authentication
- No session sharing (separate auth guards)
4. **Future-Proof Design**
- Both apps can be deployed separately
- Database can be split later if needed (with careful foreign key management)
- APIs can be added for inter-app communication if needed
---
## Development Guidelines
### When Adding Features to Emaji:
✅ **DO:**
- Use `OrganizationUser` for authentication
- Link data to `organizations` table
- Create relationships through `organization_user` pivot
- Read from shared reference tables (`qualifications`, `languages`, etc.)
❌ **DON'T:**
- Access `users` table (that's for emajiwallet)
- Access `user_credentials`, `user_identifiers`, `pathways`, etc.
- Create direct relationships to wallet-only tables
- Modify shared reference data without coordination
### Testing Checklist:
- [ ] Organization user can register
- [ ] Organization user can log in
- [ ] Organization user can create jobs
- [ ] Jobs are properly linked to organizations
- [ ] Profession/qualification data displays correctly
- [ ] No errors referencing old `User` model
- [ ] No references to deleted wallet models
---
## Troubleshooting
### Common Issues:
**Issue:** `Class 'App\Models\User' not found`
- **Solution:** Update all references to use `OrganizationUser` instead
**Issue:** Foreign key constraint errors during migration
- **Solution:** Ensure no orphaned records exist before running migrations
**Issue:** Authentication fails after migration
- **Solution:** Clear config cache: `php artisan config:clear && php artisan cache:clear`
**Issue:** "users table not found" in emaji
- **Solution:** Verify you're using `organization_users` in auth config
---
## Contact & Support
For questions about this architecture:
- Check migration files in `database/migrations/`
- Review model relationships in `app/Models/`
- Consult authentication config in `config/auth.php`
**Important Files to Reference:**
- `/ARCHITECTURE.md` (this file)
- `/config/auth.php` - Authentication configuration
- `/app/Models/OrganizationUser.php` - Primary user model
- `/app/Models/Organization.php` - Organization model
- `/routes/web.php` - Route definitions
---
**Last Updated:** February 10, 2026
**Database Version:** emaji_db36
**Laravel Version:** 12.x
**PHP Version:** 8.4+