feat(assessments): layered clinical assessment engine end-to-end

Add a template-driven assessment system with universal intake, clinical
pathways, disease instruments (stroke MVP + extended, diabetes, and ten
specialty packs), scoring, patient outcome trends, REST/API + FHIR
export, and Enterprise org-level assessment analytics. Seed packs and
design/licensing docs ship for deploy and pre-GA review.

app/Models/Assessment.php

@@ -0,0 +1,112 @@
+<?php
+
+namespace App\Models;
+
+use App\Models\Concerns\BelongsToOwner;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Illuminate\Database\Eloquent\Relations\HasMany;
+use Illuminate\Database\Eloquent\Relations\HasOne;
+use Illuminate\Database\Eloquent\SoftDeletes;
+use Illuminate\Support\Str;
+
+class Assessment extends Model
+{
+    use BelongsToOwner, SoftDeletes;
+
+    public const STATUS_DRAFT = 'draft';
+
+    public const STATUS_COMPLETED = 'completed';
+
+    public const STATUS_CANCELLED = 'cancelled';
+
+    protected $table = 'care_assessments';
+
+    protected $fillable = [
+        'uuid', 'owner_ref', 'organization_id', 'branch_id', 'patient_id',
+        'template_id', 'consultation_id', 'visit_id', 'patient_pathway_id', 'practitioner_id',
+        'status', 'assessed_at', 'completed_at', 'completed_by', 'started_by', 'notes',
+    ];
+
+    protected function casts(): array
+    {
+        return [
+            'assessed_at' => 'datetime',
+            'completed_at' => 'datetime',
+        ];
+    }
+
+    protected static function booted(): void
+    {
+        static::creating(function (Assessment $assessment) {
+            if (! $assessment->uuid) {
+                $assessment->uuid = (string) Str::uuid();
+            }
+        });
+    }
+
+    public function getRouteKeyName(): string
+    {
+        return 'uuid';
+    }
+
+    public function organization(): BelongsTo
+    {
+        return $this->belongsTo(Organization::class, 'organization_id');
+    }
+
+    public function branch(): BelongsTo
+    {
+        return $this->belongsTo(Branch::class, 'branch_id');
+    }
+
+    public function patient(): BelongsTo
+    {
+        return $this->belongsTo(Patient::class, 'patient_id');
+    }
+
+    public function template(): BelongsTo
+    {
+        return $this->belongsTo(AssessmentTemplate::class, 'template_id');
+    }
+
+    public function consultation(): BelongsTo
+    {
+        return $this->belongsTo(Consultation::class, 'consultation_id');
+    }
+
+    public function visit(): BelongsTo
+    {
+        return $this->belongsTo(Visit::class, 'visit_id');
+    }
+
+    public function patientPathway(): BelongsTo
+    {
+        return $this->belongsTo(PatientPathway::class, 'patient_pathway_id');
+    }
+
+    public function practitioner(): BelongsTo
+    {
+        return $this->belongsTo(Practitioner::class, 'practitioner_id');
+    }
+
+    public function answers(): HasMany
+    {
+        return $this->hasMany(AssessmentAnswer::class, 'assessment_id');
+    }
+
+    public function score(): HasOne
+    {
+        return $this->hasOne(AssessmentScore::class, 'assessment_id');
+    }
+
+    public function isDraft(): bool
+    {
+        return $this->status === self::STATUS_DRAFT;
+    }
+
+    public function isCompleted(): bool
+    {
+        return $this->status === self::STATUS_COMPLETED;
+    }
+}

app/Models/AssessmentAnswer.php

