Organization Types, Academic Structure & Terminology

Classgrid supports multiple kinds of educational organizations without forcing every institution to use engineering-college terminology.

The platform separates an institution's identity from the shape of its academic hierarchy:

• org_type identifies what kind of institution the organization is.
• structure_type selects the exact hierarchy plan and terminology profile.
• division_mode records whether divisions or sections are visible to users.
• allow_sub_batches controls optional lab-batch or sub-batch splitting where supported.

This guide is written for institution IT administrators, implementation teams, and developers integrating with Classgrid.

Readers who are new to these concepts can start with Sections 16 through 28, which explain the theory, vocabulary, lifecycle, and end-to-end examples in plain language.

Important: org_type and structure_type are selected when the organization is registered. They are permanent organization identity fields and must not be changed after creation. Correcting an incorrect selection requires a controlled data migration, not a normal settings update.

Developer warning: Never hardcode words such as "Semester", "Division", "PRN", "Faculty", or "Examination" in shared interfaces. Load the active organization's terminology from GET /api/hierarchy/terminology.

1. Core concepts

1.1 org_type: institution identity

org_type answers this question:

What kind of educational institution owns this Classgrid organization?

The Organization model accepts six values:

school
junior_college
engineering
coaching
diploma
other

The value affects institution profiles, role availability, admissions behavior, academic labels, and other organization-aware features.

1.2 structure_type: hierarchy and terminology plan

structure_type answers this question:

What academic hierarchy and terminology should this organization use?

Classgrid accepts 13 structure variants:

engineering
engineering_with_div
engineering_no_div
school_with_div
school_no_div
coaching
junior_college
junior_college_with_div
junior_college_no_div
diploma
diploma_with_div
diploma_no_div
custom

One org_type can map to multiple structure_type values.

For example:

engineering
├── engineering                Legacy Plan 1
├── engineering_with_div       Plan 1a
└── engineering_no_div         Plan 1b

1.3 division_mode: visible or hidden divisions

division_mode accepts:

with_divisions
without_divisions

When without_divisions is selected, the interface omits the division selector.

The backend still creates a hidden division node named Default where a stable division relationship is required for storage.

1.4 allow_sub_batches: optional splitting

allow_sub_batches is a Boolean organization setting.

When enabled for a compatible structure, it allows smaller learner groups below a division, such as:

• Engineering: Lab Batch
• Junior College: Batch
• Diploma: Lab Batch

School terminology sets sub_batch to null.

Coaching uses its native Batch hierarchy label and does not use the optional sub_batch field.

2. The six institution types

2.1 Organization-to-structure relationship

Legacy values exist for backward compatibility. New Engineering, Junior College, and Diploma organizations should use an explicit _with_div or _no_div value.

3. Complete structure-type reference

The hierarchy arrays shown below are copied from the server terminology map.

The array describes the labels exposed by the terminology profile. A hidden Default division used for storage is deliberately absent from _no_div arrays.

3.1 engineering — Legacy Plan 1

Visible hierarchy:

Degree → Department → Year → Semester → Division

Example values:

Exact terminology hierarchy:

["Degree", "Department", "Year", "Semester", "Division"]

Optional lab splitting can add Lab Batch values such as A1 and A2 below a division when allow_sub_batches is enabled.

3.2 engineering_with_div — Plan 1a

Visible hierarchy:

Degree → Department → Year → Semester → Division

Example values:

Exact terminology hierarchy:

["Degree", "Department", "Year", "Semester", "Division"]

Use this structure when learners, classrooms, attendance, fees, or examinations must be scoped to named divisions such as A, B, or C.

3.3 engineering_no_div — Plan 1b

Visible hierarchy:

Degree → Department → Year → Semester

Example values:

Exact terminology hierarchy:

["Degree", "Department", "Year", "Semester"]

The hidden Default node preserves backend relationships without asking users to choose a division.

3.4 school_with_div — Plan 2

Visible hierarchy:

Standard → Section

Example values:

Exact terminology hierarchy:

["Standard", "Division"]

The raw hierarchy array uses Division; the active terminology field division renders that concept as Section for a school.

3.5 school_no_div — Plan 3

Visible hierarchy:

Standard

Example values:

Exact terminology hierarchy:

["Standard"]

Use this structure when each standard has only one learner group and users should not see a section selector.

3.6 coaching — Plan 4

Declared terminology hierarchy:

Course → Year → Phase → Batch

Example values:

Exact terminology hierarchy:

["Course", "Year", "Phase", "Batch"]

Coaching uses Batch as a native academic grouping. It does not use Engineering-style divisions or optional lab sub-batches.

3.7 junior_college — Legacy Plan 5

Visible hierarchy:

Stream → Standard → Division → Batch

Example values:

Exact terminology hierarchy:

["Stream", "Standard", "Division", "Batch"]

The Batch label is the Junior College sub_batch term.

3.8 junior_college_with_div — Plan 5a

Visible hierarchy:

Stream → Standard → Division → Batch

Example values:

Exact terminology hierarchy:

["Stream", "Standard", "Division", "Batch"]

Batch splitting remains optional and should be enabled only when the organization uses it.

3.9 junior_college_no_div — Plan 5b

Visible hierarchy:

Stream → Standard → Batch

Example values:

Exact terminology hierarchy:

["Stream", "Standard", "Batch"]

The hidden division is a storage node and must not be presented as a learner-facing choice.

3.10 diploma — Legacy Plan 6

Visible hierarchy:

Department → Year → Semester → Division

Example values:

Exact terminology hierarchy:

["Department", "Year", "Semester", "Division"]

Optional practical splitting can add Lab Batch values below divisions when allow_sub_batches is enabled.

3.11 diploma_with_div — Plan 6a

Visible hierarchy:

Department → Year → Semester → Division

Example values:

Exact terminology hierarchy:

["Department", "Year", "Semester", "Division"]

Use this structure when the Polytechnic assigns learners, classrooms, or records to named divisions.

3.12 diploma_no_div — Plan 6b

Visible hierarchy:

Department → Year → Semester

Example values:

Exact terminology hierarchy:

["Department", "Year", "Semester"]

The hidden Default division keeps tenant data compatible with division-scoped backend relationships.

3.13 custom — Plan 7

