Organization

An organisation is a client company. It is the tenant boundary: every user belongs to one, and every business record carries its organization_id.

Purpose

The application is multi-tenant, and the organisation is the root of that tenancy. Beyond identity (name, slug, WorkOS directory id) it carries commercial state — contract package and renewal, configuration status, available credits — plus branding and the agent context used to ground AI features. Isolation is enforced by scoping queries on organization_id, not by a package.

Usage

The organisation is resolved on every authenticated request and drives most staff tooling.

app/Http/Middleware/HandleInertiaRequests.php — shares auth.organization with React on each request, cached for 60 seconds per organisation.
app/Filament/Resources/OrganizationResource.php and its Schemas/, Actions/ and RelationManagers/ — the main staff console for a client, including impersonation, branding and agent context.
app/Mcp/Tools/GetOrganizationTool.php and ListOrganizationFilesTool.php — expose organisation data over MCP.
app/Models/Concerns/BelongsToOrganization.php — global scope and auto-fill of organization_id for tenant models.

Relationships

Relation	Type	Related model
`contact`	`belongsTo`	User via `contact_id`
`logo`	`belongsTo`	Attachment via `logo_id`
`users`	`hasMany`	User
`projects`	`hasMany`	Project
`reports`	`hasMany`	Report
`invoices`	`hasMany`	Invoice
`configurationResources`	`hasMany`	ConfigurationResource
`configurationCollections`	`hasMany`	ConfigurationCollection
`memorandum`	`hasOne`	Memorandum
`commercialTraction`	`hasOne`	CommercialTraction
`contractFiles`	`hasMany`	Attachment, filtered to `metadata->type = contract`
`governanceFiles`	`hasMany`	Attachment, filtered to `metadata->type = governance`
`investorsGovernanceComplianceDocuments`	`hasMany`	Attachment, via the model’s own scope
`allFiles`	`hasMany`	Attachment; placeholder for the files relation manager

Other models point back with belongsTo organization, including OpticsSetting, OpticsSearchLog, OpticsIndexedDocument and SuccessionPipeline.

Data shape

Table: organizations.

Identity

Column	Type	Notes
`id`	`uuid`	Primary key
`name`	`string`
`slug`	`string`	Unique, indexed
`workos_id`	`string`	Nullable, indexed; WorkOS organisation
`created_at`, `updated_at`	`timestamp`

Commercial state

Column	Type	Notes
`contract_renewal_at`	`string`	Nullable; stored as a string, not a date
`contract_package`	`string`	Nullable
`configuration_status`	`string`	Defaults to `Incomplete`
`credits_available`	`integer`	Cast to integer, defaults to `0`
`investor_events`	`json`	Nullable, cast to array

Branding and contact

Column	Type	Notes
`contact_id`	`uuid`	Nullable FK to `users`, null on delete
`logo_id`	`uuid`	Nullable FK to `attachments`, null on delete
`brand_color`	`string(7)`	Nullable; hex colour

Agent context

Column	Type	Notes
`approved_providers`	`json`	Cast to array, defaults to `[]`
`context_summary`	`text`	Nullable; grounding summary for AI features
`context_notes`	`text`	Nullable; staff notes for AI features

Two columns present in earlier migrations have since been dropped: active (removed in 2026_06_05_000001) and divergence_report_file_id (removed in 2025_08_11_000001).