Architecture - OpenEyes

OpenEyes is built on a modular, event-based architecture using the Yii 1.x PHP framework. This page covers the technical architecture and core design patterns.

Technology Stack

Core Framework

OpenEyes is built on Yii Framework 1.1.28, a high-performance PHP framework based on the Model-View-Controller (MVC) pattern.

protected/composer.json

{
  "require": {
    "php": "^7.4 || ^8.0 || ^8.1",
    "yiisoft/yii": "1.1.28"
  }
}

Dependencies

Key dependencies include:

PHP 7.4+ with support for PHP 8.0 and 8.1
MySQL/MariaDB for data storage
PHPUnit 9.6.5 for testing
Faker for test data generation
PHPStan for static analysis

Architecture Overview

MVC Pattern

OpenEyes follows the classic Model-View-Controller pattern:

protected/
├── models/          # Data models and business logic
├── controllers/     # Request handling and flow control
├── views/          # Presentation layer
├── components/     # Reusable components
└── modules/        # Event type modules

Core Models

The system is built around several key models:

Patient Model

The Patient model is central to the system:

protected/models/Patient.php

class Patient extends BaseActiveRecordVersioned
{
    use HasFactory;

    const CHILD_AGE_LIMIT = 16;
    const PATIENT_SOURCE_OTHER = 0;
    const PATIENT_SOURCE_REFERRAL = 1;
    const PATIENT_SOURCE_SELF_REGISTER = 2;

    // Properties
    // @property int $id
    // @property string $first_name
    // @property string $last_name
    // @property string $dob
    // @property string $gender
    // @property string $hos_num
    // @property string $nhs_num

    // Relations
    // @property Episode[] $episodes
    // @property Address[] $addresses
    // @property Contact $contact
    // @property Gp $gp
    // @property Practice $practice
    // @property Allergy[] $allergies
}

Event Model

Events represent clinical encounters:

protected/models/Event.php

class Event extends BaseActiveRecordVersioned
{
    use HasFactory;

    // Properties
    // @property string $id
    // @property string|int $episode_id
    // @property string|int $user_id
    // @property string|int $event_type_id
    // @property boolean $deleted
    // @property string $event_date

    // Relations
    // @property Episode $episode
    // @property User $user
    // @property EventType $eventType
    // @property EventIssue[] $issues
}

Event-Based Architecture

BaseEventTypeController

All event modules extend BaseEventTypeController, which provides standardized CRUD operations:

protected/controllers/BaseEventTypeController.php

class BaseEventTypeController extends BaseModuleController
{
    const ACTION_TYPE_CREATE = 'Create';
    const ACTION_TYPE_VIEW = 'View';
    const ACTION_TYPE_PRINT = 'Print';
    const ACTION_TYPE_EDIT = 'Edit';
    const ACTION_TYPE_DELETE = 'Delete';

    public $patient;
    public $site;
    public ?Event $event = null;
    public $episode;
    public $editable = true;
    protected $open_elements;
}

The controller is stateful and provides hooks for customization:

setElementDefaultOptions() - Set defaults on elements
setElementComplexAttributesFromData() - Set complex attributes
saveElementComplexAttributesFromData() - Save complex data

Event Type Modules

Each clinical event type is implemented as a module. Example from OphCiExamination:

protected/modules/OphCiExamination/OphCiExaminationModule.php

namespace OEModule\OphCiExamination;

class OphCiExaminationModule extends \BaseEventTypeModule
{
    public $controllerNamespace = '\OEModule\OphCiExamination\controllers';

    public function init()
    {
        $this->setImport(array(
            'application.modules.OphDrPrescription.models.*',
        ));
        $this->setModules(['ExaminationAdmin']);
        parent::init();
    }
}

Module System

OpenEyes uses a modular architecture where functionality is organized into modules:

Module Structure

protected/modules/OphCiExamination/
├── OphCiExaminationModule.php    # Module definition
├── controllers/
│   └── DefaultController.php     # Main controller
├── models/                       # Domain models
├── views/                        # View templates
├── migrations/                   # Database migrations
├── components/                   # Module components
├── factories/                    # Test factories
└── tests/                        # Module tests

Module Naming Conventions

Modules follow specific prefixes based on type:

OphCi - Clinical Investigation (e.g., OphCiExamination)
OphDr - Drug/Prescription (e.g., OphDrPrescription)
OphTr - Treatment (e.g., OphTrOperationnote)
OphCo - Correspondence/Communication (e.g., OphCoCorrespondence)

Database Architecture

Migrations

Database schema changes are managed through migrations:

protected/migrations/
├── m130913_000000_consolidation.php
├── m131009_083758_record_no_allergies.php
└── m131015_125648_proc_aliases.php

Each module can have its own migrations:

protected/modules/OphCiExamination/migrations/

Versioned Models

Core models extend BaseActiveRecordVersioned to track changes:

class Patient extends BaseActiveRecordVersioned
{
    // Automatic versioning of all changes
}

Autoloading

Composer autoloading is configured for modern PHP namespaces:

composer.json

{
  "autoload": {
    "psr-4": {
      "OE\\concerns\\": "protected/concerns",
      "OE\\contracts\\": "protected/contracts",
      "OE\\factories\\": "protected/factories",
      "OE\\listeners\\": "protected/listeners",
      "OE\\seeders\\": "protected/seeders"
    }
  }
}

Component Architecture

Behaviors

Yii behaviors provide reusable functionality:

protected/behaviors/

Widgets

Reusable UI components:

protected/widgets/

Helpers

Utility functions and helper classes:

protected/helpers/

Configuration

Main Configuration

Configuration is loaded through OEConfig:

protected/config/main.php

require_once dirname(__FILE__).'/OEConfig.php';
return OEConfig::getMergedConfig('main');

Local overrides can be placed in:

protected/config/local/

Event System

OpenEyes uses Yii’s event system for extensibility:

Event listeners in protected/listeners/
Components can raise and listen for events
Modules can hook into application-wide events

Services Layer

Business logic is organized into services:

protected/services/

Security

Access Control

Access control is managed through:

Role-based access control (RBAC)
Controller-level access rules
Action-type based permissions

Data Validation

All models implement validation rules:

public function rules()
{
    return [
        ['first_name, last_name', 'required'],
        ['email', 'email'],
    ];
}

Performance Considerations

Caching

Yii provides caching mechanisms:

Database query caching
Fragment caching
Full page caching

Asset Management

Assets are organized per module:

protected/modules/OphCiExamination/assets/

Get Started

User Guide

Clinical Modules

Administration

Development

​Technology Stack

​Core Framework

​Dependencies

​Architecture Overview

​MVC Pattern

​Core Models

​Patient Model

​Event Model

​Event-Based Architecture

​BaseEventTypeController

​Event Type Modules

​Module System

​Module Structure

​Module Naming Conventions

​Database Architecture

​Migrations

​Versioned Models

​Autoloading

​Component Architecture

​Behaviors

​Widgets

​Helpers

​Configuration

​Main Configuration

​Event System

​Services Layer

​Security

​Access Control

​Data Validation

​Performance Considerations

​Caching

​Asset Management

​Next Steps

Module Development

Testing

Build docs developers (and LLMs) love