Visible hierarchy:

Group → Sub-Group

Example values:

Exact terminology hierarchy:

["Group", "Sub-Group"]

Custom organizations use generic terms such as Member, Instructor, Task, and Assessment.

4. Master terminology comparison

This table contains all 21 public terminology keys from TERMINOLOGY_MAP.

The six comparison columns use these representative structures:

• Engineering: engineering_with_div
• School: school_with_div
• Coaching: coaching
• Junior College: junior_college_with_div
• Diploma: diploma_with_div
• Custom: custom

Values are shown exactly as returned by the terminology map. A backticked null means the feature label is intentionally unavailable.

4.1 Variant consistency

Terminology values remain the same within each institution family except for the hierarchy array.

The hierarchy array changes when the division step is removed from a _no_div structure.

5. Division mode explained

5.1 with_divisions

Use with_divisions when users work with real named divisions or sections.

Expected behavior:

• The division or section selector is visible.
• Administrators create names such as A, B, and C.
• Learners can be assigned to a named division.
• Classrooms, attendance, fees, and examinations can be scoped to that division.
• The active terminology determines whether the UI says Division, Section, Batch, or Group.

Explicit with-division structures:

engineering_with_div
school_with_div
junior_college_with_div
diploma_with_div

5.2 without_divisions

Use without_divisions when the institution does not expose named divisions or sections.

Expected behavior:

• The UI hides the division selector.
• The visible hierarchy ends before the division level.
• The server creates a division node named Default with code DEF.
• Backend records can still use a stable division relationship.
• APIs and reports must not present Default as a real user choice.

Explicit no-division structures:

engineering_no_div
school_no_div
junior_college_no_div
diploma_no_div

5.3 Legacy structures

The following values remain valid for backward compatibility:

engineering
junior_college
diploma

They must not be silently rewritten for existing organizations.

For new registrations, prefer the explicit variant that matches the selected division mode.

5.4 Division behavior matrix

6. Terminology API

6.1 Get the active organization's terminology

GET /api/hierarchy/terminology

This authenticated, tenant-scoped endpoint returns:

• The active org_type.
• The active structure_type.
• The complete terminology object for that structure.

Example response for an Engineering organization:

{
  "structure_type": "engineering_with_div",
  "org_type": "engineering",
  "terminology": {
    "org_label": "College",
    "top_level": "Degree",
    "course": "Branch",
    "subject": "Course",
    "subject_code": "Course Code",
    "year": "Year",
    "period": "Semester",
    "division": "Division",
    "sub_batch": "Lab Batch",
    "student_id": "PRN",
    "student_id_long": "Permanent Registration Number",
    "teacher": "Faculty",
    "classroom": "Classroom",
    "add_student": "Register Student",
    "add_teacher": "Add Faculty",
    "hierarchy": [
      "Degree",
      "Department",
      "Year",
      "Semester",
      "Division"
    ],
    "assignment_label": "Assignment",
    "exam_label": "Examination",
    "id_card_title": "FACULTY IDENTITY CARD",
    "student_id_card_title": "STUDENT IDENTITY CARD",
    "forum_label": "Forum & Discussion",
    "parent_comm": "Student Communication"
  }
}

6.2 Frontend useTerminology() hook

The classroom frontend exposes useTerminology().

It fetches the endpoint through the hierarchy API and caches the result for 30 minutes.

import { useTerminology } from '@/features/classrooms/hooks/useTerminology';

export function AddLearnerButton() {
  const { data, isLoading } = useTerminology();

  if (isLoading) {
    return null;
  }

  return (
    <button type="button">
      {data?.terminology.add_student}
    </button>
  );
}

Use the returned terminology object for labels, headings, actions, placeholders, empty states, table columns, filters, and validation messages.

6.3 Get terminology comparison metadata

GET /api/hierarchy/terminology/all

This authenticated endpoint returns server-generated comparison metadata.

It is useful for organization settings and administrative comparison screens.

The active-organization endpoint remains authoritative for the current tenant's exact structure variant.

7. Academic hierarchy APIs

All hierarchy routes require authentication and use the authenticated user's organization_id as the tenant boundary.

7.1 Get the full hierarchy tree

GET /api/hierarchy/tree

The default response is nested:

{
  "tree": [
    {
      "_id": "example-root-id",
      "organization_id": "example-organization-id",
      "level_type": "degree",
      "name": "B.Tech",
      "code": "BTECH",
      "parent_id": null,
      "sort_order": 0,
      "is_active": true,
      "children": []
    }
  ],
  "terminology": {
    "top_level": "Degree"
  }
}

Request a flat array with:

GET /api/hierarchy/tree?flat=true

The flat response uses a nodes array.

7.2 Get direct children

GET /api/hierarchy/children/:parentId

The route returns only active direct children owned by the current organization.

{
  "children": [
    {
      "_id": "example-child-id",
      "level_type": "department",
      "name": "Computer Engineering",
      "code": "CE",
      "parent_id": "example-root-id",
      "sort_order": 0,
      "is_active": true
    }
  ]
}

7.3 Seed the default hierarchy

POST /api/hierarchy/seed

Use this once during onboarding after the organization structure has been finalized.

The operation is idempotency-protected:

• If no hierarchy exists, the server creates default nodes for the active preset structure.
• If any hierarchy nodes already exist, the server returns 409.
• Existing structures must be changed through hierarchy CRUD operations, not by seeding again.
• A custom organization should create its own Group and Sub-Group nodes because it has no fixed preset tree.

Example success response:

{
  "message": "Hierarchy seeded for \"engineering_with_div\" structure.",
  "total_nodes": 21
}

The exact count depends on the structure and seed defaults.

7.4 Related hierarchy mutation routes

Node creation is validated against the active structure plan.

8. AcademicHierarchy model

Every academic level is stored as a tenant-owned node.

Nodes reference their parent through parent_id, producing a tree.

8.1 Core fields

8.2 Allowed level_type values

degree
department
year
semester
division
sub_batch
standard
stream
course
batch
group
sub_group

8.3 Tree integrity rules

