# astin-ua/freescout-organisations architecture

> Architecture diagram of the GitHub repository astin-ua/freescout-organisations, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/astin-ua/freescout-organisations
- Repository: https://github.com/astin-ua/freescout-organisations

## Overview

OrgPortal extends FreeScout with organization and department management, role-scoped access, permanent ticket attribution, a corporate self-service portal, REST endpoints, and notifications. The principal workflow is customer or administrator organization management, ticket-to-organization attribution, then scoped ticket access and notification for corporate users. Admin and API routes dispatch to separate controllers; the portal controller handles manager ticket operations. Provider hooks supply FreeScout integration points. Relationships reflect the excerpts, SOURCE INDEX references, and README; unsampled implementation details are not inferred.

Main entry points: [`Modules/OrgPortal/Http/Controllers/OrgPortalAdminController.php`](https://github.com/astin-ua/freescout-organisations/blob/main/Modules/OrgPortal/Http/Controllers/OrgPortalAdminController.php) (Admin Console), [`Modules/OrgPortal/Http/Controllers/Api/OrgPortalApiController.php`](https://github.com/astin-ua/freescout-organisations/blob/main/Modules/OrgPortal/Http/Controllers/Api/OrgPortalApiController.php) (REST API), [`Modules/OrgPortal/Http/routes.php`](https://github.com/astin-ua/freescout-organisations/blob/main/Modules/OrgPortal/Http/routes.php) (Route Dispatch), [`Modules/OrgPortal/Http/Controllers/OrgPortalFrontController.php`](https://github.com/astin-ua/freescout-organisations/blob/main/Modules/OrgPortal/Http/Controllers/OrgPortalFrontController.php) (Self-Service Portal)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_management["Organization Management"]
  node_admin["Admin Console"]
  node_api["REST API"]
  node_routes["Route Dispatch<br/>[routes.php]"]
  node_org[("Organizations<br/>[Organization.php]")]
  node_membership[("Membership &amp; Roles")]
  node_units[("Structural Units")]
  node_tagbindings[("Tag Bindings")]
end

subgraph group_portal["Corporate Portal"]
  node_portal["Self-Service Portal"]
  node_threadviews[("Thread Views")]
end

subgraph group_attribution["Ticket Attribution"]
  node_service["FreeScout Hooks"]
  node_attribution["Attribution Service<br/>[OrgAttribution.php]"]
end

subgraph group_notifications["Notifications"]
  node_notificationcontroller["Notification Bell"]
  node_notification[("Portal Notifications")]
  node_subscription[("Subscriptions")]
  node_notifyjob["Notification Job"]
  node_email["Notification Email"]
end

node_portaluser(("Corporate Manager"))

node_portaluser -->|"requests portal"| node_routes
node_routes -->|"routes admin"| node_admin
node_routes -->|"routes API"| node_api
node_routes -->|"routes portal"| node_portal
node_routes -->|"routes bell"| node_notificationcontroller
node_admin -->|"manages organizations"| node_org
node_admin -->|"manages memberships"| node_membership
node_admin -->|"manages units"| node_units
node_admin -->|"backfills tickets"| node_attribution
node_api -->|"manages organizations"| node_org
node_api -->|"manages memberships"| node_membership
node_api -->|"manages units"| node_units
node_api -->|"manages bindings"| node_tagbindings
node_portal -->|"checks access"| node_membership
node_portal -->|"reads thread views"| node_threadviews
node_portal -->|"updates preferences"| node_subscription
node_service -->|"uses attribution"| node_attribution
node_attribution -->|"resolves membership"| node_membership
node_attribution -->|"resolves tag bindings"| node_tagbindings
node_service -->|"creates alerts"| node_notification
node_service -->|"selects managers"| node_membership
node_notificationcontroller -->|"reads alerts"| node_notification
node_notificationcontroller -->|"checks ticket scope"| node_attribution
node_notifyjob -->|"sends mail"| node_email
node_portal -.->|"manages alerts"| node_notification
node_service -.->|"queues notifications"| node_notifyjob

click node_admin "https://github.com/astin-ua/freescout-organisations/blob/main/Modules/OrgPortal/Http/Controllers/OrgPortalAdminController.php"
click node_api "https://github.com/astin-ua/freescout-organisations/blob/main/Modules/OrgPortal/Http/Controllers/Api/OrgPortalApiController.php"
click node_routes "https://github.com/astin-ua/freescout-organisations/blob/main/Modules/OrgPortal/Http/routes.php"
click node_org "https://github.com/astin-ua/freescout-organisations/blob/main/Modules/OrgPortal/Models/Organization.php"
click node_membership "https://github.com/astin-ua/freescout-organisations/blob/main/Modules/OrgPortal/Models/OrganizationMember.php"
click node_units "https://github.com/astin-ua/freescout-organisations/blob/main/Modules/OrgPortal/Models/OrganizationUnit.php"
click node_tagbindings "https://github.com/astin-ua/freescout-organisations/blob/main/Modules/OrgPortal/Models/OrganizationTag.php"
click node_portal "https://github.com/astin-ua/freescout-organisations/blob/main/Modules/OrgPortal/Http/Controllers/OrgPortalFrontController.php"
click node_threadviews "https://github.com/astin-ua/freescout-organisations/blob/main/Modules/OrgPortal/Models/OrgPortalThreadView.php"
click node_service "https://github.com/astin-ua/freescout-organisations/blob/main/Modules/OrgPortal/Providers/OrgPortalServiceProvider.php"
click node_attribution "https://github.com/astin-ua/freescout-organisations/blob/main/Modules/OrgPortal/Services/OrgAttribution.php"
click node_notificationcontroller "https://github.com/astin-ua/freescout-organisations/blob/main/Modules/OrgPortal/Http/Controllers/OrgPortalNotificationController.php"
click node_notification "https://github.com/astin-ua/freescout-organisations/blob/main/Modules/OrgPortal/Models/OrgPortalNotification.php"
click node_subscription "https://github.com/astin-ua/freescout-organisations/blob/main/Modules/OrgPortal/Models/OrgNotificationSubscription.php"
click node_notifyjob "https://github.com/astin-ua/freescout-organisations/blob/main/Modules/OrgPortal/Jobs/SendOrgNotification.php"
click node_email "https://github.com/astin-ua/freescout-organisations/blob/main/Modules/OrgPortal/Mail/OrgNotificationMail.php"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_admin,node_api,node_routes,node_org,node_membership,node_units,node_tagbindings toneBlue
class node_portal,node_threadviews toneAmber
class node_service,node_attribution toneMint
class node_notificationcontroller,node_notification,node_subscription,node_notifyjob,node_email toneRose
class node_portaluser toneIndigo
```

## Components

### Organization Management

- [Admin Console](https://github.com/astin-ua/freescout-organisations/blob/main/Modules/OrgPortal/Http/Controllers/OrgPortalAdminController.php): `Modules/OrgPortal/Http/Controllers/OrgPortalAdminController.php`
- [REST API](https://github.com/astin-ua/freescout-organisations/blob/main/Modules/OrgPortal/Http/Controllers/Api/OrgPortalApiController.php): `Modules/OrgPortal/Http/Controllers/Api/OrgPortalApiController.php`
- [Route Dispatch](https://github.com/astin-ua/freescout-organisations/blob/main/Modules/OrgPortal/Http/routes.php): `Modules/OrgPortal/Http/routes.php`
- [Organizations](https://github.com/astin-ua/freescout-organisations/blob/main/Modules/OrgPortal/Models/Organization.php): `Modules/OrgPortal/Models/Organization.php`
- [Membership & Roles](https://github.com/astin-ua/freescout-organisations/blob/main/Modules/OrgPortal/Models/OrganizationMember.php): `Modules/OrgPortal/Models/OrganizationMember.php`
- [Structural Units](https://github.com/astin-ua/freescout-organisations/blob/main/Modules/OrgPortal/Models/OrganizationUnit.php): `Modules/OrgPortal/Models/OrganizationUnit.php`
- [Tag Bindings](https://github.com/astin-ua/freescout-organisations/blob/main/Modules/OrgPortal/Models/OrganizationTag.php): `Modules/OrgPortal/Models/OrganizationTag.php`

### Corporate Portal

- [Self-Service Portal](https://github.com/astin-ua/freescout-organisations/blob/main/Modules/OrgPortal/Http/Controllers/OrgPortalFrontController.php): `Modules/OrgPortal/Http/Controllers/OrgPortalFrontController.php`
- [Thread Views](https://github.com/astin-ua/freescout-organisations/blob/main/Modules/OrgPortal/Models/OrgPortalThreadView.php): `Modules/OrgPortal/Models/OrgPortalThreadView.php`

### Ticket Attribution

- [FreeScout Hooks](https://github.com/astin-ua/freescout-organisations/blob/main/Modules/OrgPortal/Providers/OrgPortalServiceProvider.php): `Modules/OrgPortal/Providers/OrgPortalServiceProvider.php`
- [Attribution Service](https://github.com/astin-ua/freescout-organisations/blob/main/Modules/OrgPortal/Services/OrgAttribution.php): `Modules/OrgPortal/Services/OrgAttribution.php`

### Notifications

- [Notification Bell](https://github.com/astin-ua/freescout-organisations/blob/main/Modules/OrgPortal/Http/Controllers/OrgPortalNotificationController.php): `Modules/OrgPortal/Http/Controllers/OrgPortalNotificationController.php`
- [Portal Notifications](https://github.com/astin-ua/freescout-organisations/blob/main/Modules/OrgPortal/Models/OrgPortalNotification.php): `Modules/OrgPortal/Models/OrgPortalNotification.php`
- [Subscriptions](https://github.com/astin-ua/freescout-organisations/blob/main/Modules/OrgPortal/Models/OrgNotificationSubscription.php): `Modules/OrgPortal/Models/OrgNotificationSubscription.php`
- [Notification Job](https://github.com/astin-ua/freescout-organisations/blob/main/Modules/OrgPortal/Jobs/SendOrgNotification.php): `Modules/OrgPortal/Jobs/SendOrgNotification.php`
- [Notification Email](https://github.com/astin-ua/freescout-organisations/blob/main/Modules/OrgPortal/Mail/OrgNotificationMail.php): `Modules/OrgPortal/Mail/OrgNotificationMail.php`

### Other components

- **Corporate Manager**

## Connections

- Corporate Manager → Route Dispatch: requests portal (evidence: `Modules/OrgPortal/Http/routes.php`)
- Route Dispatch → Admin Console: routes admin (evidence: `Modules/OrgPortal/Http/routes.php`)
- Route Dispatch → REST API: routes API (evidence: `Modules/OrgPortal/Http/routes.php`)
- Route Dispatch → Self-Service Portal: routes portal (evidence: `Modules/OrgPortal/Http/routes.php`)
- Route Dispatch → Notification Bell: routes bell (evidence: `Modules/OrgPortal/Http/routes.php`)
- Admin Console → Organizations: manages organizations (evidence: `Modules/OrgPortal/Http/Controllers/OrgPortalAdminController.php`)
- Admin Console → Membership & Roles: manages memberships (evidence: `Modules/OrgPortal/Http/Controllers/OrgPortalAdminController.php`)
- Admin Console → Structural Units: manages units (evidence: `Modules/OrgPortal/Http/Controllers/OrgPortalAdminController.php`)
- Admin Console → Attribution Service: backfills tickets (evidence: `Modules/OrgPortal/Http/Controllers/OrgPortalAdminController.php`)
- REST API → Organizations: manages organizations (evidence: `Modules/OrgPortal/Http/Controllers/Api/OrgPortalApiController.php`)
- REST API → Membership & Roles: manages memberships (evidence: `Modules/OrgPortal/Http/Controllers/Api/OrgPortalApiController.php`)
- REST API → Structural Units: manages units (evidence: `Modules/OrgPortal/Http/Controllers/Api/OrgPortalApiController.php`)
- REST API → Tag Bindings: manages bindings (evidence: `Modules/OrgPortal/Http/Controllers/Api/OrgPortalApiController.php`)
- Self-Service Portal → Membership & Roles: checks access (evidence: `Modules/OrgPortal/Http/Controllers/OrgPortalFrontController.php`)
- Self-Service Portal → Thread Views: reads thread views (evidence: `Modules/OrgPortal/Http/Controllers/OrgPortalFrontController.php`)
- Self-Service Portal → Subscriptions: updates preferences (evidence: `Modules/OrgPortal/Http/Controllers/OrgPortalFrontController.php`)
- FreeScout Hooks → Attribution Service: uses attribution (evidence: `Modules/OrgPortal/Providers/OrgPortalServiceProvider.php`)
- Attribution Service → Membership & Roles: resolves membership (evidence: `Modules/OrgPortal/Services/OrgAttribution.php`)
- Attribution Service → Tag Bindings: resolves tag bindings (evidence: `Modules/OrgPortal/Services/OrgAttribution.php`)
- FreeScout Hooks → Portal Notifications: creates alerts (evidence: `Modules/OrgPortal/Providers/OrgPortalServiceProvider.php`)
- FreeScout Hooks → Membership & Roles: selects managers (evidence: `Modules/OrgPortal/Providers/OrgPortalServiceProvider.php`)
- Notification Bell → Portal Notifications: reads alerts (evidence: `Modules/OrgPortal/Http/Controllers/OrgPortalNotificationController.php`)
- Notification Bell → Attribution Service: checks ticket scope (evidence: `Modules/OrgPortal/Http/Controllers/OrgPortalNotificationController.php`)
- Notification Job → Notification Email: sends mail (evidence: `Modules/OrgPortal/Jobs/SendOrgNotification.php`)
- Self-Service Portal → Portal Notifications: manages alerts (evidence: `Modules/OrgPortal/Http/Controllers/OrgPortalFrontController.php`)
- FreeScout Hooks → Notification Job: queues notifications (evidence: `Modules/OrgPortal/Providers/OrgPortalServiceProvider.php`)