SKOLE-STUD — Student Management Module

Module ID: SKOLE-STUD | Version: 1.0 | Status: Active
Products: Teacher App (assigned students) · Web App (full CRUD) · Parent App (own child profile)

1. Overview

Field	Value
Module Name	Student Management
Module Code	STUD
Business Value	Central student registry powering all other modules. Every attendance record, diary entry, activity, and request traces back to a student. Admin manages lifecycle; teachers view their assigned students.

Scope In

Full student CRUD for web admin (create, update, archive)
Teacher: view list of assigned students, view individual student detail
Parent: view their child’s profile (read via Auth response)
Guardian and address management per student

Scope Out

Academic transcripts / grades
Timetable assignment

2. Requirements

Functional Requirements (FR)

What the module must DO — actions, behaviors, and outcomes.

SKOLE-STUD-FR001: The module shall allow admins to create student records with comprehensive personal, academic, and contact information.
SKOLE-STUD-FR002: The module shall enable admins to update student info and change their enrollment status.
SKOLE-STUD-FR003: The module shall allow admins to archive students, capturing both an archive reason and the date.
SKOLE-STUD-FR004: The module shall provide student filtering by grade, status, and name.
SKOLE-STUD-FR005: The module shall allow teachers to view only their list of assigned students.
SKOLE-STUD-FR006: The module shall enable admins to manage student guardian and address records.
SKOLE-STUD-FR007: The module shall allow admins to reset a student’s parent PIN for application access.
SKOLE-STUD-FR008: The module shall enforce that a student’s roll number is unique within its school.

Non-Functional Requirements (NFR)

How well the module must do it — performance, security, and reliability.

SKOLE-STUD-NFR001: The module shall perform multi-tenant isolation by scoping all student queries strictly to the skole_id.
SKOLE-STUD-NFR002: The module shall behave predictably by allowing archived students to be filtered out of default lists to maintain registry cleanliness.
SKOLE-STUD-NFR003: The module shall ensure that student detail retrieval is performant to support real-time application features like attendance marking.

Constraints

Rules and boundaries — tech choices and platform restrictions.

C001: We must treat the student registry as the core dependency for all other academic modules (Attendance, Diary, Activities).
C002: We must use a junction table (staff_student) for staff assignments to support many-to-many relationships where needed.

3. Sub-modules / Backlog

ID	Sub-module	Priority	Status	Estimate	Linked FR
`SKOLE-STUD-SM001`	Student CRUD (web admin)	P0	Done	4d	FR001–FR004
`SKOLE-STUD-SM002`	Teacher student view	P0	Done	2d	FR005–FR006
`SKOLE-STUD-SM003`	Guardian management	P1	Done	1d	FR007
`SKOLE-STUD-SM004`	Address management	P1	Done	1d	FR008
`SKOLE-STUD-SM005`	PIN reset	P1	Done	0.5d	FR009
`SKOLE-STUD-SM006`	Archive workflow	P1	Done	1d	FR003

4. Logical Implementation

Student Status State Machine

[registered] ──enroll──→ [active]
[active] ──deactivate──→ [inactive]
[active|inactive] ──archive──→ [archived]  (captures archive_reason, archive_date)

Teacher Assigned Students Flow

GET /teachers-app/students?skole_id=
  ├─ Query staff_student WHERE staff_id = jwt.sub
  ├─ Extract student_id list
  └─ Query students WHERE id IN [...] AND skole_id = skole_id

Admin Student Listing

GET /web-app/students?skole_id=&grade=&status=&name=
  ├─ Dynamic filter build (Prisma where clause)
  └─ Return paginated student list with address + guardian

5. UI Requirements

Teacher App

ID	Screen	Route	Description
`SKOLE-STUD-UI001`	StudentsScreen	`/students`	List of teacher’s assigned students with search
`SKOLE-STUD-UI002`	StudentDetailScreen	`/students/:id`	Full student profile with attendance summary, diary, activities tabs

Components:

ID	Component	Props
`SKOLE-STUD-UC001`	`StudentCard`	`student`, `onPress`
`SKOLE-STUD-UC002`	`StudentSearchBar`	`value`, `onChange`
`SKOLE-STUD-UC003`	`StudentProfileHeader`	`student`
`SKOLE-STUD-UC004`	`StudentInfoTab`	`student`, `guardian`, `address`

Web App

ID	Screen	Route	Description
`SKOLE-STUD-UI003`	Students Page	`/:skoleId/students`	Table with filters, create/edit/archive actions
`SKOLE-STUD-UI004`	Student Detail	`/:skoleId/students/:id`	Full profile page with tabbed edit forms

Parent App

ID	Screen	Route	Description
`SKOLE-STUD-UI005`	ChildProfileScreen	`/child-profile`	Read-only child profile from auth response data
`SKOLE-STUD-UI006`	StudentProfileScreen	`/child-selection`	Detailed student info view

6. Conditional Expressions

ID	Expression	Trigger	True Action	False Action
`SKOLE-STUD-CE001`	`student_status === 'archived'`	Student list default query	Exclude (unless filter set)	Include
`SKOLE-STUD-CE002`	`student_status === 'inactive'`	StudentCard render	Grey out card	Normal
`SKOLE-STUD-CE003`	`roll_no !== null`	Student ID display	Show roll_no	Show temp_roll_no
`SKOLE-STUD-CE004`	`student.major_ailment !== null`	Profile header	Show medical alert icon	Hide icon
`SKOLE-STUD-CE005`	`user.type === 'staff'`	Student detail screen	Read-only, no edit	—
`SKOLE-STUD-CE006`	`user.type === 'user' (admin)`	Student detail screen	Show edit, archive, reset PIN	Read-only

7. Internal Module Connections

Direction	Module	Data / Event	Condition
STUD → AUTH	Auth	Children list returned on parent login	On auth
ATND → STUD	Attendance	`student_id` FK in attendance records	Every record
DIRY → STUD	Diary	`student_id` FK in diary entries	When student-specific
WRIT → STUD	Write-To	`student_id` FK in requests	Every request
STAF → STUD	Staff	`staff_student` junction table links staff to students	On assignment