• Every node requires an organization_id.
• Every node requires an allowed level_type.
• Every node requires a non-empty name.
• Root nodes use parent_id: null.
• Child nodes reference another AcademicHierarchy record.
• Parent lookups are restricted to the current organization.
• Siblings under the same parent cannot share the same name.
• sort_order controls deterministic sibling ordering.
• Only active nodes are returned by normal tree and child queries.
• Deleting a node sets is_active to false for that node and its descendants.
• A sub_batch can be created only under a division.
• No-division plans create the hidden Default division below a standard or semester as appropriate.

9. UI implementation rules

9.1 Mandatory rule

Every organization-aware label must come from the terminology API. Do not infer labels from the URL, user role, or a frontend-only organization-type table.

This applies to:

• Sidebar navigation.
• Page titles.
• Form field labels.
• Button text.
• Input placeholders.
• Empty-state text.
• Search prompts.
• Table column titles.
• Filter names.
• Import templates.
• Export headings.
• Validation messages.
• ID-card headings.
• Forum headings.
• Communication modules.

9.2 Common label changes

9.3 Correct implementation pattern

const { data } = useTerminology();
const terms = data?.terminology;

return (
  <section>
    <h1>{terms?.classroom}</h1>
    <label>{terms?.student_id}</label>
    <button type="button">{terms?.add_student}</button>
  </section>
);

9.4 Incorrect implementation pattern

return (
  <section>
    <h1>Classroom</h1>
    <label>PRN</label>
    <button type="button">Register Student</button>
  </section>
);

The incorrect version leaks Engineering terminology into School, Coaching, Junior College, Diploma, and Custom tenants.

9.5 Null-safe behavior

When a terminology value is null:

• Do not render the related form field.
• Do not invent a replacement term.
• Do not submit an unsupported hierarchy value.
• Preserve the layout without an empty heading.
• Use feature and hierarchy metadata to determine whether the underlying capability is available.

For example, School and Coaching return sub_batch: null.

10. Registration and provisioning flow

10.1 Required sequence

1. The administrator selects an institution family.
2. The registration flow stores the normalized org_type.
3. For Engineering, School, Junior College, or Diploma, the administrator chooses whether real divisions are used.
4. The system computes the explicit structure_type.
5. The system stores division_mode.
6. The organization is created with the finalized identity fields.
7. The administrator authenticates as the Organization Admin.
8. The onboarding flow calls POST /api/hierarchy/seed once for a preset hierarchy.
9. The administrator reviews and edits the generated hierarchy nodes.
10. Frontend clients load terminology from GET /api/hierarchy/terminology.

10.2 Structure computation table

10.3 Default behavior when no explicit structure is supplied

The provisioning service defaults to:

10.4 Immutability rule

After organization creation:

• Do not expose editable org_type controls.
• Do not expose editable structure_type controls.
• Do not switch between _with_div and _no_div by changing one database field.
• Do not delete hidden default divisions to simulate a different structure.
• Do not recalculate structure from a later profile edit.

Changing the structure after records exist can invalidate hierarchy references used by learners, classrooms, attendance, fees, and examinations.

11. Quick reference cards

11.1 Engineering College

Key difference: supports optional Lab Batch splitting under divisions.

11.2 School

Key difference: uses Parent Communication and Student & Parent Board.

11.3 Coaching Institute

Key difference: uses Doubt Forum and the action Enroll Student.

11.4 Junior College

Key difference: optional sub-batches are labeled Batch.

11.5 Diploma / Polytechnic

Key difference: supports optional Lab Batch splitting and semester terminology.

11.6 Other / Custom Organization

Key difference: learner-facing terminology changes from Student to Member in actions and ID-card titles.

12. Developer integration checklist

12.1 Organization creation

• Accept only one of the six valid org_type values.
• Accept only one of the 13 valid structure_type values.
• Ensure the selected structure belongs to the selected organization family.
• Compute an explicit division variant for new Engineering organizations.
• Compute an explicit division variant for new School organizations.
• Compute an explicit division variant for new Junior College organizations.
• Compute an explicit division variant for new Diploma organizations.
• Store the matching division_mode.
• Keep legacy structure values for existing organizations only.
• Keep org_type and structure_type immutable after creation.

12.2 Hierarchy setup

• Authenticate before calling hierarchy routes.
• Seed the hierarchy only after structure selection is final.
• Handle 409 when hierarchy nodes already exist.
• Keep every node scoped to the authenticated organization.
• Use allowed level_type values only.
• Use parent_id: null only for root nodes.
• Preserve sibling sort_order.
• Hide storage-only Default divisions.
• Create sub-batches only below divisions.
• Soft-delete hierarchy nodes instead of removing tenant history directly.

12.3 Terminology integration

• Call GET /api/hierarchy/terminology after authentication.
• Cache through useTerminology() where available.
• Use org_label for institution-family wording.
• Use student_id and student_id_long for learner identifiers.
• Use teacher and add_teacher for educator labels and actions.
• Use assignment_label and exam_label for academic work.
• Use id_card_title and student_id_card_title without changing capitalization.
• Use forum_label and parent_comm in community features.
• Treat null as unavailable.
• Do not maintain a competing frontend terminology dictionary.

12.4 UI verification

• Engineering screens say PRN, Faculty, and Semester.
• School screens say Roll No, Teacher, Term, and Section.
• Coaching screens say Enrollment No, Mentor, Phase, and Batch.
• Junior College screens say Roll No, Lecturer, Term, and Division.
• Diploma screens say Enrollment No, Faculty, Semester, and Division.
• Custom screens say ID, Instructor, Phase, and Group.
• No-division screens omit the division or section selector.
• Hidden Default divisions never appear as user-selectable academic divisions.
• ID-card titles preserve the exact uppercase server values.
• Forum and communication labels match the tenant terminology.

13. Complete hierarchy-array appendix

14. Terminology-key appendix

15. Core rules checklist

1. org_type identifies the institution family.
2. structure_type identifies the precise academic hierarchy plan.
3. division_mode controls whether a division concept is visible.
4. _no_div structures still use a hidden Default division for storage.
5. Legacy structures remain valid for existing organizations.
6. New organizations should use explicit division variants where available.
7. GET /api/hierarchy/terminology is the authoritative UI-label source.
8. useTerminology() is the standard frontend integration hook.
9. GET /api/hierarchy/tree is the authoritative tenant hierarchy source.
10. POST /api/hierarchy/seed is a one-time onboarding operation.
11. Hierarchy nodes must always remain tenant-scoped.
12. org_type and structure_type must not be changed after creation.
13. Shared UI must never hardcode institution-specific academic words.
14. Real institution names must never be used in examples or reusable documentation.

