SETUP¶
The main user is an "admin". The "setup" consists in a series of steps in which the admin configures the school on the system. The setup ends when all the steps are completed.
The setup is split in 2 main parts:
- School configuration (required) - all user stories below are refined and complete for this
- People importing (required) - user stories to be implemented later on, after the first step
As long as the setup isn't complete, the admin can't navigate the rest of the application. The admin should be able to start were it left returning to the setup.
HIGH LEVEL OVERVIEW¶
The admin sets the following on each step
STEP 1: School configuration¶
- School identity
- Academic Year (Terms, Closing Periods, Extra Periods)
- Departments (name, homeroom role, scheduling mode)
- Grades inside departments (names, codes)
STEP 2: People imports¶
- Import students
- Import teachers
- Import staff
USER STORIES¶
US1: Create School Identity¶
As a Admin I want to define the School Identity during the initial platform setup,so that the system establishes the primary institutional context that governs all subsequent configurations.
Who Can Do This¶
Admin
Acceptance Criteria¶
Scenario 1: School Identity setup completion gate Given the platform is in initial setup flow When the Admin tries to proceed to the next setup step Then the system allows progression only if School Identity is defined (required fields provided); otherwise keeps the Admin in the School Identity step reporting missing or invalid fields.
Fields associated with the school¶
legal_name (R) operational_name (R) legal_country (R) main_address (R) timezone (R) primary_language (R) school_type (R) : [state-approved / recognised / international / state / private ] tax_id (R) [piva]
US2: Create Academic Year¶
As an Admin, I want to create a new Academic Year by defining its identity and calendar structure (dates, terms, closing and extra periods), so that the school operates within a coherent temporal and academic framework.
Who Can Do This¶
- Admin
Acceptance Criteria¶
Scenario 1: Calendar period scoped inside Academic Year Given an Admin defines one period (=Terms/ClosingPeriods/ ExtraPeriods) for an Academic Year When the period is saved Then the system ensures that each period’s date range is fully contained within AcademicYear.start_date and AcademicYear.end_date of that Academic Year, otherwise returns an error message.
Scenario 2: Prevent conflicting non-instructional period overlaps Given an Academic Year contains one or more periods (Terms, ClosingPeriods, ExtraPeriods) When the Admin defines a new period within that Academic Year Then the system enforces that are no periods overlaps
Scenario 3: Prevent duplicate period definition within Academic Year Given an Academic Year already contains a period of the same type with the same name When the Admin defines another identical period Then the system prevents duplicates within that Academic Year
Scenario 4: Terms are ordered and sequential within Academic Year Given an Academic Year has multiple Terms When the Admin defines or updates the Terms list Then the system stores an explicit ordinal_position for each Term and enforces that Term numbering is sequential within the same Academic Year. Periods are ordered by start date.
**Scenario 5: Academic Year setup completion gate Given the platform is in the setup flow When the Admin attempts to proceed to the next step Then the system allows progression only if Academic Year is defined (required fields provided); otherwise keeps the Admin in the Academic Year step reporting missing or invalid fields. The academic year becomes the Active year.
Fields associated with entities¶
AcademicYear name (R) start_date (R) end_date (R) status (R) (Draft / Active / Archived / Deleted -> default: Draft, but here we set it to active since it's the first and only) description (O)
Term (O) name start_date end_date ordinal_position
ClosingPeriod (O) name start_date end_date
ExtraPeriod (O) name start_date end_date
US3: Create Departments¶
As a Admin, I want to create Departments during the school setup phase, so that I can define the school’s organizational structure for the Academic Year.
Who Can Do This¶
- Admin
Acceptance Criteria¶
Scenario 1: Academic Year requires at least one Department Given an Academic Year exists When the Admin attempts to proceed to the next setup phase Then the system requires at least one Department exists within that academic year
Scenario 2: Department identity must be unique within the same Academic Year Given an Academic Year already contains a Department with the same name When the Admin creates another Department with an identical name within the same Academic Year Then the system prevents duplication within that academic year
Scenario 3: Department ordinal_position must be unique and sequential within the same Academic Year Given an Academic Year contains multiple Departments When the Admin assigns an ordinal_position Then the system ensures that department ordering is unique and sequential within that academic year
Scenario 4: Prevent invalid configuration combination (homeroom_role + scheduling_mode) Given the Admin is setting the homeroom_role + scheduling_mode combinations When the Admin sets an invalid combination of homeroom_role and scheduling_mode (homeroom_role = None + scheduling_mode = Homeroom-derived) Then the system prevents the creation because the configuration is not allowed
Scenario 5: Department setup completion gate Given the platform is in the setup flowWhen the Admin attempts to proceed to the next stepThen the system allows progression only if at least one Department is defined for the Academic Year and if Department is defined (required fields provided); otherwise keeps the Admin in the Department step reporting structural inconsistencies.
Notes¶
Departments are created within a specific Academic Year. A Department requires configuration fields that define how the organization and scheduling will work in that Department. Homeroom_role and scheduling_mode are Department configuration fields selected during Department creation A valid combinations matrix for homeroom_role and scheduling_mode is needed
Fields associated with entities¶
Department name (R) homeroom_role (R) (none, administrative, scheduling-active) scheduling_mode (R) (homeroom-derived, track-and-block) ordinal_position (R) AcademicYear (R)
Invalid combination for homeroom role and scheduling mode(*)¶
homeroom_role = None scheduling_mode = Homeroom-derived
US5: Create Grade¶
As an Admin, I want to create a Grade within a Department for a specific Academic Year, so that I can define the academic levels on which curriculum and tracks are configured.
Who Can Do This¶
- Admin
Acceptance Criteria¶
Scenario 1: Prevent duplicate Grade names within the same Department and Academic Year Given a Department already contains a Grade with the same name When the Admin attempts to create another Grade with the same name in that Department Then the system blocks the creation and displays an error indicating that Grade names must be unique within the same Department
Scenario 2: Grade ordinal_position must be unique and sequential within the DepartmentGiven a Department already contains Grades with ordinal_position valuesWhen the Admin assigns an ordinal_position to a new Grade within that DepartmentThen the system ensures that ordinal_position is uniqueand enforces that ordering remains sequential within the Department (1, 2, 3, …)
Scenario 3: Grade setup completion gate Given the platform is in the setup flow When the Admin attempts to proceed to the next step Then the system allows progression only if at least one Grade for Department is defined and if Grade is defined (required fields provided); otherwise keeps the Admin in the Grade step reporting structural inconsistencies.
Fields associated with entities¶
- grade_name (R)
- department (inherited)
- academic_year ()
- ordinal_position (R)