Organisation Setup & Masters (ORG)

Module code ORG · Release R0 (masters), R1 (setup wizard, geo-fences), R3 (shared accounts) · Packaging Core · Requirements FR-ORG-*, BR-ORG-* in the PRD and BRD · Related Core HR, Attendance, Leave

1. Overview and scope

ORG holds the tenant's structure and shared masters: who the employer is, where people work, how the organisation is divided, and which holidays apply where. Every other module reads ORG through its service interface. ORG also owns the setup wizard that a new tenant follows (see tenant lifecycle).

In scope: company profile and branding; legal entities with statutory identifiers; work locations with address, time zone, geo-fences and employee-ID sequences; departments, designations, the department-designation map, grades, cost centres; holiday calendars per location with public and optional holidays; custom-field definitions for any entity; the shared client account and contact master used by FFM and TSM (R3); the generic master pattern (active/inactive, duplicate checks, reassignment on deactivation).

Out of scope: employees and their job history (EMP), shifts (ATT), pay structures (PAY).

2. Learned from the reference product

Source: Spryple analysis, §3.3, §4 and §21.3.

• [Observed] Masters share one pattern: add, inline edit, Active/Inactive, duplicates rejected; to deactivate a department you must first transfer its employees (SP-X-01, SP-ORG-02, SP-ORG-03).
• [Observed] Work locations carry a prefix and seed for employee-ID generation; the same prefix and seed give a common sequence, different ones a per-branch sequence (SP-ORG-04).
• [Observed] Holidays are per branch with a type (Public or Optional), no duplicate date per branch, and feed leave-duration calculation (SP-ORG-06).
• [Observed] A department-designation map restricts designations per department when an HR policy rule is on (SP-ORG-07).
• [Observed] Geo-fencing is a radius per branch (200 m in the example) [Observed-SS §21.3].
• [Inferred] There is no multi-company (legal entity) structure documented; the company profile is a single record (§20, question 8).

3. Our design decisions

ID	Decision [Proposed]	Reason
D-ORG-01	A tenant has one or more legal entities, each with PAN, TAN, GSTIN, PF and ESI codes and bank accounts. Locations belong to a legal entity.	Groups with several companies are common among SMEs; statutory files are per entity.
D-ORG-02	Employee-ID sequences are explicit objects (org_id_sequence) referenced by locations, generated with a row lock for gap-free, concurrency-safe numbers.	Keeps the reference behaviour (shared or per-branch) without race conditions.
D-ORG-03	Several geo-fences per location (circle or polygon), optionally Wi-Fi BSSIDs and a QR code (R2).	Campuses, multi-gate plants and client sites.
D-ORG-04	Holiday calendars are reusable and assigned to locations with effective dates.	Many branches share one state calendar; changes propagate once.
D-ORG-05	Deactivating a master that has active references opens a bulk reassignment step, then deactivates.	The reference product requires manual one-by-one transfers.
D-ORG-06	Custom fields are typed definitions per entity (employee, client_account, claim, etc.) with validation, visibility and reportability flags.	Configuration, not customisation.
D-ORG-07	One shared client account master (org_account, org_contact) for FFM and TSM.	The reference product has two separate client masters.

4. Domain model

Cost centres (org_cost_center) follow the same master pattern and are omitted from the diagram.

5. State machines

5.1 Master record (every master)

5.2 Setup wizard

6. Key business logic

6.1 Employee-ID generation

nextEmployeeCode(location):
  seq = SELECT * FROM org_id_sequence WHERE id = location.id_sequence_id FOR UPDATE
  code = seq.prefix + leftPad(seq.next_value, seq.pad_length)
  UPDATE org_id_sequence SET next_value = next_value + 1
  return code        # same transaction as the employee insert; rollback leaves no gap

6.2 Holiday change propagation

on holiday added, removed or moved in calendar C:
  locations = locations using C on that date
  emit org.holiday.changed(locations, date)
  # ATT recomputes days at those locations for open periods and the future.
  # LVE recomputes charged days for future approved requests (sandwich and holidays).

6.3 Readiness score

Each wizard step contributes checks (e.g. "at least one location with a geo-fence", "holiday calendar for the current year", "PF code entered when EPF is enabled"). The score is passed checks over total, shown on the owner dashboard and reported to PLT for health scores.