16. Plain-language theory: how the system fits together

The tables above are the exact reference values. This section explains what those values mean and why Classgrid needs them.

The complete system can be understood as a chain:

Organization identity
        ↓
Academic structure selection
        ↓
Hierarchy nodes stored in the database
        ↓
Terminology returned by the backend
        ↓
Correct labels and choices shown in the frontend
        ↓
Learners, classrooms, attendance, fees, and examinations use the same structure

Each part has a different responsibility.

16.1 Organization identity

Organization identity is the broad institution family.

For example, a School and an Engineering College may both teach learners, record attendance, and conduct examinations, but they do not organize academics in the same way.

A School normally thinks in terms of:

Standard → Section

An Engineering College normally thinks in terms of:

Degree → Department → Year → Semester → Division

The org_type field tells Classgrid which institutional model should be used as the starting point.

16.2 Academic structure selection

The institution family alone is not enough.

Two Engineering Colleges may use the same terminology but handle divisions differently:

• One may divide every semester into A, B, and C.
• Another may have only one learner group and therefore need no visible division selector.

The structure_type records that precise choice.

It combines:

• The institution family.
• The hierarchy plan.
• The visible division behavior.
• The terminology profile.

16.3 Hierarchy nodes

The hierarchy is not stored as one long text value.

Each real academic item is stored as a node.

For example:

B.Tech
└── Computer Engineering
    └── First Year
        └── Semester 1
            └── Division A

In this example:

• B.Tech is one node.
• Computer Engineering is another node whose parent is B.Tech.
• First Year is another node whose parent is Computer Engineering.
• Semester 1 is another node whose parent is First Year.
• Division A is another node whose parent is Semester 1.

This parent-child model lets every tenant build its own real academic tree while still following the selected plan.

16.4 Terminology

Terminology changes the words shown to users.

The underlying software concept may be similar, but each institution expects familiar language.

For example, the learner identifier concept becomes:

• PRN for Engineering.
• Roll No for School.
• Enrollment No for Coaching.
• Roll No for Junior College.
• Enrollment No for Diploma.
• ID for Custom organizations.

Terminology is not decorative text. It is part of the institution profile and must be used consistently in forms, tables, menus, reports, cards, and messages.

16.5 Frontend behavior

The frontend does not decide that every institution uses semesters or divisions.

Instead, it asks the backend:

GET /api/hierarchy/terminology

The backend identifies the authenticated organization, reads its structure_type, loads the matching dictionary, and returns the correct labels.

The frontend then renders those labels.

16.6 Record behavior

The hierarchy does more than control labels.

Academic records can refer to hierarchy nodes so that data remains correctly scoped.

Examples include:

• A learner assigned to a Standard or Department.
• A classroom assigned to a Semester and Division.
• Attendance recorded for a Batch.
• An examination configured for a Term.
• A report filtered by Stream or Year.

This is why changing structure_type after records exist is dangerous: existing records already point to nodes created under the original structure.

16.7 Academic plans are not subscription plans

Plan numbers in this document describe academic hierarchy designs.

They do not describe:

• Product pricing.
• Subscription tiers.
• Storage limits.
• Learner limits.
• Purchased modules.
• Trial duration.
• Billing status.

An organization can use Plan 1a for its academic hierarchy while independently having any commercial subscription made available by Classgrid.

17. Detailed meaning of the organization settings

17.1 What org_type means

org_type is a permanent classification of the institution.

It answers:

What type of institution is this?

It is used when Classgrid needs to select institution-aware defaults, profiles, role language, and feature behavior.

It does not contain the institution's name.

For example:

{
  "name": "Example Engineering College",
  "org_type": "engineering"
}

Here, the name can be customized, but engineering remains the machine-readable identity.

17.2 What structure_type means

structure_type is the exact academic plan key.

It answers:

How is this institution's academic structure arranged?

It determines:

• Which terminology dictionary is returned.
• Which hierarchy levels are expected.
• Whether a visible division level exists.
• Which hierarchy boundaries should be validated.
• Which default tree should be seeded during onboarding.

It is a machine value, so it uses lowercase words and underscores, such as:

engineering_with_div

The user-facing interface should display a friendly description instead of showing this raw key to ordinary users.

17.3 What division_mode means

division_mode explicitly records the organization's division choice.

It answers:

Should users see and select real divisions or sections?

with_divisions means the institution has named groups at that level.

without_divisions means the institution does not want that level presented to users.

The field must agree with an explicit _with_div or _no_div structure.

17.4 What allow_sub_batches means

allow_sub_batches controls an optional split below a division.

It answers:

Can a visible division be separated into smaller practical or instructional groups?

For example:

Division A
├── Lab Batch A1
└── Lab Batch A2

It does not replace the main division.

It adds a smaller grouping beneath it.

17.5 What a legacy structure means

A legacy value is an older value that remains valid because existing organizations already use it.

Backward compatibility means newer code continues to understand old records instead of breaking them.

The legacy values are:

engineering
junior_college
diploma

They should remain readable and functional.

New registrations should use explicit division variants so the intended behavior is unambiguous.

17.6 What a custom structure means

custom is a general-purpose structure for an organization that does not match a predefined institution family.

It uses neutral words:

• Organization
• Group
• Sub-Group
• Member
• Instructor
• Task
• Assessment

Custom does not mean that every field and workflow becomes automatically configurable.

It means the organization starts with a generic hierarchy and terminology profile.

Any specialized workflow still needs explicit product support or configuration.

18. Academic hierarchy theory and vocabulary

18.1 Tree

A tree is a collection of connected hierarchy nodes.

It begins with one or more top-level nodes and expands downward.

The tree represents the institution's academic organization.

18.2 Node

A node is one stored academic item.

Examples:

• One Degree.
• One Department.
• One Standard.
• One Semester.
• One Division.
• One Course.
• One Batch.

A node stores its own name, code, type, parent, ordering, and active state.

18.3 Root node

A root is a node with no parent.