@@ -0,0 +1,63 @@
+<?php
+
+namespace App\Models;
+
+use App\Models\Concerns\BelongsToOwner;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+
+class AssessmentAnswer extends Model
+{
+    use BelongsToOwner;
+
+    protected $table = 'care_assessment_answers';
+
+    protected $fillable = [
+        'owner_ref', 'assessment_id', 'question_id',
+        'value_text', 'value_number', 'value_boolean', 'value_date', 'value_json',
+    ];
+
+    protected function casts(): array
+    {
+        return [
+            'value_number' => 'decimal:4',
+            'value_boolean' => 'boolean',
+            'value_date' => 'datetime',
+            'value_json' => 'array',
+        ];
+    }
+
+    public function assessment(): BelongsTo
+    {
+        return $this->belongsTo(Assessment::class, 'assessment_id');
+    }
+
+    public function question(): BelongsTo
+    {
+        return $this->belongsTo(AssessmentQuestion::class, 'question_id');
+    }
+
+    /**
+     * Authoritative value for the given answer type (unused columns must stay null at write time).
+     */
+    public function authoritativeValue(?string $answerType = null): mixed
+    {
+        $type = $answerType ?? $this->question?->answer_type;
+
+        return match ($type) {
+            AssessmentQuestion::TYPE_TEXT,
+            AssessmentQuestion::TYPE_TEXTAREA,
+            AssessmentQuestion::TYPE_SINGLE_CHOICE => $this->value_text,
+            AssessmentQuestion::TYPE_NUMBER,
+            AssessmentQuestion::TYPE_INTEGER,
+            AssessmentQuestion::TYPE_SCALE,
+            AssessmentQuestion::TYPE_SCORE_ITEM,
+            AssessmentQuestion::TYPE_CALCULATED => $this->value_number,
+            AssessmentQuestion::TYPE_BOOLEAN => $this->value_boolean,
+            AssessmentQuestion::TYPE_DATE,
+            AssessmentQuestion::TYPE_DATETIME => $this->value_date,
+            AssessmentQuestion::TYPE_MULTI_CHOICE => $this->value_json,
+            default => $this->value_text ?? $this->value_number ?? $this->value_boolean ?? $this->value_date ?? $this->value_json,
+        };
+    }
+}

app/Models/AssessmentQuestion.php

@@ -0,0 +1,61 @@
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Illuminate\Database\Eloquent\Relations\HasMany;
+
+class AssessmentQuestion extends Model
+{
+    public const TYPE_TEXT = 'text';
+
+    public const TYPE_TEXTAREA = 'textarea';
+
+    public const TYPE_NUMBER = 'number';
+
+    public const TYPE_INTEGER = 'integer';
+
+    public const TYPE_BOOLEAN = 'boolean';
+
+    public const TYPE_DATE = 'date';
+
+    public const TYPE_DATETIME = 'datetime';
+
+    public const TYPE_SINGLE_CHOICE = 'single_choice';
+
+    public const TYPE_MULTI_CHOICE = 'multi_choice';
+
+    public const TYPE_SCALE = 'scale';
+
+    public const TYPE_SCORE_ITEM = 'score_item';
+
+    public const TYPE_CALCULATED = 'calculated';
+
+    protected $table = 'care_assessment_questions';
+
+    protected $fillable = [
+        'template_id', 'code', 'section', 'label', 'help_text', 'answer_type',
+        'options', 'is_required', 'sort_order', 'score_key', 'validation',
+    ];
+
+    protected function casts(): array
+    {
+        return [
+            'options' => 'array',
+            'validation' => 'array',
+            'is_required' => 'boolean',
+            'sort_order' => 'integer',
+        ];
+    }
+
+    public function template(): BelongsTo
+    {
+        return $this->belongsTo(AssessmentTemplate::class, 'template_id');
+    }
+
+    public function answers(): HasMany
+    {
+        return $this->hasMany(AssessmentAnswer::class, 'question_id');
+    }
+}

app/Models/AssessmentScore.php

@@ -0,0 +1,34 @@
+<?php
+
+namespace App\Models;
+
+use App\Models\Concerns\BelongsToOwner;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+
+class AssessmentScore extends Model
+{
+    use BelongsToOwner;
+
+    protected $table = 'care_assessment_scores';
+
+    protected $fillable = [
+        'owner_ref', 'assessment_id', 'template_code',
+        'total_score', 'max_score', 'subscores', 'severity_label', 'computed_at',
+    ];
+
+    protected function casts(): array
+    {
+        return [
+            'total_score' => 'decimal:4',
+            'max_score' => 'decimal:4',
+            'subscores' => 'array',
+            'computed_at' => 'datetime',
+        ];
+    }
+
+    public function assessment(): BelongsTo
+    {
+        return $this->belongsTo(Assessment::class, 'assessment_id');
+    }
+}

app/Models/AssessmentTemplate.php

