LearningOS

LearningOS is a reusable TypeScript operating layer for education platforms, schools, coaching institutes, academies, and education ERPs.

It manages students, guardians, teachers, classes, subjects, enrollments, attendance, exams, scores, assignments, submissions, timetable, report cards, academic analytics, events, audit logs, and role-based permissions.

This starter is built with Node.js + TypeScript, has no external runtime dependencies, uses a JSON file store for local development, and includes a PostgreSQL schema for production migration.

What LearningOS includes

• Student profile management
• Guardian/contact management
• Teacher management
• Class and section management
• Subject management
• Student enrollment
• Attendance sessions and attendance marks
• Exam creation and score recording
• Assignment creation, submission, and grading
• Timetable scheduling with conflict detection
• Report card generation and publishing
• Academic analytics
• Event log
• Audit log
• Role-based permission checks
• Seed demo data
• PostgreSQL schema example
• Automated tests

Architecture

LearningOS
├── Students
├── Guardians
├── Teachers
├── Classes
├── Subjects
├── Enrollments
├── Attendance
├── Exams
├── Assignments
├── Timetable
├── Report Cards
├── Analytics
├── Events
└── Audit Logs

Development stack

Language: TypeScript
Runtime: Node.js 20+
Storage: JSON file store for local dev
Production DB: PostgreSQL schema included
Testing: node:test

Run locally

npm run build
npm start

Default server:

http://localhost:5100

Health endpoint:

GET /health

Docs endpoint:

GET /docs

Environment variables

PORT=5100
DEFAULT_TENANT_ID=demo-tenant
LEARNINGOS_DB_FILE=data/learningos.db.json

Demo tenant

demo-tenant

Main demo IDs

stu_asha
stu_rahul
stu_neha
guard_asha_parent
teacher_math
teacher_science
class_grade10a
sub_math_10
sub_science_10
sub_english_10
atts_math_001
atts_science_001
exam_math_midterm
exam_science_midterm
asg_math_homework
tt_math_mon
tt_science_mon
rc_asha_term1

Auth and permissions

Use request headers:

x-tenant-id: demo-tenant
x-user-id: admin-user
x-role: learning_admin

Roles:

viewer
teacher
coordinator
academic_admin
principal
learning_admin
admin
owner
auditor

API examples

Overview

GET /learningos/overview
x-role: learning_admin

Create student

POST /learningos/students
x-role: learning_admin
Content-Type: application/json

{
  "firstName": "Maya",
  "lastName": "Rao",
  "admissionNo": "STU-2001",
  "gradeLevel": "Grade 10",
  "section": "A",
  "email": "maya@example.com"
}

Create subject

POST /learningos/subjects
x-role: learning_admin
Content-Type: application/json

{
  "name": "AI Literacy",
  "code": "AI-10",
  "gradeLevel": "Grade 10",
  "credits": 2
}

Create class

POST /learningos/classes
x-role: learning_admin
Content-Type: application/json

{
  "name": "Grade 10 B",
  "gradeLevel": "Grade 10",
  "section": "B",
  "academicYear": "2026-2027",
  "capacity": 40
}

Enroll student

POST /learningos/enrollments
x-role: learning_admin
Content-Type: application/json

{
  "studentId": "stu_asha",
  "classId": "class_grade10a",
  "academicYear": "2026-2027"
}

Create attendance session

POST /learningos/attendance-sessions
x-role: teacher
Content-Type: application/json

{
  "classId": "class_grade10a",
  "subjectId": "sub_math_10",
  "teacherId": "teacher_math",
  "date": "2026-05-20",
  "period": "P1",
  "topic": "Quadratic equations"
}

Mark attendance

POST /learningos/attendance-sessions/{sessionId}/marks
x-role: teacher
Content-Type: application/json

{
  "studentId": "stu_asha",
  "status": "present",
  "remarks": "On time"
}

Bulk mark attendance

POST /learningos/attendance-sessions/{sessionId}/bulk-marks
x-role: teacher
Content-Type: application/json

{
  "marks": [
    { "studentId": "stu_asha", "status": "present" },
    { "studentId": "stu_rahul", "status": "absent" },
    { "studentId": "stu_neha", "status": "late", "remarks": "8 minutes late" }
  ]
}

Create exam

POST /learningos/exams
x-role: academic_admin
Content-Type: application/json

{
  "name": "English Quiz",
  "classId": "class_grade10a",
  "subjectId": "sub_english_10",
  "term": "Term 1",
  "examDate": "2026-07-01",
  "maxMarks": 50
}

Record exam score

POST /learningos/exams/{examId}/scores
x-role: teacher
Content-Type: application/json

{
  "studentId": "stu_asha",
  "marksObtained": 44,
  "remarks": "Good performance"
}

Create assignment

POST /learningos/assignments
x-role: teacher
Content-Type: application/json

{
  "title": "Science Lab Notes",
  "classId": "class_grade10a",
  "subjectId": "sub_science_10",
  "teacherId": "teacher_science",
  "dueDate": "2099-01-01T00:00:00.000Z",
  "maxMarks": 25
}

Submit assignment

POST /learningos/assignments/{assignmentId}/submit
x-role: teacher
Content-Type: application/json

{
  "studentId": "stu_neha",
  "content": "Lab notes uploaded",
  "attachmentUrls": ["lab-notes.pdf"]
}

Grade submission

POST /learningos/submissions/{submissionId}/grade
x-role: teacher
Content-Type: application/json

{
  "marks": 22,
  "feedback": "Good observations"
}

Add timetable entry

POST /learningos/timetable
x-role: academic_admin
Content-Type: application/json

{
  "classId": "class_grade10a",
  "subjectId": "sub_math_10",
  "teacherId": "teacher_math",
  "dayOfWeek": "wednesday",
  "startTime": "09:00",
  "endTime": "10:00",
  "room": "Room 301"
}

Generate report card

POST /learningos/students/stu_asha/report-card
x-role: learning_admin
Content-Type: application/json

{
  "classId": "class_grade10a",
  "term": "Term 1",
  "academicYear": "2026-2027"
}

Tests

npm test

Production notes

For production, replace the JSON file store with PostgreSQL using database/schema.sql. Keep LearningOS as a reusable service/package and connect it with:

SecurityOS   → roles, permissions, audit policy
FinanceOS    → student fees, invoices, payments
AnalyticsOS  → advanced dashboards and reports
AutomationOS → reminders, parent notifications, workflows
ExperienceOS → student/parent feedback and support journeys
AIOS         → learning assistant, recommendations, academic insights

Planning Alignment

• Official package: @appneurox/learningos
• Manifest: manifest.json
• Domain API namespace: /v1/learning
• Modes: standalone and PlatformOS integrated
• Related systems: KnowledgeOS, AIOS

See docs/planning.md for the planning contract applied from APPNEURAL Plannings/OSs.