Its parent_id is null.

Examples:

• B.Tech can be an Engineering root.
• Class 8 can be a School root.
• Entrance Preparation can be a Coaching root.
• Science can be a Junior College root.
• Computer Engineering can be a Diploma root.
• Level 1 can be a Custom root.

18.4 Parent node

A parent is the node immediately above another node.

In this path:

Department → Year

The Department is the parent of the Year.

18.5 Child node

A child is the node immediately below another node.

In this path:

Standard → Section

The Section is a child of the Standard.

18.6 Sibling nodes

Siblings share the same parent.

For example:

Semester 1
├── Division A
├── Division B
└── Division C

The three divisions are siblings.

sort_order determines their display order.

18.7 Leaf node

A leaf is a node with no children.

It is normally the final visible selection in a path.

Examples include a Division, Section, Batch, or Sub-Group.

18.8 Path

A path is the complete route from a root to a selected node.

For example:

B.Tech → Computer Engineering → First Year → Semester 1 → Division A

The path tells Classgrid exactly where a learner, classroom, or academic record belongs.

18.9 Level

A level is a category of nodes at one stage of the hierarchy.

Semester is a level.

Semester 1 and Semester 2 are nodes at that level.

This difference is important:

• Level: the type or category.
• Node: one real value within that category.

18.10 Visible hierarchy

The visible hierarchy contains the choices users are expected to see.

For engineering_no_div, the visible hierarchy ends at Semester.

Users should not be asked to select the hidden storage division.

18.11 Storage hierarchy

The storage hierarchy can include technical nodes that keep database relationships consistent.

The hidden Default division is the main example.

It exists for backend consistency, not because the institution has a real division named Default.

18.12 Hierarchy label versus level_type

The display label and database type are related but not always identical strings.

For example, a School displays Section, while the underlying node type is division.

This allows shared backend logic to work while the user sees institution-appropriate language.

18.13 Hierarchy array

The terminology hierarchy array is an ordered description of the structure's labels.

For example:

["Degree", "Department", "Year", "Semester", "Division"]

Order matters because each item describes the next step in the academic path.

The array is not a list of actual institution records.

It describes the kinds of levels; actual nodes come from the hierarchy tree API.

19. Detailed meaning of every terminology key

19.1 org_label

org_label is the generic word used for the institution.

It can appear in headings, descriptions, setup messages, and organization-aware instructions.

Examples include College, School, Institute, Junior College, Polytechnic, and Organization.

It is not the organization's actual registered name.

19.2 top_level

top_level names the highest academic grouping used by that institution profile.

Examples include Degree, Standard, Course, Stream, Department, and Group.

It can be used in creation forms such as "Add Degree" or filter labels such as "Select Stream".

The actual top-level nodes must still come from the hierarchy tree.

19.3 course

course is the institution-specific word for the program or curricular grouping concept used by shared interfaces.

Depending on the institution, it becomes Branch, Class, Course, Stream, or Program.

It must not be confused with subject.

For Engineering and Diploma, a Branch describes the learner's program area, while a Course describes an individual taught subject.

19.4 subject

subject names the individual teaching unit.

It becomes:

• Course for Engineering and Diploma.
• Subject for School and Junior College.
• Topic for Coaching.
• Course for Custom.

Use it in classroom setup, syllabus screens, assignment filters, and examination configuration.

19.5 subject_code

subject_code is the label for the short code associated with a teaching unit.

Examples of possible values entered by an administrator are CS101, MATH-8, or TOPIC-01.

The terminology controls the field label, such as Course Code, Subject Code, or Topic Code.

It does not generate the code itself.

19.6 year

year is the label for the learner's academic progression stage.

It becomes Year, Class, Standard, or Level depending on the institution.

For Coaching, the terminology map also uses Year, commonly representing a target or program year.

The actual allowed values come from hierarchy or institution configuration.

19.7 period

period names the academic subdivision of time.

It becomes:

• Semester for Engineering and Diploma.
• Term for School and Junior College.
• Phase for Coaching and Custom.

This label can be used in navigation, filters, setup forms, attendance reports, and assessment configuration.

19.8 division

division names the principal learner grouping below the higher academic levels.

It becomes Division, Section, Batch, or Group.

The same key allows one shared component to show the correct institution-specific word.

For _no_div structures, the key can still exist even though the visible selector is hidden.

19.9 sub_batch

sub_batch names an optional smaller group below the main division concept.

It becomes Lab Batch, Batch, or Sub-Group where supported.

A null value means the terminology profile does not expose this optional concept.

The frontend should hide the feature instead of displaying the word null.

19.10 student_id

student_id is the short label for the learner's institution-facing identifier.

It becomes PRN, Roll No, Enrollment No, or ID.

Use it on forms, table columns, search fields, filters, and compact learner cards.

This is a label; the learner's actual identifier value is stored separately.

19.11 student_id_long

student_id_long is the expanded form of the learner identifier label.

Examples include Permanent Registration Number, Roll Number, Enrollment Number, and Identifier.

Use it where extra clarity is useful, such as detailed forms, help text, and formal reports.

Do not invent an expanded form on the frontend.

19.12 teacher

teacher is the educator-role label.

It becomes Faculty, Teacher, Mentor, Lecturer, or Instructor.

Use it in menus, profile headings, assignments, classroom ownership, filters, and empty states.

This terminology label does not by itself grant a user role or permission.

19.13 classroom

classroom names the teaching or collaboration space.

Most institution profiles use Classroom.

Custom organizations use Group.

The label does not define which hierarchy node owns the classroom; that relationship comes from classroom data and hierarchy references.

19.14 add_student

add_student is the complete action phrase for adding a learner.

It becomes Register Student, Add Student, Enroll Student, or Add Member.

Because it is already an action phrase, the UI should render it directly.

Do not prepend another verb and create text such as "Add Register Student".

19.15 add_teacher

add_teacher is the complete action phrase for adding an educator.

It becomes Add Faculty, Add Teacher, Add Mentor, Add Lecturer, or Add Instructor.

Use it on buttons, menu actions, page titles, and empty-state calls to action.

Permissions must still determine whether the current user can perform the action.

19.16 assignment_label

assignment_label names learner work assigned by an educator.