@@ -0,0 +1,95 @@
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Builder;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Illuminate\Database\Eloquent\Relations\HasMany;
+use Illuminate\Database\Eloquent\SoftDeletes;
+use Illuminate\Support\Str;
+
+/**
+ * Platform catalog row (no owner_ref). System templates in v1 always have null organization_id.
+ */
+class AssessmentTemplate extends Model
+{
+    use SoftDeletes;
+
+    public const CATEGORY_UNIVERSAL = 'universal';
+
+    public const CATEGORY_DISEASE = 'disease';
+
+    public const CATEGORY_OUTCOME = 'outcome';
+
+    public const CATEGORY_SCREENING = 'screening';
+
+    protected $table = 'care_assessment_templates';
+
+    protected $fillable = [
+        'uuid', 'organization_id', 'code', 'name', 'category', 'description',
+        'version', 'is_current', 'scoring_strategy', 'meta', 'is_active',
+    ];
+
+    protected function casts(): array
+    {
+        return [
+            'version' => 'integer',
+            'is_current' => 'boolean',
+            'is_active' => 'boolean',
+            'meta' => 'array',
+        ];
+    }
+
+    protected static function booted(): void
+    {
+        static::creating(function (AssessmentTemplate $template) {
+            if (! $template->uuid) {
+                $template->uuid = (string) Str::uuid();
+            }
+        });
+    }
+
+    public function getRouteKeyName(): string
+    {
+        return 'uuid';
+    }
+
+    public function organization(): BelongsTo
+    {
+        return $this->belongsTo(Organization::class, 'organization_id');
+    }
+
+    public function questions(): HasMany
+    {
+        return $this->hasMany(AssessmentQuestion::class, 'template_id')->orderBy('sort_order');
+    }
+
+    public function assessments(): HasMany
+    {
+        return $this->hasMany(Assessment::class, 'template_id');
+    }
+
+    public function scopeSystem(Builder $query): Builder
+    {
+        return $query->whereNull($this->getTable().'.organization_id');
+    }
+
+    public function scopeCurrent(Builder $query): Builder
+    {
+        return $query->where($this->getTable().'.is_current', true)
+            ->where($this->getTable().'.is_active', true);
+    }
+
+    /**
+     * Resolve the current system template for a stable code (e.g. nihss, universal_intake).
+     */
+    public static function currentSystemByCode(string $code): ?self
+    {
+        return static::query()
+            ->system()
+            ->current()
+            ->where('code', $code)
+            ->first();
+    }
+}

app/Models/ClinicalPathway.php

@@ -0,0 +1,66 @@
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Builder;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\HasMany;
+use Illuminate\Database\Eloquent\SoftDeletes;
+use Illuminate\Support\Str;
+
+/** Platform catalog pathway (no owner_ref). */
+class ClinicalPathway extends Model
+{
+    use SoftDeletes;
+
+    protected $table = 'care_clinical_pathways';
+
+    protected $fillable = [
+        'uuid', 'code', 'name', 'description', 'match_rules',
+        'is_active', 'sort_order', 'meta',
+    ];
+
+    protected function casts(): array
+    {
+        return [
+            'match_rules' => 'array',
+            'meta' => 'array',
+            'is_active' => 'boolean',
+            'sort_order' => 'integer',
+        ];
+    }
+
+    protected static function booted(): void
+    {
+        static::creating(function (ClinicalPathway $pathway) {
+            if (! $pathway->uuid) {
+                $pathway->uuid = (string) Str::uuid();
+            }
+        });
+    }
+
+    public function getRouteKeyName(): string
+    {
+        return 'uuid';
+    }
+
+    public function templates(): HasMany
+    {
+        return $this->hasMany(PathwayTemplate::class, 'pathway_id')->orderBy('sort_order');
+    }
+
+    public function patientPathways(): HasMany
+    {
+        return $this->hasMany(PatientPathway::class, 'pathway_id');
+    }
+
+    public function scopeActive(Builder $query): Builder
+    {
+        return $query->where('is_active', true);
+    }
+
+    public static function findByCode(string $code): ?self
+    {
+        return static::query()->where('code', $code)->where('is_active', true)->first();
+    }
+}

app/Models/Consultation.php

@@ -78,6 +78,11 @@ class Consultation extends Model
         return $this->hasMany(Diagnosis::class, 'consultation_id');
     }
 