8. Database Tables

ID	Table	Role
`SKOLE-STUD-TB001`	`students`	Core student records
`SKOLE-STUD-TB002`	`student_address`	Home/permanent addresses
`SKOLE-STUD-TB003`	`student_guardian`	Guardian info per student
`SKOLE-STUD-TB004`	`staff_student`	Staff-to-student assignment mapping

9. API Endpoints Summary

ID	Method	Route	Auth	Description
PARENT-01	GET	`/parent-app/student`	JWT (parent)	List parent’s children
PARENT-02	GET	`/parent-app/student/:id`	JWT (parent)	Get child detail
PARENT-03	PUT	`/parent-app/student/:id`	JWT (parent)	Update child info
PARENT-04	DELETE	`/parent-app/student/:id`	JWT (parent)	Archive/remove child
PARENT-05	GET	`/parent-app/student/search`	JWT (parent)	Search children
TEACHER-01	GET	`/teachers-app/student`	JWT (staff)	List assigned students
TEACHER-02	GET	`/teachers-app/student/:id`	JWT (staff)	Get student detail
TEACHER-03	PUT	`/teachers-app/student/:id`	JWT (staff)	Update student
TEACHER-04	POST	`/teachers-app/student`	JWT (staff)	Create student
ADMIN-01	GET	`/web-app/student`	JWT (user)	List all students
ADMIN-02	GET	`/web-app/student/:id`	JWT (user)	Get student detail
ADMIN-03	POST	`/web-app/student`	JWT (user)	Create student
ADMIN-04	PUT	`/web-app/student/:id`	JWT (user)	Update student
ADMIN-05	DELETE	`/web-app/student/:id`	JWT (user)	Delete student
ADMIN-06	POST	`/web-app/student/bulk-upload`	JWT (user)	Bulk upload students

10. Detailed Endpoint Documentation (12-Section Format)

PARENT-01: List Parent’s Children

Section 1: Endpoint Summary

Returns all children/students linked to a parent account. Essential for multi-child family support, providing quick access to all enrolled children.

Section 2: HTTP Details

HTTP Method: GET
Endpoint URL: /parent-app/student
Content-Type: application/json
Authentication: JWT Bearer Token (Parent)
Rate Limit: 100 requests per minute

Section 3: Path Parameters

None

Section 4: Query Parameters

Parameter	Type	Required	Default	Description	Example
status	String	No	active	Filter by status (active, inactive, archived)	`active`
class	String	No	-	Filter by class/grade	`10`
take	Integer	No	10	Records per page	`20`
skip	Integer	No	0	Pagination offset	`0`

Section 5: Request Body Schema

Empty (GET request)

Section 6: Response Schema (Success - 200)

{
  "status": "success",
  "message": "Students retrieved",
  "data": {
    "students": [
      {
        "id": "UUID",
        "skole_id": "UUID",
        "first_name": "Arjun",
        "last_name": "Kumar",
        "roll_no": "12",
        "class": "10",
        "section": "A",
        "status": "active",
        "dob": "2010-05-15",
        "gender": "Male",
        "major_ailment": null,
        "guardian": {
          "father_name": "Rajesh Kumar",
          "mother_name": "Priya Kumar",
          "emergency_contact": "9876543210"
        },
        "address": {
          "street": "123 Main St",
          "city": "Bangalore",
          "state": "Karnataka",
          "postal_code": "560001"
        },
        "created_at": "2024-01-15T10:30:45.000Z"
      }
    ],
    "pagination": {
      "total": 2,
      "take": 10,
      "skip": 0,
      "pages": 1
    }
  }
}

Section 7: Error Responses

401 - Unauthorized

{
  "status": "error",
  "code": "UNAUTHORIZED",
  "message": "Invalid or expired JWT token"
}

404 - No Students

{
  "status": "success",
  "message": "No students found",
  "data": {
    "students": [],
    "pagination": {"total": 0}
  }
}

Section 8: Implementation Examples

JavaScript:

const getParentChildren = async (token, filters = {}) => {
  const params = new URLSearchParams({
    status: filters.status || 'active',
    take: filters.take || 10,
    skip: filters.skip || 0
  });

  const response = await fetch(
    `https://api.skole.com/v1/parent-app/student?${params}`,
    {
      method: 'GET',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      }
    }
  );

  const data = await response.json();
  if (data.status === 'success') {
    console.log(`Found ${data.data.students.length} children`);
    return data.data.students;
  }
  throw new Error(data.message);
};

// Usage
const children = await getParentChildren(token, { status: 'active' });

Python:

import requests

def get_parent_children(token: str, status: str = 'active') -> list:
    url = 'https://api.skole.com/v1/parent-app/student'
    headers = {
        'Authorization': f'Bearer {token}',
        'Content-Type': 'application/json'
    }
    params = {
        'status': status,
        'take': 10,
        'skip': 0
    }
    
    response = requests.get(url, headers=headers, params=params, timeout=10)
    data = response.json()
    
    if data['status'] == 'success':
        return data['data']['students']
    raise Exception(data['message'])

# Usage
children = get_parent_children(token)

cURL:

curl -X GET \
  'https://api.skole.com/v1/parent-app/student?status=active&take=10' \
  -H 'Authorization: Bearer YOUR_TOKEN_HERE' \
  -H 'Content-Type: application/json'

Section 9: Database Context

Primary Table: students Join Tables: student_guardian, student_address Query Pattern:

SELECT s.*, sg.*, sa.* 
FROM students s
LEFT JOIN student_guardian sg ON s.id = sg.student_id
LEFT JOIN student_address sa ON s.id = sa.student_id
WHERE s.parent_id = ? AND s.skole_id = ? AND s.status = ?
ORDER BY s.created_at DESC
LIMIT ? OFFSET ?

Indices: parent_id, skole_id, status

Section 10: Business Logic & Validations

Validation:

JWT must contain valid parent_id
Query must be scoped to parent’s school (skole_id)
Status filter validates against enum: [active, inactive, archived]

Business Logic:

Extract parent_id from JWT
Load parent’s skole_id for school isolation
Build dynamic WHERE clause based on filters
Query students with guardian and address joins
Return paginated results

GET /parent-app/student/:id - Get specific child detail
PUT /parent-app/student/:id - Update child info
GET /parent-app/student/search - Search children

Section 12: Response Summary Table

Status	Scenario	Error Code	Message
200 ✅	Success	-	Students retrieved
200 ✅	No students	-	No students found
401 ❌	Unauthorized	UNAUTHORIZED	Invalid JWT

PARENT-02: Get Child Detail

Section 1: Endpoint Summary

Fetches complete profile of a specific child including personal info, guardians, address, and academic details.

Section 2: HTTP Details

HTTP Method: GET
Endpoint URL: /parent-app/student/:id
Authentication: JWT Bearer Token (Parent)

Section 3: Path Parameters

Parameter	Type	Required	Description
id	UUID	Yes	Student ID

Section 5: Request Body Schema

Empty (GET request)

Section 6: Response Schema (Success - 200)

{
  "status": "success",
  "data": {
    "id": "UUID",
    "skole_id": "UUID",
    "first_name": "Arjun",
    "last_name": "Kumar",
    "roll_no": "12",
    "class": "10",
    "section": "A",
    "status": "active",
    "dob": "2010-05-15",
    "gender": "Male",
    "blood_group": "O+",
    "major_ailment": null,
    "student_photo_url": "https://cdn.skole.com/students/uuid.jpg",
    "guardian": {
      "father_name": "Rajesh Kumar",
      "mother_name": "Priya Kumar",
      "father_phone": "9876543210",
      "mother_phone": "9876543211",
      "emergency_contact": "9876543212",
      "relationship": "father"
    },
    "address": {
      "street": "123 Main St",
      "city": "Bangalore",
      "state": "Karnataka",
      "postal_code": "560001",
      "country": "India"
    },
    "created_at": "2024-01-15T10:30:45.000Z",
    "updated_at": "2026-03-16T10:30:45.000Z"
  }
}

Section 7: Error Responses

404 - Student Not Found

{
  "status": "error",
  "code": "NOT_FOUND",
  "message": "Student not found"
}

403 - Access Denied

{
  "status": "error",
  "code": "FORBIDDEN",
  "message": "You don't have access to this student"
}

Section 8: Implementation Examples

JavaScript:

const getChildDetail = async (token, studentId) => {
  const response = await fetch(
    `https://api.skole.com/v1/parent-app/student/${studentId}`,
    {
      method: 'GET',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      }
    }
  );

  const data = await response.json();
  if (data.status === 'success') {
    return data.data;
  }
  throw new Error(data.message);
};

Section 9: Database Context

Query joins: students + student_guardian + student_address

Section 10: Business Logic & Validations

Verify parent_id has access to this student_id.

GET /parent-app/student - List all children
PUT /parent-app/student/:id - Update child

Section 12: Response Summary Table

Status	Scenario	Error Code	Message
200 ✅	Success	-	Student detail
404 ❌	Not found	NOT_FOUND	Student not found
403 ❌	No access	FORBIDDEN	No access to student

PARENT-03: Update Child Info

Section 1: Endpoint Summary

Parents can update child’s profile information (emergency contact, address, medical info).

Section 2: HTTP Details

HTTP Method: PUT
Endpoint URL: /parent-app/student/:id
Authentication: JWT Bearer Token (Parent)

Section 3: Path Parameters

Parameter	Type	Required	Description
id	UUID	Yes	Student ID

Section 5: Request Body Schema

{
  "dob": "Date (ISO 8601)",
  "blood_group": "Enum: O+, O-, A+, A-, B+, B-, AB+, AB-",
  "major_ailment": "String (health conditions)",
  "guardian": {
    "emergency_contact": "String (phone)"
  },
  "address": {
    "street": "String",
    "city": "String",
    "state": "String",
    "postal_code": "String"
  }
}

Section 6: Response Schema (Success - 200)

{
  "status": "success",
  "message": "Student updated",
  "data": {
    "id": "UUID",
    "updated_at": "2026-03-16T10:30:45.000Z"
  }
}

Section 7: Error Responses

400 - Validation Error

{
  "status": "error",
  "code": "VALIDATION_ERROR",
  "message": "Invalid blood group format"
}

Section 8: Implementation Examples

JavaScript:

const updateChildInfo = async (token, studentId, updates) => {
  const response = await fetch(
    `https://api.skole.com/v1/parent-app/student/${studentId}`,
    {
      method: 'PUT',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(updates)
    }
  );

  const data = await response.json();
  return data.status === 'success';
};

// Usage
await updateChildInfo(token, studentId, {
  blood_group: 'O+',
  major_ailment: 'None',
  address: {
    street: '456 New St',
    city: 'Bangalore'
  }
});

Section 9: Database Context

Updates: students, student_guardian, student_address tables

Section 10: Business Logic & Validations

Verify parent access, validate blood group enum, check school isolation.

GET /parent-app/student/:id - Get current info
PATCH endpoints for partial updates

Section 12: Response Summary Table

Status	Scenario	Error Code	Message
200 ✅	Success	-	Student updated
400 ❌	Invalid data	VALIDATION_ERROR	Invalid format

PARENT-04: Archive Child Record

Section 1: Endpoint Summary

Parents can remove/archive a child from their profile (when child transfers schools).

Section 2: HTTP Details

HTTP Method: DELETE
Endpoint URL: /parent-app/student/:id
Authentication: JWT Bearer Token (Parent)

Section 5: Request Body Schema

{
  "reason": "String (optional - transfer, other)"
}

Section 6: Response Schema (Success - 200)

{
  "status": "success",
  "message": "Student archived"
}

Section 8: Implementation Examples

JavaScript:

const archiveChild = async (token, studentId, reason = null) => {
  const response = await fetch(
    `https://api.skole.com/v1/parent-app/student/${studentId}`,
    {
      method: 'DELETE',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ reason })
    }
  );

  return (await response.json()).status === 'success';
};

Section 9: Database Context

Sets status = ‘archived’, records archive_reason and archive_date

Section 12: Response Summary Table

Status	Scenario	Error Code	Message
200 ✅	Success	-	Student archived

PARENT-05: Search Children

Section 1: Endpoint Summary

Search children by name, roll number, or class with fuzzy matching support.

Section 2: HTTP Details

HTTP Method: GET
Endpoint URL: /parent-app/student/search
Authentication: JWT Bearer Token (Parent)

Section 4: Query Parameters

Parameter	Type	Required	Description
q	String	Yes	Search query (name, roll_no)
class	String	No	Filter by class

Section 6: Response Schema (Success - 200)

{
  "status": "success",
  "data": {
    "results": [
      {
        "id": "UUID",
        "first_name": "Arjun",
        "last_name": "Kumar",
        "roll_no": "12",
        "class": "10"
      }
    ]
  }
}

Section 8: Implementation Examples

JavaScript:

const searchChildren = async (token, query, filter = {}) => {
  const params = new URLSearchParams({ q: query, ...filter });
  const response = await fetch(
    `https://api.skole.com/v1/parent-app/student/search?${params}`,
    {
      method: 'GET',
      headers: {
        'Authorization': `Bearer ${token}`
      }
    }
  );

  return (await response.json()).data.results;
};

Section 12: Response Summary Table

Status	Scenario	Error Code
200 ✅	Success	-

TEACHER-01: List Assigned Students

Section 1: Endpoint Summary

Teachers retrieve list of students assigned to their classes.

Section 2: HTTP Details

HTTP Method: GET
Endpoint URL: /teachers-app/student
Authentication: JWT Bearer Token (Staff)

Section 4: Query Parameters

Parameter	Type	Required	Description
class_id	UUID	No	Filter by class
take	Integer	No	Page size (default: 20)
skip	Integer	No	Pagination offset

Section 6: Response Schema (Success - 200)

{
  "status": "success",
  "data": {
    "students": [
      {
        "id": "UUID",
        "first_name": "Arjun",
        "last_name": "Kumar",
        "roll_no": "12",
        "class": "10",
        "section": "A",
        "dob": "2010-05-15",
        "major_ailment": null
      }
    ],
    "pagination": {
      "total": 45,
      "take": 20,
      "skip": 0
    }
  }
}

Section 8: Implementation Examples

JavaScript:

const getMyStudents = async (token, classId = null) => {
  const params = new URLSearchParams({
    take: 20,
    skip: 0
  });
  if (classId) params.append('class_id', classId);

  const response = await fetch(
    `https://api.skole.com/v1/teachers-app/student?${params}`,
    {
      method: 'GET',
      headers: { 'Authorization': `Bearer ${token}` }
    }
  );

  const data = await response.json();
  return data.data.students;
};

Section 9: Database Context

Query via staff_student junction table:

SELECT s.* FROM students s
INNER JOIN staff_student ss ON s.id = ss.student_id
WHERE ss.staff_id = ? AND s.skole_id = ?
ORDER BY s.roll_no ASC

Section 10: Business Logic & Validations

Load students only through staff_student assignments (many-to-many).

GET /teachers-app/student/:id - Student detail
POST /teachers-app/student - Create new student
PUT /teachers-app/student/:id - Update student

Section 12: Response Summary Table

Status	Scenario	Error Code	Message
200 ✅	Success	-	Students retrieved

TEACHER-02: Get Student Detail

Section 1: Endpoint Summary

Fetch complete profile of a student assigned to teacher’s class.

Section 2: HTTP Details

HTTP Method: GET
Endpoint URL: /teachers-app/student/:id
Authentication: JWT Bearer Token (Staff)

Section 3: Path Parameters

Parameter	Type	Required	Description
id	UUID	Yes	Student ID

Section 6: Response Schema (Success - 200)

{
  "status": "success",
  "data": {
    "id": "UUID",
    "first_name": "Arjun",
    "last_name": "Kumar",
    "roll_no": "12",
    "class": "10",
    "section": "A",
    "dob": "2010-05-15",
    "gender": "Male",
    "blood_group": "O+",
    "major_ailment": null,
    "parent_details": {
      "father_name": "Rajesh Kumar",
      "father_phone": "9876543210",
      "mother_name": "Priya Kumar"
    }
  }
}

Section 7: Error Responses

403 - Not In Class

{
  "status": "error",
  "code": "FORBIDDEN",
  "message": "Student not in your assigned classes"
}

Section 8: Implementation Examples

JavaScript:

const getStudentDetail = async (token, studentId) => {
  const response = await fetch(
    `https://api.skole.com/v1/teachers-app/student/${studentId}`,
    {
      method: 'GET',
      headers: { 'Authorization': `Bearer ${token}` }
    }
  );

  const data = await response.json();
  if (data.status === 'success') return data.data;
  throw new Error(data.message);
};

Section 12: Response Summary Table

Status	Scenario	Error Code	Message
200 ✅	Success	-	Student detail
403 ❌	Not assigned	FORBIDDEN	Not in your classes

TEACHER-03: Update Student Info

Section 1: Endpoint Summary

Teachers can update student information like attendance status or academic notes.

Section 2: HTTP Details

HTTP Method: PUT
Endpoint URL: /teachers-app/student/:id
Authentication: JWT Bearer Token (Staff)

Section 5: Request Body Schema

{
  "notes": "String (teacher notes)",
  "status": "Enum: active, inactive"
}

Section 6: Response Schema (Success - 200)

{
  "status": "success",
  "message": "Student updated"
}

Section 8: Implementation Examples

JavaScript:

const updateStudent = async (token, studentId, updates) => {
  const response = await fetch(
    `https://api.skole.com/v1/teachers-app/student/${studentId}`,
    {
      method: 'PUT',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(updates)
    }
  );

  return (await response.json()).status === 'success';
};