It becomes Assignment, Homework, Practice Set, or Task.

Use it in creation screens, submission status, due-date notices, and navigation.

Plural text should be produced carefully by the UI instead of changing the server's exact singular label blindly.

19.17 exam_label

exam_label names the institution's assessment concept.

It becomes Examination, Test, Mock Test, or Assessment.

Use it in schedules, creation forms, result publishing, analytics, and navigation.

The label does not determine the examination workflow by itself.

19.18 id_card_title

id_card_title is the exact heading printed on an educator identity card.

It is intentionally uppercase in the terminology map.

Examples include FACULTY IDENTITY CARD, TEACHER IDENTITY CARD, and MENTOR IDENTITY CARD.

The frontend should preserve the returned capitalization.

19.19 student_id_card_title

student_id_card_title is the exact heading printed on a learner or member identity card.

Standard educational profiles use STUDENT IDENTITY CARD.

Custom uses MEMBER IDENTITY CARD.

This key controls the title, not the data fields printed on the card.

19.20 forum_label

forum_label names the institution's community discussion area.

It becomes Forum & Discussion, Student & Parent Board, Doubt Forum, Discussion Forum, or Discussion Board.

Use it in navigation, page headings, empty states, and notifications.

The wording reflects the expected community context of each institution family.

19.21 parent_comm

parent_comm names the communication area associated with learners, parents, or members.

School uses Parent Communication.

Most student-focused profiles use Student Communication.

Custom uses Member Communication.

The label does not decide recipient permissions; the communication workflow must enforce those separately.

20. What each organization type contains

20.1 Engineering

Engineering represents a degree-based academic institution.

Its hierarchy contains these main concepts:

Degree
Department
Year
Semester
Division when enabled
Lab Batch when optionally enabled

The Degree is the broad qualification, such as B.Tech.

The Department identifies the academic discipline.

The Year identifies learner progression.

The Semester identifies the academic period.

The Division separates a semester group when the institution uses multiple groups.

The optional Lab Batch creates smaller practical groups below a division.

Engineering interfaces use PRN, Faculty, Assignment, and Examination.

20.2 School

School represents standard-based education.

Its hierarchy contains:

Standard
Section when enabled

The Standard is the main academic level, such as Class 8.

The Section separates learners in the same Standard into groups such as A and B.

When sections are not used, Classgrid creates a hidden Default division for backend storage.

School interfaces use Roll No, Teacher, Homework, Test, Student & Parent Board, and Parent Communication.

20.3 Coaching

Coaching represents course-oriented preparation or training.

Its declared terminology hierarchy contains:

Course
Year
Phase
Batch

The Course identifies the preparation program.

The Year can identify the target program year.

The Phase divides a long program into instructional stages.

The Batch identifies the learner group, such as a morning or evening batch.

Coaching does not use an Engineering-style Division plus Lab Batch model.

Its native group is already called Batch.

Coaching interfaces use Enrollment No, Mentor, Practice Set, Mock Test, and Doubt Forum.

20.4 Junior College

Junior College represents stream-based higher-secondary education.

Its hierarchy contains:

Stream
Standard
Division when enabled
Batch when optionally enabled

The Stream identifies the broad academic direction.

The Standard commonly identifies 11th or 12th.

The Division separates learners within the same Stream and Standard.

The optional Batch creates a smaller grouping where required.

Junior College interfaces use Roll No, Lecturer, Term, Assignment, Examination, and Discussion Forum.

20.5 Diploma / Polytechnic

Diploma represents department-based technical diploma education.

Its hierarchy contains:

Department
Year
Semester
Division when enabled
Lab Batch when optionally enabled

The Department identifies the technical discipline.

The Year and Semester identify progression and academic time.

The Division separates larger learner groups.

The optional Lab Batch separates practical groups.

Diploma interfaces use Enrollment No, Faculty, Assignment, Examination, and Forum & Discussion.

20.6 Other / Custom

Other represents an institution that does not fit the five predefined educational families.

Its generic hierarchy contains:

Group
Sub-Group

The organization decides what those groups represent in its own operation.

The neutral terminology avoids incorrectly calling every user a Student or every educator a Teacher.

Custom interfaces use ID, Instructor, Member, Task, Assessment, and Discussion Board.

21. Division, section, batch, and sub-batch theory

These words can sound interchangeable, but the platform uses them for different institutional meanings.

21.1 Division

A Division is a main learner group within the same academic placement.

Example:

Semester 1
├── Division A
└── Division B

Engineering, Junior College, and Diploma use the visible word Division.

21.2 Section

A Section is the School word for the shared division concept.

Example:

Class 8
├── Section A
└── Section B

The backend can still use level_type: "division" while the frontend displays Section.

21.3 Coaching Batch

A Coaching Batch is the native learner group for a course or program stage.

Example:

Entrance Preparation
├── Morning Batch
└── Evening Batch

It is not an optional lab split.

It is a principal part of Coaching organization.

21.4 Sub-batch

A sub-batch is a smaller group below a main Division.

Example:

Division A
├── Lab Batch A1
└── Lab Batch A2

It is commonly used for practical sessions where a full division is too large for one laboratory.

21.5 Hidden Default division

The hidden Default division exists only to preserve a consistent backend relationship.

Consider a School with one group in Class 8.

Users see:

Class 8

Storage can contain:

Class 8
└── Default

The learner is associated with the technical division node, but users are not asked to select it.

21.6 Why the backend keeps a hidden division

Without a stable division relationship, shared features would need two completely different storage patterns:

• One for institutions with divisions.
• Another for institutions without divisions.

The hidden node lets the backend keep one consistent relationship model.

This simplifies tenant-safe queries and avoids missing division references in shared workflows.

21.7 What hidden does not mean

Hidden does not mean deleted.

Hidden does not mean inactive.

Hidden does not mean optional to the backend.

It means the node is valid storage data but should not be presented as a real user choice.

22. API and HTTP vocabulary explained

22.1 API

API means Application Programming Interface.

It is a defined way for one part of the system to request data or actions from another part.

In Classgrid, the frontend calls backend APIs.

22.2 Endpoint

An endpoint is one specific API address.

Example:

/api/hierarchy/terminology

This endpoint has one clear responsibility: return terminology for the authenticated organization.