7. Configuration

Setting	Type	Default	Description
company.default_timezone	string	Asia/Kolkata	Used when a location has none
structure.enforce_dept_designation_map	boolean	false	Restricts designations per department [Observed SP-ORG-07]
structure.department_hierarchy	boolean	false	Allows nested departments
id_sequence.pad_length	integer	4	Digits after the prefix
holidays.optional_per_year	integer	2	Shared with LVE
geofence.default_radius_m	integer	200	Default radius for new fences
logo.max_bytes	integer	1048576	Logo upload size (1 MB, as observed)
custom_fields.max_per_entity	integer	50	Plan-dependent limit

8. Screens by persona

Persona	Screens
org_owner	Setup wizard with readiness score, company profile and branding, legal entities
hr_admin	Locations (map picker, fences, ID sequence), departments, designations, map, grades, cost centres, holiday calendars and assignment, custom fields
finance_admin	Legal-entity statutory codes and bank accounts
sales_admin	Client accounts and contacts (R3)
employee	Holiday list for their location (read-only), org chart (read-only, R2)

9. Events

Event	Consumers
org.location.created, org.location.updated	ATT (fences), PAY (PT and LWF state), RPT
org.geofence.changed	ATT, MOB (cached fences)
org.holiday.changed	ATT (recompute), LVE (recompute future requests), NTF
org.department.deactivated, org.designation.deactivated	EMP (after reassignment)
org.legal_entity.updated	PAY (statutory registrations)
org.account.created, org.account.updated	FFM, TSM

Consumed: plt.tenant.provisioned (seed defaults), emp.job.changed (reference counts for deactivation checks).

10. API surface

Resource	Main operations
/v1/org/company	GET, PUT, logo upload
/v1/org/legal-entities, /v1/org/bank-accounts	CRUD
/v1/org/locations and /v1/org/locations/:id/geofences	CRUD
/v1/org/id-sequences	CRUD, GET /:id/preview
/v1/org/departments, /v1/org/designations, /v1/org/grades, /v1/org/cost-centers	CRUD, POST /:id/deactivate with reassignment plan
/v1/org/holiday-calendars and /:id/holidays	CRUD, POST /:id/assign
/v1/org/custom-fields	CRUD
/v1/org/accounts, /v1/org/contacts	CRUD (R3)
/v1/org/setup	GET readiness, POST step completion

Detailed in API endpoints.

11. Permissions

Permission	Scopes	Default roles
org.company.manage	ORG	org_owner, hr_admin
org.legal_entity.manage	ORG	org_owner, finance_admin
org.location.manage	ORG	hr_admin
org.structure.manage	ORG	hr_admin
org.holiday.manage	ORG, LOCATION	hr_admin, hr_manager
org.holiday.read	SELF, ORG	employee
org.custom_field.manage	ORG	hr_admin
org.account.manage	ORG, TEAM	sales_admin, sales_manager, field_executive (own accounts)
org.setup.manage	ORG	org_owner

12. Reports

Report	Contents
Headcount by location and department	Active employees, joiners, leavers [Observed SA dashboard]
Holiday calendar	Per location and year, public and optional
Master audit	Changes to masters with who and when
Setup readiness	Wizard checks and status

13. Release and priority

Capability	Release	MoSCoW
Company, locations, departments, designations, holidays, ID sequences	R0	Must
Legal entities and bank accounts	R0	Must
Setup wizard and readiness score	R1	Must
Geo-fences (circles, multiple per location)	R1	Must
Grades, cost centres, dept-designation map	R1	Should
Custom fields	R1	Should
Polygon fences, Wi-Fi BSSID, QR	R2	Could
Org chart	R2	Should
Shared client accounts	R3	Must (for FFM and TSM)

14. Open questions

1. Do we need location hierarchies (region, zone, branch) for scopes in R1, or is LOCATION enough? The default is flat locations with an optional region tag.
2. Should holiday calendars be published by the platform per state as templates? This would be part of the statutory pack.
3. Do branches in different time zones exist among Indian SME customers (e.g. overseas offices)? The model supports it; the UI assumes IST by default.