Section 12: Response Summary Table

Status	Scenario	Error Code
200 ✅	Success	-

TEACHER-04: Create Student Record

Section 1: Endpoint Summary

Teachers can create new student records in their assigned classes (for late admissions or transfers).

Section 2: HTTP Details

HTTP Method: POST
Endpoint URL: /teachers-app/student
Authentication: JWT Bearer Token (Staff)

Section 5: Request Body Schema

{
  "first_name*": "String",
  "last_name*": "String",
  "roll_no*": "Integer (unique per class)",
  "class_id*": "UUID",
  "dob*": "Date (ISO 8601)",
  "gender": "Enum: M, F, Other",
  "father_name": "String",
  "mother_name": "String",
  "father_phone": "String"
}

Section 6: Response Schema (Success - 201)

{
  "status": "success",
  "message": "Student created",
  "data": {
    "id": "UUID",
    "roll_no": "12",
    "created_at": "2026-03-16T10:30:45.000Z"
  }
}

Section 7: Error Responses

400 - Duplicate Roll Number

{
  "status": "error",
  "code": "DUPLICATE_ROLL_NO",
  "message": "Roll number already exists in this class"
}

Section 8: Implementation Examples

JavaScript:

const createStudent = async (token, studentData) => {
  const response = await fetch(
    'https://api.skole.com/v1/teachers-app/student',
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(studentData)
    }
  );

  const data = await response.json();
  if (data.status === 'success') return data.data;
  throw new Error(data.message);
};

Section 12: Response Summary Table

Status	Scenario	Error Code	Message
201 ✅	Created	-	Student created
400 ❌	Duplicate	DUPLICATE_ROLL_NO	Roll number exists

ADMIN-01: List All Students (Web App)

Section 1: Endpoint Summary

Admin view of all students in school with advanced filtering, sorting, and pagination.

Section 2: HTTP Details

HTTP Method: GET
Endpoint URL: /web-app/student
Authentication: JWT Bearer Token (Admin)

Section 4: Query Parameters

Parameter	Type	Required	Description	Example
status	String	No	Filter: active, inactive, archived	`active`
class	String	No	Filter by class/grade	`10`
section	String	No	Filter by section	`A`
search	String	No	Search by name or roll_no	`Arjun`
sort_by	String	No	Sort field (name, roll_no, class)	`roll_no`
sort_order	String	No	asc or desc	`asc`
take	Integer	No	Page size (default: 20, max: 100)	`50`
skip	Integer	No	Pagination offset	`0`

Section 6: Response Schema (Success - 200)

{
  "status": "success",
  "data": {
    "students": [
      {
        "id": "UUID",
        "first_name": "Arjun",
        "last_name": "Kumar",
        "roll_no": "12",
        "class": "10",
        "section": "A",
        "status": "active",
        "created_at": "2024-01-15T10:30:45.000Z"
      }
    ],
    "pagination": {
      "total": 450,
      "take": 20,
      "skip": 0,
      "pages": 23
    },
    "filters_applied": {
      "status": "active",
      "class": "10"
    }
  }
}

Section 8: Implementation Examples

JavaScript:

const getAllStudents = async (token, filters = {}) => {
  const params = new URLSearchParams({
    take: filters.take || 20,
    skip: filters.skip || 0,
    ...filters
  });

  const response = await fetch(
    `https://api.skole.com/v1/web-app/student?${params}`,
    {
      method: 'GET',
      headers: { 'Authorization': `Bearer ${token}` }
    }
  );

  return (await response.json()).data;
};

// Usage
const results = await getAllStudents(token, {
  status: 'active',
  class: '10',
  take: 50
});

Python:

def get_all_students(token: str, filters: dict = None) -> dict:
    url = 'https://api.skole.com/v1/web-app/student'
    headers = {'Authorization': f'Bearer {token}'}
    params = {
        'take': 20,
        'skip': 0,
        **(filters or {})
    }
    
    response = requests.get(url, headers=headers, params=params)
    return response.json()['data']

Section 9: Database Context

Dynamic WHERE clause builder:

SELECT s.*, COUNT(*) OVER() as total
FROM students s
WHERE s.skole_id = ?
  AND (? IS NULL OR s.status = ?)
  AND (? IS NULL OR s.class = ?)
  AND (? IS NULL OR s.section = ?)
  AND (? IS NULL OR s.first_name ILIKE ? OR s.roll_no = ?)
ORDER BY s.{sort_by} {sort_order}
LIMIT ? OFFSET ?

Indices: skole_id, status, class, section, (first_name, last_name)

Section 10: Business Logic & Validations

Validation:

Admin must belong to school (skole_id match)
Status, class, section must be valid enums
Pagination: skip >= 0, take <= 100
Search applies fuzzy matching

Business Logic:

Build dynamic WHERE filters
Apply school isolation
Count total records matching filters
Fetch paginated results
Return with pagination metadata

GET /web-app/student/:id - Student detail
POST /web-app/student - Create student
PUT /web-app/student/:id - Update student
POST /web-app/student/bulk-upload - Bulk import

Section 12: Response Summary Table

Status	Scenario	Error Code	Message
200 ✅	Success	-	Students retrieved
400 ❌	Invalid filter	INVALID_FILTER	Invalid filter value

ADMIN-02: Get Student Detail (Web App)

Section 1: Endpoint Summary

Complete admin view of student profile with all linked data: guardians, addresses, staff assignments, academic info.

Section 2: HTTP Details

HTTP Method: GET
Endpoint URL: /web-app/student/:id
Authentication: JWT Bearer Token (Admin)

Section 6: Response Schema (Success - 200)

