> Source: https://wexa.ai/docs/administration/departments-and-projects

# Departments and projects

Below the organization, Wexa has exactly two structural levels: **departments** and **projects**.
Mirroring a company means deciding, for each team, which of the two it should be. This page gives
that decision a rule, then covers the screens that create each.

## The rule

**A project is the unit of isolation. A department is the unit of delegated administration.**

Everything a team's work consists of — its context graph, its knowledge base, its data catalog, its
[ontology](/docs/concepts/project-ontology), its agents and their executions — belongs to exactly one
project and is not visible from another. If two teams must not see each other's material, they need
two projects; nothing weaker will do it.

A department owns no work of its own. What it owns is **who administers what**: a department
administrator administers every project underneath it without being named on each one, and a
department carries an allow-list of what its projects may reach. If you have one team whose work is
one body of material, you want one project — putting a department around it buys nothing. If you have
a division with five teams whose work must stay separate but whose administration should be one
person's job, you want a department with five projects.

### Worked cases

| Your situation | What to create | Why |
|---|---|---|
| A single team trying Wexa out | One project, no department | A department with one project adds a level that never branches |
| Two teams who must not see each other's data | Two projects | Isolation is a property of the project and only of the project |
| Two teams who share data freely and share a lead | One project | A second project means copying or re-ingesting everything they share |
| A division of several teams, one divisional lead who should administer all of them | One department, one project per team | The lead is made a department administrator once instead of on every project |
| The same work at different stages, e.g. a trial before a rollout | Two projects | The trial's context and ontology should not survive into the rollout |
| A team that needs a different set of connectors or models from its neighbours | One project, and a department scope that permits only what it needs | Scopes are set on the department and narrowed per project |

The trap to avoid is creating a department per team **and** a project per team. That leaves a
one-to-one tree where every administrative act has to be done at the level you happened to guess,
and it is the shape that is hardest to collapse later.

## Departments

Settings → Departments (`/settings/departments`). Departments are also served by the identity
service at `/departments` and `/settings/departments`.

**Creating one.** The screen asks for a name and nothing else. A duplicate name is refused with
`409 "A department with that name already exists."`

**Who may create one.** Organization-wide administrators only — an Org Admin or the organization's
owner. A department administrator administers the department they were given; creating further ones
is an organization-level act, and both `POST /departments` and `POST /settings/departments` answer
`403 "Only a super admin or org admin can create a department."` to anyone below that tier. The
"New department" button is hidden for them for the same reason.

**Renaming one.** Safe: people and projects stay attached. The screen says as much.

**Deleting one.** Refused with `409` while it still has people — `"Cannot delete a department with
N member(s)."` Move the people first.

**Who may change one.** `PUT` and `DELETE` are reserved for organization-wide administrators, the
department's own owner, and its own administrators. A department administrator scoped to a different
department gets `403 "You can only manage departments you administer."` This is enforced on the
server, not only hidden in the screen.

### Department scopes

Open a department (`/settings/departments/{id}`) and you can set its **scopes** — which projects it
reaches, and which modules, connectors, models, entity types and actions its work may use, plus a
clearance for sensitive data classes.

Two properties make this predictable:

- **Restrict-only.** A scope narrows; it never widens. The set available to a department is bounded
  by the organization's, and a project's by its department's — organization ⊇ department ⊇ project.
  A grant that exceeds the level above is refused with `403`.
- **Server-enforced.** The screen shows the scope controls only to an organization administrator, and
  `PUT /settings/departments/{id}/scopes` refuses anyone else with
  `"Only a super admin, org admin, or the department owner can grant department scopes."`

An empty scope list means "everything the level above allows", not "nothing".

## Projects

Settings → Projects (`/settings/projects`). A project is created with a name; a duplicate is refused
with `"A project with that name already exists"`. From the same screen you can rename a project,
make it your active one, and delete it.

**Who may create a project.** Organization administrators and department administrators. A project
administrator may not — they administer the project they were given rather than spawning new ones —
and neither may a plain member. The screen reflects this by telling a member with no projects to ask
an administrator rather than offering a button the server would refuse, and `POST /project` enforces
the same rule with `403`.

A department administrator creates **inside a department they administer**: the request must name
that department (the screen's department selector, or the active department scope), and naming
another one is refused with `403 "You can only create projects in departments you administer."`
Organization administrators are unrestricted.

**Each project has a mode.** `auto` in the API, shown as **Simple** in the application; `manual` in
the API, shown as **Advanced**. The mode changes how much of the platform a project's members see and
how the [ontology](/docs/concepts/project-ontology) is edited, so it is worth setting deliberately
rather than leaving at the default — see [project mode](/docs/concepts/project-mode). Reading a
project's mode across a scope boundary returns `403`, and changing it is restricted to an
administrator and recorded in the audit trail.

## How the structure shows up elsewhere

The tree you build here is not only an organizing device; three other things read it directly.

- **Roles.** `dept_admin` and `project_admin` are meaningless without the department or project they
  are scoped to. An invitation carrying one of those roles must carry its scope, and is refused
  otherwise. See [roles and permissions](/docs/administration/roles-and-permissions).
- **Credentials.** An API key is minted against one project and can be listed or revoked only by an
  administrator of that project. See
  [credential management](/docs/administration/credential-management).
- **Quota.** The per-project ceiling is per project, and the organization ceiling is shared by all of
  them. Splitting one team into four projects gives each a separate project bucket but does not give
  them more organization headroom. See [quota and credits](/docs/concepts/quota-and-credits).