+    public function assessments(): HasMany
+    {
+        return $this->hasMany(Assessment::class, 'consultation_id');
+    }
+
     public function documents(): HasMany
     {
         return $this->hasMany(ConsultationDocument::class, 'consultation_id');

app/Models/PathwayTemplate.php

@@ -0,0 +1,35 @@
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+
+/** Catalog binding: pathway → template_code (resolve is_current at assessment start). */
+class PathwayTemplate extends Model
+{
+    public const PHASE_ACUTE = 'acute';
+
+    public const PHASE_FOLLOW_UP = 'follow_up';
+
+    public const PHASE_ANY = 'any';
+
+    protected $table = 'care_pathway_templates';
+
+    protected $fillable = [
+        'pathway_id', 'template_code', 'is_required_on_activation', 'phase', 'sort_order',
+    ];
+
+    protected function casts(): array
+    {
+        return [
+            'is_required_on_activation' => 'boolean',
+            'sort_order' => 'integer',
+        ];
+    }
+
+    public function pathway(): BelongsTo
+    {
+        return $this->belongsTo(ClinicalPathway::class, 'pathway_id');
+    }
+}

app/Models/Patient.php

@@ -99,6 +99,16 @@ class Patient extends Model
         return $this->hasMany(Visit::class, 'patient_id');
     }
 
+    public function assessments(): HasMany
+    {
+        return $this->hasMany(Assessment::class, 'patient_id');
+    }
+
+    public function pathways(): HasMany
+    {
+        return $this->hasMany(PatientPathway::class, 'patient_id');
+    }
+
     public function investigationRequests(): HasMany
     {
         return $this->hasMany(InvestigationRequest::class, 'patient_id');

app/Models/PatientPathway.php

@@ -0,0 +1,81 @@
+<?php
+
+namespace App\Models;
+
+use App\Models\Concerns\BelongsToOwner;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Illuminate\Database\Eloquent\Relations\HasMany;
+use Illuminate\Database\Eloquent\SoftDeletes;
+use Illuminate\Support\Str;
+
+class PatientPathway extends Model
+{
+    use BelongsToOwner, SoftDeletes;
+
+    public const STATUS_ACTIVE = 'active';
+
+    public const STATUS_RESOLVED = 'resolved';
+
+    public const STATUS_INACTIVE = 'inactive';
+
+    protected $table = 'care_patient_pathways';
+
+    protected $fillable = [
+        'uuid', 'owner_ref', 'organization_id', 'patient_id', 'pathway_id',
+        'status', 'activated_at', 'activated_by', 'activation_consultation_id',
+        'activation_diagnosis_text', 'resolved_at', 'notes',
+    ];
+
+    protected function casts(): array
+    {
+        return [
+            'activated_at' => 'datetime',
+            'resolved_at' => 'datetime',
+        ];
+    }
+
+    protected static function booted(): void
+    {
+        static::creating(function (PatientPathway $row) {
+            if (! $row->uuid) {
+                $row->uuid = (string) Str::uuid();
+            }
+        });
+    }
+
+    public function getRouteKeyName(): string
+    {
+        return 'uuid';
+    }
+
+    public function organization(): BelongsTo
+    {
+        return $this->belongsTo(Organization::class, 'organization_id');
+    }
+
+    public function patient(): BelongsTo
+    {
+        return $this->belongsTo(Patient::class, 'patient_id');
+    }
+
+    public function pathway(): BelongsTo
+    {
+        return $this->belongsTo(ClinicalPathway::class, 'pathway_id');
+    }
+
+    public function activationConsultation(): BelongsTo
+    {
+        return $this->belongsTo(Consultation::class, 'activation_consultation_id');
+    }
+
+    public function assessments(): HasMany
+    {
+        return $this->hasMany(Assessment::class, 'patient_pathway_id');
+    }
+
+    public function isActive(): bool
+    {
+        return $this->status === self::STATUS_ACTIVE;
+    }
+}

app/Models/Visit.php

@@ -74,6 +74,11 @@ class Visit extends Model
         return $this->hasMany(Consultation::class, 'visit_id');
     }
 
+    public function assessments(): HasMany
+    {
+        return $this->hasMany(Assessment::class, 'visit_id');
+    }
+
     public function bill(): HasOne
     {
         return $this->hasOne(Bill::class, 'visit_id');