Admin Setup

Admin Setup is where the platform is shaped to your business. Before a single invoice, quote or shift exists, an administrator models the organisation — its legal entities, branches, departments and positions — defines who may do what by composing roles from a shared capability catalogue and granting them at the right level, and records the company’s own identity, branding and shared settings. Everything else in IXL CORE reads from this foundation: records are scoped to a level in the hierarchy, every action is checked against the access rules set here, and documents carry the company profile and logo configured here.

This guide is a reference for what Admin Setup does and how the pieces fit together. It describes IXL CORE version 1.0.

Overview

Admin Setup covers three connected areas:

• Organisation structure — the organisation and the entity → branch → department → position hierarchy beneath it.
• Roles & permissions — roles you compose from a shared capability catalogue, each capability carried at a defined data-scope level.
• Users & role assignments — granting a role to a member at a chosen scope, with optional start and end dates.
• Platform settings — the company profile, branding assets, document templates and shared setting values that the rest of the platform draws on.

Two ideas run through all three. First, a five-level hierarchy — organisation, entity, branch, department, position — that both structures your records and scopes access to them. Second, every administrative change is written to the audit trail, so who changed what, and when, is always recoverable.

Organisation structure

An organisation is the top of the tree — your tenant. It carries a name, a unique slug, an optional legal name, an external reference and a description, and a status of draft, active, inactive or archived. Beneath it sits a strict hierarchy, each level nested inside the one above:

• An entity is a legal company within the organisation. It has a name, a code unique within the organisation, an optional legal name and registration number, a description, and the same four-way status.
• A branch belongs to an entity — a physical or operational location, with a name, a code unique within its entity, a description, a status, and an is primary flag to mark the head location.
• A department belongs to a branch, with a name, a code unique within its branch, a description and a status. Departments can nest: a department may name a parent department within the same branch, giving you a departmental tree.
• A position belongs to a department — a named seat with a title, a code unique within its department, a description and a status. A position may name the position it reports to (anywhere in the same organisation) and may reference a job profile it represents, so the org chart and HR’s job library stay in step.

Codes are enforced unique only within their parent, so the same code can recur under different entities or branches without clashing. This tree is not cosmetic: it is the same set of levels — organisation, entity, branch, department, position — that scopes every record and every access grant across the platform.

Typical steps

1. Create the organisation, giving it a name and slug.
2. Add each entity (legal company) beneath it, then the branches for each entity.
3. Within each branch, add departments (nesting them where useful) and the positions they contain, wiring reporting lines and job profiles as you go.

Roles & permissions

Access is built in three layers: capabilities, permissions and roles.

A capability is a single named ability — for example the right to view leads or manage settings — and belongs to a functional domain. The capability catalogue is global: it is shared by every tenant and authored only by the platform operator, so a tenant administrator composes from it rather than inventing entries. Each capability declares which data-scope levels it may be exercised at.

A permission binds a capability to a specific scope level (organisation, entity, branch, department or position) with an allow effect, an optional set of constraints, and a status of active, inactive or reserved. The permission’s scope level must be one the capability allows, and a capability may carry only one active permission per scope level and effect.

A role groups permissions under a name and a code (lower-case, dot/underscore/hyphen separated, unique within the organisation), with a description, a status, and is system and is assignable flags. You compose a role by attaching active permissions to it; only active, assignable roles may receive permissions or be granted to users. Crucially, every access decision is enforced on the request itself, not merely hidden in the interface, and an administrator may only confer capabilities they already hold — you cannot attach a permission, or assign a role, that grants an ability you lack yourself. That ceiling stops privilege escalation by an admin curating around their own limits.

Typical steps

1. Browse the shared capability catalogue to find the abilities a role should carry.
2. Create a permission for each capability at the scope level you want it exercised.
3. Create a role, then attach those permissions to build up its rights.

Users & role assignments

Access reaches a person through a role assignment. You pick an existing organisation member, a role, and a scope level, and — for anything below organisation level — the exact entity, branch, department or position the grant applies to. The assignment can carry a start and end date, so access can be time-boxed.

Assignments are guarded on every side. The chosen user must already be a member of the organisation (you provision existing members into roles here; adding a brand-new person is a separate concern). The role must belong to the same organisation and be active and assignable. The scope you name must be internally consistent — a branch must sit under the named entity, a department under that branch, and so on — and each level of the hierarchy is checked against the organisation. Two further protections apply: an administrator may only assign a role whose every capability they already hold, and the platform refuses to expire the last remaining access-administration grant in an organisation, so a tenant can never lock itself out of its own access controls. Every assignment, and every later change to one, is written to the audit trail.

Typical steps

1. Choose a member of the organisation to grant access to.
2. Select the role and the scope level, naming the entity, branch, department or position where required.
3. Optionally set start and end dates to time-box the grant, then save — the grant is audited.

Platform settings

Settings record the company’s own identity and the shared preferences the platform reads.

The company profile holds structured identity on the organisation record: name, legal and trading name, registration and tax numbers, company email, phone and website, and a full address (street, city, region, postal code, country). Viewing it needs the settings.view capability and editing it needs settings.manage, and every save is audited.

Branding stores the company logo and favicon — uploaded as real raster images (PNG, JPG, WebP; SVG is deliberately refused to avoid stored-script risk, and there are size and dimension limits). These assets render in-app and are embedded in branded documents such as letterheads, proposals and the public signing page. The brand colour lives alongside as a shared setting.

Document templates provide the branded layouts those documents are built from, and a template can be set as the default. Finally, shared settings are definition-and-value pairs: a global catalogue of setting definitions (each declaring the scope levels it may be set at) against which your organisation stores values at the organisation, entity, branch or department level. Because a value can be set at several levels, the platform resolves an effective value for any given scope by walking the hierarchy — so a department inherits the organisation’s setting unless a more specific value overrides it. All of this is governed by the same settings.view / settings.manage capabilities and audited on change.

Typical steps

1. Complete the company profile with the legal identity and contact details documents will carry.
2. Upload the logo and favicon, and set a default document template.
3. Set shared setting values at the level you want them to apply, letting more specific scopes override broader ones.

How Admin Setup connects

Admin Setup is the platform foundation the other modules stand on:

• Every module scopes its records to the organisation → entity → branch → department → position hierarchy defined here, and checks every action against the roles and permissions set here.
• The access engine enforces capabilities on each request across the platform — from crm.leads.view to settings.manage — with the same anti-escalation and last-admin protections applied everywhere.
• Branded documents — proposals, contracts, letterheads and the public signing page — draw the company profile, logo and default template from Settings.
• HR’s job library links to positions through the job profile a seat represents, keeping the org chart and workforce data aligned.

Configure this foundation once, and the rest of the business inherits its structure, its access rules and its identity by default.