22.3 HTTP method

The method describes the type of operation.

The path and method together identify the operation.

GET /api/hierarchy/tree and POST /api/hierarchy/tree would not mean the same thing.

22.4 Request

A request is the message sent by a client to the backend.

It can contain:

• A method.
• A URL.
• Authentication information.
• URL parameters.
• Query parameters.
• A JSON body.

22.5 Response

A response is the message returned by the backend.

It normally contains:

• An HTTP status code.
• JSON data or an error object.
• Optional headers.

22.6 JSON

JSON is a structured text format used to exchange data.

Example:

{
  "org_type": "school",
  "structure_type": "school_with_div"
}

Property names appear on the left, and their values appear on the right.

22.7 Authentication

Authentication proves which user is making the request.

Hierarchy routes require authentication.

The backend uses the authenticated user to determine the correct organization.

22.8 Tenant-scoped

Tenant-scoped means a request can access only the current organization's data.

If two organizations both have a node named Class 8, each node still belongs to a different organization_id.

The API must never mix their records.

22.9 Path parameter

A path parameter is a value inside the URL path.

Example:

GET /api/hierarchy/children/:parentId

The real request replaces :parentId with a node ID.

22.10 Query parameter

A query parameter modifies how data is returned.

Example:

GET /api/hierarchy/tree?flat=true

Here, flat=true asks for a flat node array instead of a nested tree.

22.11 Request body

A request body contains data sent to create or update something.

Example node-creation body:

{
  "level_type": "division",
  "name": "A",
  "code": "A",
  "parent_id": "example-parent-id",
  "sort_order": 0
}

22.12 Status code

A status code gives the broad result of the request.

For hierarchy seeding, 409 means nodes already exist and the one-time seed must not run again.

22.13 One-time operation

A one-time operation is intended to run once during a lifecycle stage.

Hierarchy seeding is a one-time onboarding operation.

After nodes exist, administrators use normal create, update, and delete routes.

22.14 Validation

Validation checks whether a request follows the rules before data is stored.

Examples include:

• level_type must be allowed.
• name is required.
• The parent must belong to the same organization.
• A sub-batch must be placed below a division.
• A duplicate sibling name must be rejected.

23. Backend and database vocabulary explained

23.1 Model

A model is the application's representation of one kind of stored record.

Organization and AcademicHierarchy are models.

23.2 Schema

A schema defines which fields a record can contain and the rules for those fields.

For example, the Organization schema defines the accepted org_type values.

23.3 Document

A document is one stored record created from a model.

One hierarchy node is one AcademicHierarchy document.

23.4 Field

A field is one named value inside a document.

Examples include name, code, level_type, and parent_id.

23.5 String

A String is text.

Examples include "B.Tech", "Semester 1", and "engineering_with_div".

23.6 Boolean

A Boolean has only two values:

true
false

is_active and allow_sub_batches are Boolean fields.

23.7 Number

A Number stores a numeric value.

sort_order, student_count, and sub_batch_capacity are numeric fields.

23.8 Object ID

An Object ID is the unique database identifier of a document.

organization_id identifies the owning organization.

parent_id identifies the parent hierarchy node.

Users normally see names and codes instead of Object IDs.

23.9 Enum

An enum is a fixed list of accepted values.

The org_type, structure_type, division_mode, and level_type fields use enums.

An enum prevents arbitrary misspelled values from being stored through normal model validation.

23.10 Required field

A required field must be present before the document can be saved.

Hierarchy nodes require organization_id, level_type, and name.

23.11 Default value

A default is used when a value is not supplied.

Examples include:

• code defaults to an empty string.
• sort_order defaults to 0.
• is_active defaults to true.
• student_count defaults to 0.

23.12 null

null means no value is assigned.

A root node has parent_id: null because it has no parent.

A terminology field can be null because that concept is unavailable for the profile.

The meaning depends on the field context.

23.13 Reference

A reference connects one document to another document by ID.

parent_id references another hierarchy node.

organization_id references the owning organization.

23.14 Index

An index helps the database find records efficiently.

Hierarchy indexes support common lookups by organization, level type, and parent.

23.15 Unique rule

A unique rule prevents duplicate values for a defined combination.

Hierarchy nodes cannot have duplicate names under the same parent in the same organization.

The same name can still exist under a different parent or in a different organization.

23.16 Timestamp

Timestamps record when data was created and updated.

The hierarchy model automatically stores createdAt and updatedAt.

23.17 Soft delete

A soft delete marks data inactive instead of physically removing it immediately.

Hierarchy deletion sets is_active to false for the selected node and its descendants.

Normal tree queries return only active nodes.

23.18 Descendant

A descendant is any node below another node, not only a direct child.

If a Department is deactivated, its Years, Semesters, and Divisions are descendants.

23.19 Denormalized value

A denormalized value is a copied or precomputed value stored to make common reads faster.

student_count is described as a denormalized dashboard count.

The authoritative learner records still require correct synchronization with that count.

23.20 Tenant boundary

A tenant boundary is the rule that keeps one organization's data separate from every other organization.

Every hierarchy query must include the current organization_id.

An ID alone must not be trusted without verifying its organization ownership.

24. Frontend terminology theory

24.1 Dynamic label

A dynamic label is loaded from data instead of written permanently into the component.

For example:

<label>{terms.student_id}</label>

The same component can display PRN, Roll No, Enrollment No, or ID.

24.2 Hardcoded label

A hardcoded label is written directly into reusable source code.

Example:

<label>PRN</label>

This is wrong in a shared learner form because School and Coaching organizations do not use PRN terminology.

24.3 Hook

A React hook is a reusable function that gives a component stateful data or behavior.

useTerminology() loads and caches the active organization's terminology.

Components use the hook instead of repeating API-fetching logic.

24.4 Query cache

A query cache temporarily stores a successful API result in the frontend.

Terminology changes rarely, so the hook keeps it fresh for 30 minutes before treating it as stale.

Caching reduces repeated requests while users navigate between screens.

24.5 Loading state

The loading state exists while the terminology request is still in progress.

The interface should avoid briefly showing incorrect Engineering defaults during this state.

It can show a skeleton, reserve space, or delay the terminology-dependent content.

24.6 Error state

