# ProgencyAI - SaaS ISL/Group Home Management Platform
## Architecture Plan

### Core Framework
- Event-based architecture (EventDispatcher + Listeners)
- Modular system (each feature = self-contained module)
- Multi-tenant (organization-scoped data)
- Role-Based Access Control (RBAC) with strict enforcement
- Background job queue (database-backed)
- Real-time notifications
- AI Agent integration with permission enforcement

### Directory Structure
```
/progencyai
├── public/                  # Web root
│   ├── index.php           # Front controller
│   ├── assets/             # CSS, JS, images
│   └── .htaccess           # URL rewriting
├── core/                   # Framework core
│   ├── App.php             # Application bootstrap
│   ├── Router.php          # URL routing
│   ├── Database.php        # PDO wrapper
│   ├── Auth.php            # Authentication
│   ├── RBAC.php            # Role/Permission enforcement
│   ├── EventDispatcher.php # Event system
│   ├── ModuleManager.php   # Module loader
│   ├── Queue.php           # Background jobs
│   ├── Notification.php    # Notification system
│   ├── AIAgent.php         # AI integration with RBAC
│   ├── View.php            # Template engine
│   ├── Session.php         # Session management
│   ├── Middleware.php      # Request middleware
│   └── Migration.php       # DB migrations
├── modules/                # Feature modules
│   ├── auth/               # Login, registration, password reset
│   ├── organizations/      # Multi-org management
│   ├── users/              # User management
│   ├── consumers/          # Consumer/resident management
│   ├── staff/              # Staff management
│   ├── isp/               # Individual Support Plans
│   ├── mar/               # Medication Administration Records
│   ├── incidents/          # Incident reporting
│   ├── compliance/         # Compliance tracking/audits
│   ├── schedule/           # Scheduling
│   ├── documents/          # Document management
│   ├── training/           # Staff training/certifications
│   ├── reports/            # Reporting engine
│   ├── notifications/      # In-app notifications
│   ├── ai_agents/          # AI-powered features
│   ├── billing/            # SaaS billing
│   └── admin/             # Super admin panel
├── config/                 # Configuration
│   ├── app.php
│   ├── database.php
│   ├── modules.php
│   ├── roles.php
│   └── ai.php
├── migrations/             # Database migrations
├── storage/               # Uploads, logs, cache
└── templates/             # Shared templates
    ├── layouts/
    ├── components/
    └── emails/
```

### Module Structure (each module)
```
modules/consumers/
├── module.json             # Module metadata & config
├── Controller.php          # HTTP handlers
├── Model.php              # Data access
├── Events.php             # Events this module fires
├── Listeners.php          # Events this module listens to
├── Permissions.php        # Required permissions
├── Routes.php             # Module routes
├── migrations/            # Module DB migrations
├── views/                 # Module templates
└── assets/               # Module-specific JS/CSS
```

### Roles (MO DMH Based)
- **Super Admin**: Platform-wide, manages orgs, billing, all data
- **Organization Admin**: Full org access, configures modules/roles
- **Program Director**: Oversees all homes/programs in org
- **Program Manager**: Manages specific location(s)
- **Qualified Intellectual Disability Professional (QIDP)**: ISP development, reviews
- **Registered Nurse (RN)**: Medical oversight, MAR review
- **Licensed Practical Nurse (LPN)**: Medication administration
- **Direct Support Professional (DSP)**: Day-to-day care, documentation
- **Case Manager**: External coordination, ISP participation
- **HR/Training Coordinator**: Staff records, training assignments
- **Read-Only/Auditor**: View access for compliance reviews

### Events Architecture
- UserLoggedIn, UserLoggedOut
- ConsumerCreated, ConsumerUpdated, ConsumerTransferred
- ISPCreated, ISPReviewed, ISPGoalUpdated
- MARSigned, MARMissed, MARException
- IncidentReported, IncidentEscalated, IncidentResolved
- ComplianceAuditRun, ComplianceViolationFound
- TrainingAssigned, TrainingCompleted, CertificationExpiring
- DocumentUploaded, DocumentExpiring
- ScheduleCreated, ShiftChanged
- NotificationCreated, NotificationRead
- OrganizationCreated, ModuleEnabled, ModuleDisabled

### Multi-Org & Module Config
- Organizations table with settings JSON
- org_modules pivot table (which modules enabled per org)
- org_module_config table (per-org module settings)
- Super Admin can enable/disable/configure modules per org
- Default module set based on MO DMH requirements

### AI Agent Permission Enforcement
- AI actions go through same RBAC as user actions
- AI cannot exceed the permissions of the user who invoked it
- Audit log for all AI actions
- Rate limiting per user/org
- AI suggestions vs AI actions (suggestions bypass, actions enforce)