{
  "status": "success",
  "data": {
    "id": "UUID",
    "first_name": "Arjun",
    "last_name": "Kumar",
    "roll_no": "12",
    "class": "10",
    "section": "A",
    "status": "active",
    "dob": "2010-05-15",
    "gender": "Male",
    "blood_group": "O+",
    "major_ailment": null,
    "guardian": {
      "father_name": "Rajesh Kumar",
      "father_phone": "9876543210",
      "mother_name": "Priya Kumar",
      "mother_phone": "9876543211",
      "emergency_contact": "9876543212"
    },
    "address": {
      "type": "residential",
      "street": "123 Main St",
      "city": "Bangalore",
      "state": "Karnataka",
      "postal_code": "560001"
    },
    "assigned_staff": [
      {
        "staff_id": "UUID",
        "name": "Mr. Vikram Kumar",
        "subject": "Science"
      }
    ],
    "created_at": "2024-01-15T10:30:45.000Z",
    "updated_at": "2026-03-16T10:30:45.000Z"
  }
}

Section 8: Implementation Examples

JavaScript:

const getStudentDetail = async (token, studentId) => {
  const response = await fetch(
    `https://api.skole.com/v1/web-app/student/${studentId}`,
    {
      method: 'GET',
      headers: { 'Authorization': `Bearer ${token}` }
    }
  );

  const data = await response.json();
  return data.data;
};

Section 12: Response Summary Table

Status	Scenario	Error Code	Message
200 ✅	Success	-	Student detail

ADMIN-03: Create Student

Section 1: Endpoint Summary

Admin creates new student record with comprehensive profile including guardians, address, and class assignment.

Section 2: HTTP Details

HTTP Method: POST
Endpoint URL: /web-app/student
Authentication: JWT Bearer Token (Admin)

Section 5: Request Body Schema

{
  "first_name*": "String",
  "last_name*": "String",
  "roll_no*": "Integer",
  "class_id*": "UUID",
  "dob*": "Date (ISO 8601)",
  "gender": "Enum: M, F, Other",
  "blood_group": "String",
  "major_ailment": "String (nullable)",
  "guardian": {
    "father_name*": "String",
    "father_phone*": "String",
    "mother_name": "String",
    "mother_phone": "String",
    "emergency_contact": "String"
  },
  "address": {
    "type": "Enum: residential, permanent",
    "street*": "String",
    "city*": "String",
    "state*": "String",
    "postal_code": "String"
  }
}

Section 6: Response Schema (Success - 201)

{
  "status": "success",
  "message": "Student created",
  "data": {
    "id": "UUID",
    "roll_no": "12",
    "created_at": "2026-03-16T10:30:45.000Z"
  }
}

Section 7: Error Responses

400 - Duplicate Roll Number

{
  "status": "error",
  "code": "DUPLICATE_ROLL_NO",
  "message": "Roll number already exists in this class"
}

400 - Invalid Class

{
  "status": "error",
  "code": "INVALID_CLASS",
  "message": "Class not found in this school"
}

Section 8: Implementation Examples

JavaScript:

const createStudent = async (token, studentData) => {
  const response = await fetch(
    'https://api.skole.com/v1/web-app/student',
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(studentData)
    }
  );

  const data = await response.json();
  if (data.status === 'success') return data.data;
  throw new Error(data.message);
};

// Usage
const newStudent = await createStudent(token, {
  first_name: 'Arjun',
  last_name: 'Kumar',
  roll_no: 12,
  class_id: 'uuid-here',
  dob: '2010-05-15',
  gender: 'M',
  guardian: {
    father_name: 'Rajesh Kumar',
    father_phone: '9876543210'
  },
  address: {
    type: 'residential',
    street: '123 Main St',
    city: 'Bangalore',
    state: 'Karnataka'
  }
});

Python:

def create_student(token: str, student_data: dict):
    url = 'https://api.skole.com/v1/web-app/student'
    headers = {
        'Authorization': f'Bearer {token}',
        'Content-Type': 'application/json'
    }
    
    response = requests.post(url, json=student_data, headers=headers)
    data = response.json()
    
    if data['status'] == 'success':
        return data['data']
    raise Exception(data['message'])

Section 9: Database Context

Inserts into:

students table
student_guardian table
student_address table

Transactions: All three inserts wrapped in transaction for consistency

Section 10: Business Logic & Validations

Validation:

Roll number unique within class
Class exists and belongs to school
Guardian phone valid format
DOB must be in past
Gender from enum
Required fields present

Business Logic:

Validate roll number uniqueness in class
Check class exists in school
Create student record
Create guardians record
Create address record
Return new student ID

GET /web-app/student - List students
PUT /web-app/student/:id - Update student
DELETE /web-app/student/:id - Delete student

Section 12: Response Summary Table

Status	Scenario	Error Code	Message
201 ✅	Created	-	Student created
400 ❌	Duplicate roll	DUPLICATE_ROLL_NO	Roll exists
400 ❌	Invalid class	INVALID_CLASS	Class not found

ADMIN-04: Update Student

Section 1: Endpoint Summary

Admin updates student profile including personal details, guardians, and addresses.

Section 2: HTTP Details

HTTP Method: PUT
Endpoint URL: /web-app/student/:id
Authentication: JWT Bearer Token (Admin)

Section 5: Request Body Schema

{
  "first_name": "String",
  "last_name": "String",
  "dob": "Date",
  "gender": "Enum",
  "blood_group": "String",
  "major_ailment": "String",
  "status": "Enum: active, inactive",
  "guardian": {...},
  "address": {...}
}

Section 6: Response Schema (Success - 200)

{
  "status": "success",
  "message": "Student updated",
  "data": {
    "id": "UUID",
    "updated_at": "2026-03-16T10:30:45.000Z"
  }
}

Section 8: Implementation Examples

JavaScript:

const updateStudent = async (token, studentId, updates) => {
  const response = await fetch(
    `https://api.skole.com/v1/web-app/student/${studentId}`,
    {
      method: 'PUT',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(updates)
    }
  );

  return (await response.json()).data;
};

Section 12: Response Summary Table

Status	Scenario	Error Code	Message
200 ✅	Success	-	Student updated

ADMIN-05: Delete Student

Section 1: Endpoint Summary

Admin permanently deletes student record (soft delete: archives with reason).

Section 2: HTTP Details

