> ## Documentation Index
> Fetch the complete documentation index at: https://docs.azalt.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Organization

> Organization model, settings, membership, and access

## Overview

An Organization is the top-level tenant for all data, users, and settings. Each organization owns a hierarchical tree of Sites, membership records (roles), and configuration.

## Creation & Default Structure

* Creating an organization also creates:
  * a root Site (`id` like `site-root-*`, name `root`),
  * a default "HQ" child site, and
  * an OrganizationUser membership for the creator with `OWNER` role, assigned to the root site.
* The creator’s `currentOrganizationId` is set to the new organization.

## Settings

Organization settings influence workflows, AI features, and UI options:

* `defaultFormWorkflow`: `{ type: "DIRECT_APPROVAL" | "REQUIRE_APPROVAL" }` (affects submission status behavior)
* `defaultDashboardStatuses`: default statuses to display on dashboards
* `requireFormAssignment`: roles required to be assigned to forms
* AI keys (OpenAI/Anthropic): stored encrypted for UI/Calc generation

Admin settings handle branding/terminology (e.g., site label overrides).

## Membership & Roles (RBAC)

Memberships (`OrganizationUser`) tie a `User` to an organization with a role and status:

* Roles: `VIEWER`, `COLLECTOR`, `APPROVER`, `MANAGER`, `OWNER` (hierarchical)
* Status: `INVITED` → `ACTIVE` → `INACTIVE` (email-based invitations)

## Site Access (ABAC)

Site access is granted via `OrganizationUserSite` assignments. Effective access = assigned sites + all descendants. Assigning the root site yields access to the entire organization.

## Key Operations

* Get current org: `organizations.get`
* Create org: `organizations.create`
* Switch org: `organizations.switch`
* List orgs (user memberships): `organizations.list`
* List users (filtered by caller’s site access): `organizations.listUsers`
* Invite user: `organizations.inviteUser({ email, role, assignedSiteIds })`
* Update user role: `organizations.updateUserRole({ userId, role, assignedSiteIds? })`
* Update user sites: `organizations.updateUserSites({ userId, assignedSiteIds })`
* Bulk role/site ops: `organizations.bulkUpdateUserRoles`, `organizations.bulkUpdateUserSites`
* Update settings: `organizations.update`

All procedures enforce RBAC and ABAC (role + site access) and rely on Row Level Security.

## Best Practices

* Assign owners/managers to the root site for full access; assign others to region/site branches.
* Set `defaultFormWorkflow` and `requireFormAssignment` early to align behaviors.
* Use clear naming and tags for sites; keep the hierarchy shallow when possible.
* Prefer bulk operations for site/role assignments when updating many users.

## Gotchas

* Users without site assignments have no effective site access (they may still appear in admin lists).
* Root site cannot be deleted; deleting sites is soft-delete and can cascade to descendants.
* Coordinates on Site are strings in outputs; convert to numbers for calculations.

## See Also

* Site (hierarchy, schema, import)
* Organization User (membership, roles)
* Organization User Site (site assignments and access)