The error state exists when terminology could not be loaded.

The interface should not silently guess the institution type.

It should use an approved safe fallback or show a recoverable error according to the product design.

24.7 Fallback

A fallback is text used only when the expected dynamic value is unavailable.

Fallbacks should be generic and intentional.

They must not make a School look like an Engineering College.

24.8 Null-safe rendering

Null-safe rendering checks whether a value exists before using it.

Example:

{terms.sub_batch ? <SubBatchField label={terms.sub_batch} /> : null}

This hides the field when sub_batch is null.

24.9 Label versus permission

A terminology label controls wording.

A permission controls whether a user can view or perform an action.

Displaying Add Faculty does not automatically authorize the current user to add Faculty.

Both terminology and permission checks are required.

24.10 Label versus feature availability

A label does not guarantee that a commercial or optional module is enabled.

For example, exam_label: "Examination" defines the correct word.

Subscription, feature, and permission checks still determine whether examination functionality is available to that user.

25. Organization lifecycle theory

25.1 Registration

Registration collects the institution identity and initial setup choices.

The most important structural selections happen here because they become permanent organization fields.

25.2 Normalization

Normalization converts user input into accepted machine values.

For example, spaces can be converted to underscores and values can be converted to lowercase before validation.

25.3 Provisioning

Provisioning creates the organization and its initial administrative environment.

It stores the normalized org_type, resolved structure_type, and division_mode.

Provisioning is broader than hierarchy seeding.

25.4 Seeding

Seeding creates a useful starting hierarchy for a preset structure.

It saves administrators from manually creating every first node.

Seeded names are starting defaults and can be adjusted through supported hierarchy operations.

25.5 Configuration

Configuration is the stage where administrators review the hierarchy and add the institution's real academic values.

Examples include adding another Department, changing a code, or creating additional Divisions.

25.6 Daily use

After setup, daily workflows read the organization identity, hierarchy, and terminology.

Learner registration, classroom creation, attendance, examinations, and reporting should use the same academic structure.

25.7 Maintenance

Maintenance includes safe changes within the selected structure.

Examples include:

• Adding a new Division.
• Renaming a Batch.
• Reordering Departments.
• Soft-deleting an unused hierarchy branch.

Maintenance does not include changing the organization into another institution family.

25.8 Migration

A migration is a controlled transformation of existing data from one structure to another.

It may require remapping:

• Hierarchy nodes.
• Learner placement.
• Classroom references.
• Attendance scope.
• Fee records.
• Examination and result records.
• Reports and exports.

This is why an organization cannot safely change structure_type through a simple dropdown after launch.

26. End-to-end examples

26.1 Engineering with divisions

An administrator selects:

org_type: engineering
division choice: with divisions

Classgrid stores:

structure_type: engineering_with_div
division_mode: with_divisions

The hierarchy can contain:

B.Tech
└── Computer Engineering
    └── First Year
        └── Semester 1
            ├── Division A
            └── Division B

The terminology API returns words such as:

PRN
Faculty
Semester
Division
Assignment
Examination

A learner form shows PRN and Division selectors.

A classroom can be associated with Semester 1 and Division A.

26.2 School without sections

An administrator selects:

org_type: school
division choice: without sections

Classgrid stores:

structure_type: school_no_div
division_mode: without_divisions

Users see:

Class 8

The backend stores:

Class 8
└── Default

The terminology API returns words such as:

Roll No
Teacher
Term
Homework
Test
Parent Communication

The learner form does not show a Section selector.

Records can still reference the hidden default division internally.

26.3 Coaching

An administrator selects:

org_type: coaching
structure_type: coaching

The declared terminology hierarchy is:

Course → Year → Phase → Batch

An example academic path is:

Entrance Preparation → 2026 → Phase 1 → Morning Batch

The terminology API returns words such as:

Enrollment No
Mentor
Practice Set
Mock Test
Doubt Forum

The interface uses Batch as the primary learner group and does not ask for an Engineering Division.

26.4 Junior College without divisions

An administrator selects:

org_type: junior_college
division choice: without divisions

Classgrid stores:

structure_type: junior_college_no_div
division_mode: without_divisions

The visible path can be:

Science → 11th → Batch 1

The storage tree also contains a hidden Default division below the Standard where required by backend relationships.

The interface uses Roll No, Lecturer, Term, and Examination.

26.5 Diploma with divisions

An administrator selects:

org_type: diploma
division choice: with divisions

Classgrid stores:

structure_type: diploma_with_div
division_mode: with_divisions

An example path is:

Computer Engineering → First Year → Semester 1 → Division A

The interface uses Enrollment No, Faculty, Semester, Division, and Lab Batch terminology.

26.6 Custom organization

An administrator selects:

org_type: other
structure_type: custom

An example hierarchy is:

Level 1
└── Group A

The terminology API returns neutral words such as:

Organization
Program
Level
Group
Sub-Group
ID
Instructor
Member
Task
Assessment

The organization can use generic groups without presenting itself as a School or College.

27. Administrator decision guide

Before registration, answer these questions in order.

27.1 Institution identity

Which description matches the institution?

• Degree-based Engineering College.
• Standard-based School.
• Course and Batch-based Coaching Institute.
• Stream-based Junior College.
• Department-based Diploma or Polytechnic.
• Another organization requiring generic groups.

This answer selects org_type.

27.2 Division requirement

Does the institution have multiple named learner groups at the division level?

Examples include:

• Division A and Division B.
• Section A and Section B.

If yes, choose the with-division structure.

If no, choose the no-division structure where that variant exists.

27.3 Sub-batch requirement

Does one visible division need smaller practical groups?

If yes, enable sub-batches for a compatible structure.

Do not use sub-batches as a replacement for the main division level.

27.4 Terminology confirmation

Before finalizing, confirm that the expected words match the institution:

• Learner ID.
• Educator title.
• Academic period.
• Main grouping.
• Assignment label.
• Examination label.

27.5 Final confirmation

Confirm the selected identity and structure before records are created.

The confirmation should explain that these values cannot be changed through normal organization settings later.

28. Frequently asked questions

29. Final Classgrid Hierarchy

Platform Terminology Reference — how labels change per organization type

This is the final Classgrid hierarchy terminology reference for the five standard institution families.