HTTP Method: DELETE
Endpoint URL: /web-app/student/:id
Authentication: JWT Bearer Token (Admin)

Section 5: Request Body Schema

{
  "reason": "String (transfer, withdrawn, other)"
}

Section 6: Response Schema (Success - 200)

{
  "status": "success",
  "message": "Student deleted",
  "data": {
    "id": "UUID",
    "status": "archived"
  }
}

Section 8: Implementation Examples

JavaScript:

const deleteStudent = async (token, studentId, reason) => {
  const response = await fetch(
    `https://api.skole.com/v1/web-app/student/${studentId}`,
    {
      method: 'DELETE',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ reason })
    }
  );

  return (await response.json()).status === 'success';
};

Section 12: Response Summary Table

Status	Scenario	Error Code	Message
200 ✅	Success	-	Student deleted

ADMIN-06: Bulk Upload Students

Section 1: Endpoint Summary

Admin imports multiple students at once from CSV/Excel file. Supports complex guardian and address data with validation.

Section 2: HTTP Details

HTTP Method: POST
Endpoint URL: /web-app/student/bulk-upload
Content-Type: multipart/form-data
Authentication: JWT Bearer Token (Admin)

Section 5: Request Body Schema

Form Data:
- file: File (CSV or Excel, max 10MB)
  Columns: first_name, last_name, roll_no, class_id, dob, gender, 
           father_name, father_phone, mother_name, mother_phone, 
           street, city, state, postal_code

- dry_run: Boolean (optional, validate only without saving)

Section 6: Response Schema (Success - 200)

{
  "status": "success",
  "message": "22 students imported successfully",
  "data": {
    "imported": 22,
    "skipped": 2,
    "errors": [
      {
        "row": 5,
        "error": "Duplicate roll number in class 10"
      },
      {
        "row": 12,
        "error": "Invalid date format"
      }
    ],
    "created_ids": ["UUID1", "UUID2", "..."]
  }
}

Section 7: Error Responses

413 - File Too Large

{
  "status": "error",
  "code": "FILE_TOO_LARGE",
  "message": "File exceeds 10MB limit"
}

400 - Invalid Format

{
  "status": "error",
  "code": "INVALID_FILE_FORMAT",
  "message": "File must be CSV or Excel format"
}

422 - Validation Failures

{
  "status": "error",
  "code": "VALIDATION_FAILED",
  "message": "12 rows have validation errors",
  "data": {
    "errors": [...]
  }
}

Section 8: Implementation Examples

JavaScript (FormData):

const bulkUploadStudents = async (token, file, dryRun = false) => {
  const formData = new FormData();
  formData.append('file', file);
  formData.append('dry_run', dryRun);

  const response = await fetch(
    'https://api.skole.com/v1/web-app/student/bulk-upload',
    {
      method: 'POST',
      headers: { 'Authorization': `Bearer ${token}` },
      body: formData
    }
  );

  const data = await response.json();
  console.log(`Imported: ${data.data.imported}, Skipped: ${data.data.skipped}`);
  
  if (data.data.errors.length > 0) {
    console.error('Errors:', data.data.errors);
  }
  
  return data.data;
};

// Usage
const fileInput = document.getElementById('csvFile');
const result = await bulkUploadStudents(token, fileInput.files[0]);

Python:

import requests

def bulk_upload_students(token: str, file_path: str, dry_run: bool = False):
    url = 'https://api.skole.com/v1/web-app/student/bulk-upload'
    headers = {'Authorization': f'Bearer {token}'}
    
    with open(file_path, 'rb') as f:
        files = {'file': f}
        data = {'dry_run': dry_run}
        
        response = requests.post(url, headers=headers, files=files, data=data)
        result = response.json()
        
        print(f"Imported: {result['data']['imported']}")
        print(f"Errors: {len(result['data']['errors'])}")
        
        return result['data']

# Usage
bulk_upload_students(token, 'students.csv', dry_run=True)

cURL:

curl -X POST \
  'https://api.skole.com/v1/web-app/student/bulk-upload' \
  -H 'Authorization: Bearer YOUR_TOKEN_HERE' \
  -F 'file=@students.csv' \
  -F 'dry_run=false'

Section 9: Database Context

Process:

Parse file (CSV/Excel reader)
Validate all rows first
If dry_run=true, stop here
Wrap inserts in transaction
Create students, guardians, addresses atomically

Indices: For batch inserts, may disable temporarily then rebuild

Section 10: Business Logic & Validations

Pre-validation:

File format: CSV or Excel only
File size: max 10MB
Column headers match expected schema

Row validations:

Required fields: first_name, last_name, roll_no, class_id, dob
Roll number unique within class
Class exists in school
Phone format valid (or null)
DOB in past
Gender from enum

Transaction handling:

All rows: all-or-nothing (atomic)
If any row fails: rollback all
Return detailed error list for partial failures

POST /web-app/student - Single student creation
GET /web-app/student - List students

Section 12: Response Summary Table

Status	Scenario	Error Code	Message
200 ✅	Success	-	Students imported
413 ❌	File too large	FILE_TOO_LARGE	Exceeds 10MB
400 ❌	Invalid format	INVALID_FILE_FORMAT	CSV/Excel only
422 ❌	Validation failed	VALIDATION_FAILED	Row errors

ID	Endpoint	Method	Auth	Description	Status
PARENT-01	`/parent-app/student`	GET	JWT	List children	✅ Documented
PARENT-02	`/parent-app/student/:id`	GET	JWT	Child detail	✅ Documented
PARENT-03	`/parent-app/student/:id`	PUT	JWT	Update child	✅ Documented
PARENT-04	`/parent-app/student/:id`	DELETE	JWT	Archive child	✅ Documented
PARENT-05	`/parent-app/student/search`	GET	JWT	Search children	✅ Documented
TEACHER-01	`/teachers-app/student`	GET	JWT	List assigned	✅ Documented
TEACHER-02	`/teachers-app/student/:id`	GET	JWT	Student detail	✅ Documented
TEACHER-03	`/teachers-app/student/:id`	PUT	JWT	Update student	✅ Documented
TEACHER-04	`/teachers-app/student`	POST	JWT	Create student	✅ Documented
ADMIN-01	`/web-app/student`	GET	JWT	List all	✅ Documented
ADMIN-02	`/web-app/student/:id`	GET	JWT	Student detail	✅ Documented
ADMIN-03	`/web-app/student`	POST	JWT	Create student	✅ Documented
ADMIN-04	`/web-app/student/:id`	PUT	JWT	Update student	✅ Documented
ADMIN-05	`/web-app/student/:id`	DELETE	JWT	Delete student	✅ Documented
ADMIN-06	`/web-app/student/bulk-upload`	POST	JWT	Bulk upload	✅ Documented

Academic Calendar Module Staff Management Module

​SKOLE-STUD — Student Management Module

​1. Overview

​Scope In

​Scope Out

​2. Requirements

​Functional Requirements (FR)

​Non-Functional Requirements (NFR)

​Constraints

​3. Sub-modules / Backlog

​4. Logical Implementation

​Student Status State Machine

​Teacher Assigned Students Flow

​Admin Student Listing

​5. UI Requirements

​Teacher App

​Web App

​Parent App

​6. Conditional Expressions

​7. Internal Module Connections

​8. Database Tables

​9. API Endpoints Summary

​10. Detailed Endpoint Documentation (12-Section Format)

​PARENT-01: List Parent’s Children

​Section 1: Endpoint Summary

​Section 2: HTTP Details

​Section 3: Path Parameters

​Section 4: Query Parameters

​Section 5: Request Body Schema

​Section 6: Response Schema (Success - 200)

​Section 7: Error Responses

​Section 8: Implementation Examples

​Section 9: Database Context

​Section 10: Business Logic & Validations

​Section 11: Related Endpoints

​Section 12: Response Summary Table

​PARENT-02: Get Child Detail

​Section 1: Endpoint Summary

​Section 2: HTTP Details

​Section 3: Path Parameters

​Section 5: Request Body Schema

​Section 6: Response Schema (Success - 200)

​Section 7: Error Responses

​Section 8: Implementation Examples

​Section 9: Database Context

​Section 10: Business Logic & Validations

​Section 11: Related Endpoints

​Section 12: Response Summary Table

​PARENT-03: Update Child Info

​Section 1: Endpoint Summary

​Section 2: HTTP Details

​Section 3: Path Parameters

​Section 5: Request Body Schema

​Section 6: Response Schema (Success - 200)

​Section 7: Error Responses

​Section 8: Implementation Examples

​Section 9: Database Context

​Section 10: Business Logic & Validations

​Section 11: Related Endpoints

​Section 12: Response Summary Table

​PARENT-04: Archive Child Record

​Section 1: Endpoint Summary

​Section 2: HTTP Details

​Section 5: Request Body Schema

​Section 6: Response Schema (Success - 200)

​Section 8: Implementation Examples

​Section 9: Database Context

​Section 12: Response Summary Table

​PARENT-05: Search Children

​Section 1: Endpoint Summary

​Section 2: HTTP Details

​Section 4: Query Parameters

​Section 6: Response Schema (Success - 200)

​Section 8: Implementation Examples

​Section 12: Response Summary Table

​TEACHER-01: List Assigned Students

​Section 1: Endpoint Summary

​Section 2: HTTP Details

​Section 4: Query Parameters

​Section 6: Response Schema (Success - 200)

​Section 8: Implementation Examples

SKOLE-STUD — Student Management Module

1. Overview

Scope In

Scope Out

2. Requirements

Functional Requirements (FR)

Non-Functional Requirements (NFR)

Constraints

3. Sub-modules / Backlog

4. Logical Implementation

Student Status State Machine

Teacher Assigned Students Flow

Admin Student Listing

5. UI Requirements

Teacher App

Web App

Parent App

6. Conditional Expressions

7. Internal Module Connections

8. Database Tables

9. API Endpoints Summary

10. Detailed Endpoint Documentation (12-Section Format)

PARENT-01: List Parent’s Children

Section 1: Endpoint Summary

Section 2: HTTP Details

Section 3: Path Parameters

Section 4: Query Parameters

Section 5: Request Body Schema

Section 6: Response Schema (Success - 200)

Section 7: Error Responses

Section 8: Implementation Examples

Section 9: Database Context

Section 10: Business Logic & Validations

Section 11: Related Endpoints

Section 12: Response Summary Table

PARENT-02: Get Child Detail

Section 1: Endpoint Summary

Section 2: HTTP Details

Section 3: Path Parameters

Section 5: Request Body Schema

Section 6: Response Schema (Success - 200)

Section 7: Error Responses

Section 8: Implementation Examples

Section 9: Database Context

Section 10: Business Logic & Validations

Section 11: Related Endpoints

Section 12: Response Summary Table

PARENT-03: Update Child Info

Section 1: Endpoint Summary

Section 2: HTTP Details

Section 3: Path Parameters

Section 5: Request Body Schema

Section 6: Response Schema (Success - 200)

Section 7: Error Responses

Section 8: Implementation Examples

Section 9: Database Context

Section 10: Business Logic & Validations

Section 11: Related Endpoints

Section 12: Response Summary Table

PARENT-04: Archive Child Record

Section 1: Endpoint Summary

Section 2: HTTP Details

Section 5: Request Body Schema

Section 6: Response Schema (Success - 200)

Section 8: Implementation Examples

Section 9: Database Context

Section 12: Response Summary Table

PARENT-05: Search Children

Section 1: Endpoint Summary

Section 2: HTTP Details

Section 4: Query Parameters

Section 6: Response Schema (Success - 200)

Section 8: Implementation Examples

Section 12: Response Summary Table

TEACHER-01: List Assigned Students

Section 1: Endpoint Summary

Section 2: HTTP Details

Section 4: Query Parameters

Section 6: Response Schema (Success - 200)

Section 8: Implementation Examples