SIS Documentation
Getting Started
Installation
Prerequisites
Development Setup
1. Clone the Repository
2. Initial Setup
3. Configure Environment
4. Create Database
5. Run the Server
Available Make Commands
Running Tests
Generating API Documentation
Docker Deployment
Build Docker Image
Run with Docker Compose
Kubernetes Deployment
Running Background Jobs
Verifying Installation
Troubleshooting
Database Connection Issues
Port Already in Use
Migration Failures
Next Steps
Configuration
Environment Variables
Database Configuration
Authentication
Server Settings
AWS S3 Storage
Canvas LMS Integration
Email Configuration
Rate Limiting
Example Configuration
Development (.env)
Production
Multi-tenancy Configuration
Academic Session Configuration
CORS Configuration
Logging Configuration
Security Headers
Next Steps
Quick Start Guide
Prerequisites
Step 1: Login
Step 2: Get Current User Info
Step 3: List Students
Step 4: Create a Student
Step 5: Search with Filters
Step 6: Update a Record
Step 7: Delete a Record
Common Patterns
Required Headers
List Endpoint Pattern
CRUD Endpoints Pattern
Relationship Endpoints
Error Handling
Common Error Responses
Token Refresh
Next Steps
Architecture
Architecture Overview
High-Level Architecture
Directory Structure
Layer Responsibilities
Controllers (HTTP Layer)
Services (Business Layer)
Repositories (Data Layer)
Generic CRUD Pattern
Middleware Chain
Database Design
Soft Deletes
Multi-tenancy
Audit Fields
External Integrations
Canvas LMS
Background Jobs
Configuration
Error Handling
Testing Strategy
Generic CRUD Pattern
Overview
BaseModel
BeforeCreate Hook
BaseRepository
Key Methods
Query Building
BaseService
Key Methods
Input Mapping
BaseController
Standard Handlers
Creating a New Module
Step 1: Define the Model
Step 2: Create Repository
Step 3: Create Service
Step 4: Create Controller
Step 5: Register Routes
Input Struct Tags
Model Interface Methods
Multi-tenancy
Overview
Team Model
Team Hierarchy Example
Request Context
Team Middleware
Data Isolation
BaseModel Team Field
Automatic Filtering
Hierarchical Access
Creating Records
Disabling Team Filtering
User-Team Association
Checking Team Access
API Examples
List Records for Current Team
Create Record in Current Team
Get User’s Teams
Team Management
Create Team
Assign User to Team
Best Practices
Cross-Team Queries (Admin Only)
Job System
Overview
Architecture
Job Interface
Creating a Job
Step 1: Implement the Job Interface
Step 2: Register the Job
Cron Expressions
Common Patterns
Running Jobs
As a Scheduler (Daemon Mode)
Manual Execution
List Available Jobs
Job Logging
Querying Job Logs
Built-in Jobs (114 Total)
System Maintenance Jobs
Data Linking Jobs
Data Fix Jobs
Canvas LMS Sync Jobs (6-Phase Execution)
Gradebook Calculation Jobs
Import Jobs
Report Jobs
Manual Sync Jobs
Error Handling
Concurrency Control
Job Configuration
Monitoring
Job Health Check
Job Statistics
Best Practices
Frontend
Frontend Development Guide
Prerequisites
Project Setup
Project Structure
Core Concepts
Base Components
HTTP Interceptors
Route Guards
Feature Modules
Creating a New Feature Module
Core Services
ApiService
AuthService
BackendService
Shared Components
Key Components
Using GenericListComponent
Internationalization (i18n)
Environment Configuration
Building & Deployment
Docker Build
Kubernetes Deployment
Best Practices
Common Tasks
Adding a Column to GenericList
Custom Row Actions
Accessing Route Parameters
Frontend Architecture
Technology Stack
Application Architecture
Module Architecture
Lazy Loading Strategy
Feature Modules
Core Module
Services
HTTP Interceptors
Route Guards
Base Component Pattern
Component Hierarchy
BaseComponent
BaseListComponent
Shared Module
Component Categories
State Management
State Flow
Multi-Tenancy
Authentication Flow
Standard Login
Token Storage
LTI Authentication
OIDC/SSO Authentication
Internationalization
ngx-translate Setup
Translation Keys
Language Switching
Error Handling
ErrorInterceptor
Component-Level Handling
Performance Optimization
Lazy Loading
Change Detection
Subscription Management
TrackBy Functions
API Reference
API Overview
Base URL
HTTP Methods
Request Headers
Required Headers
Optional Headers
Response Format
Success Response
Error Response
List Response
Standard CRUD Endpoints
Relationship Endpoints
List Request Format
Parameters
Filter System
Simple Filter
Nested Filter (AND + OR)
Filter Operators
Pagination
Field Definitions
Field Types
Error Codes
Rate Limiting
Soft Delete
Audit Trail
Multi-tenancy
Preloading Relations
GraphQL API Reference
Overview
Quick Start
1. Authentication
2. Basic Query
3. Query with Variables
Request Headers
Available Queries
Academic Structure
Personnel
Assessment & Grading
Attendance
Enrollment
Timetabling
Communication
System Configuration
Other
Pagination
Input
Example
Response
Sorting
Input
Example
Common Sort Fields
Filtering
Filter Structure
Available Operators
Filter Examples
Simple Filter
Multiple Conditions (AND)
OR Conditions
Using IN Operator
Search by Name (CONTAINS)
Nested AND/OR Groups
Entity Schemas
Student
Teacher
Class
Course
Assessment
Gradebook
Behavior
Complex Query Examples
Dashboard Statistics
Student with Full Details
Class Roster with Students
Course with Assessments and Results
Teachers with Their Classes and Courses
Attendance Report
Gradebook Report
Using GraphQL Clients
JavaScript (fetch)
Angular (Apollo Angular)
cURL
GraphQL Playground
Features
Enabling Playground
Error Handling
Error Response Format
Common Error Codes
Best Practices
1. Request Only What You Need
2. Use Pagination for Large Datasets
3. Use Variables for Dynamic Values
4. Batch Related Queries
5. Use Fragments for Reusable Fields
Rate Limiting
Multi-tenancy
Comparison: GraphQL vs REST API
Authentication
Overview
Endpoints
Login
Refresh Token
Get Current User
Change Password
Logout
Reset Password (Admin)
Using Tokens
Authorization Header
Token Structure
Security Features
Token Blacklisting
Rate Limiting
Security Audit
Code Examples
JavaScript/TypeScript
Axios Interceptor
SSO / OIDC Login
OIDC Flow
Users API
Model
Status Values
Endpoints
List Users
Get User by ID
Create User
Update User
Delete User
Role Assignment
Assign Role to User
Remove Role from User
Team Assignment
Assign User to Team
Remove User from Team
Password Management
Reset Password (Admin)
Change Password (Self)
Roles API
Model
Permissions Structure
Available Actions
Endpoints
List Roles
Get Role by ID
Create Role
Update Role
Delete Role
Save Permissions
User-Role Assignment
Assign Users to Role
Remove Users from Role
Built-in Roles
Permission Check
Teams API
Model
Hierarchy
Endpoints
List Teams (Public)
List Teams (Admin)
Get Team by ID
Create Team
Update Team
Delete Team
User-Team Assignment
Assign Users to Team
Remove Users from Team
Data Isolation
Students API
Model
Status Values
Model Fields
Base Fields (from BaseModel)
Student-Specific Fields
Person Fields (from Person interface)
Address Fields (4 address types)
Mobile App Integration
LMS Integration
Endpoints
List Students
Get Student by ID
Create Student
Update Student
Delete Student
Bulk Create Students
Bulk Delete Students
Export to Excel
Import from Excel
Enrollment Endpoints
Get Student’s Class Enrollments
Enroll Student in Class
Get Student’s Course Enrollments
Special Endpoints
Force Canvas Sync
Searchable Fields
Filterable Fields
Related Modules
Canvas LMS Integration
Code Examples
JavaScript - List Active Students
JavaScript - Create Student
cURL - Search Students
Teachers API
Model
Status Values
Endpoints
Standard CRUD
Relationships
Qualifications
Work Experience
Certifications
Filterable Fields
Canvas Integration
Classes API
Model
Endpoints
Standard CRUD
Get Enrolled Students
Import Classes
Import Enrollments
Export Classes
Enrollment
Courses API
Model
Status Values
Course Types
Endpoints
Standard CRUD
Get Enrolled Students
Import Courses
Import Enrollments
Export Courses
Teacher Assignment
Canvas Integration
Academic Sessions API
Model
Status Values
Public Endpoints
List Sessions
Get Session
Protected Endpoints
Create Session
Update Session
Delete Session
Context Header
Semesters
Timetables API
Model
Timetable Detail
Endpoints
Standard CRUD
Schedule Management
Import/Export
Duplicate
Class Schedule
Generate
Periods
Days of Week
Attendance API
Model
Status Values
Attendance Types
Endpoints
Standard CRUD Endpoints
Bulk Class Attendance
Bulk Course Attendance
Get Student Attendance Details
Get Attendance Statuses
Daily Attendance Status
Daily Course Attendance Status
Attendance Report
Attendance Reports
Courses Without Attendance
Export Missing Attendance Report
Filtering
By Date Range
By Status
By Class and Date
Duplicate Handling
Code Examples
Take Class Attendance
Get Monthly Attendance Summary
Integration Notes
Behaviors API
Model
Behavior Types
Categories
Status Values
Endpoints
Standard CRUD
Send Notification
Filtering
By Student
By Date Range
Auto-Generated Codes
Gradebooks API
Models
Gradebook
GradebookCourse
Assessment
AssessmentResult
Endpoints
Gradebook CRUD
Student Reports
Class Summary
Subject Statistics
Report Cards
Generate Report Card
Check Generation Status
Download Report Card
Assessment Results
List Results for Assessment
Get Statistics
Student Course Results
Grade Calculation
Calculate Course Grade
Recalculate Student Grades
Grade Scales
Assessments API
Model
Assessment Types
Endpoints
Assessment Results
Report Cards API
Endpoints
Create Request
List Requests
Get Request Status
Download Report Card
Generate for Gradebook
Run Generation Job
Report Card Templates
Student Report Cards
Medical Records API
Model
Endpoints
Related Modules
Medical Care API
Model
Endpoints
History
Vaccinations API
Model
Endpoints
Audit Logs API
Model
Actions
Endpoints
List Logs
Get by Entity
Get by User
Get by Date Range
Get Statistics
Export
Import Data API
Model
Status Values
Endpoints
Upload File
Save Mapping
Start Import
Check Status
Download Error Report
Cancel Import
Get Saved Mappings
System Settings API
Model
Categories
Endpoints
List Settings
Get Setting
Create Setting
Update Setting
Delete Setting
Common Settings
Guides
Filter System Guide
Basic Filtering
Simple Condition
Multiple Conditions (AND)
Multiple Conditions (OR)
Nested Filtering
Operators
Comparison Operators
String Operators
Null Operators
Array Operators
Field Types
Text Fields
Date Fields
Date Range
Boolean Fields
Enum Fields
Relate Fields (Foreign Keys)
Multi-relate Fields
Related Field Filtering
Direct Relation
Through Enrollment
Filterable Fields API
Saved Filters
Filter Definition Model
Create Saved Filter
Load Saved Filter
Get Filters for Module
Complex Examples
Students in Grade 10 or 11, Active Status
Students Enrolled in Specific Courses This Semester
Attendance Records for Absent Students This Week
Performance Tips
Code Examples
JavaScript Filter Builder
Import System Guide
Overview
Import Workflow
Supported Modules
Step 1: Upload File
Step 2: Get Importable Fields
Step 3: Save Field Mapping
Mapping Options
Step 4: Start Import
Step 5: Check Status
Status Values
Step 6: Review Errors
Cancel Import
Saved Mappings
Get Saved Mappings
Apply Saved Mapping
Relation Field Import
Lookup by Code
Lookup Field Configuration
Multiple Lookup Fields
Excel Template
Download Template
Template Format
Error Handling
Validation Errors
Relation Errors
Duplicate Errors
Code Examples
JavaScript Import Flow
Best Practices
API Integration Patterns
API Base Configuration
Environment Setup
ApiService
Standard CRUD Operations
List with Pagination and Filters
Response Format
Create
Read (Get by ID)
Update
Delete
Authentication
Login Flow
JWT Token Handling
Token Refresh
Multi-Tenancy
Team Header Injection
Switching Teams
Advanced Filtering
Complex Filter Queries
Relation Filters
File Upload
Upload to S3
Error Handling
ErrorInterceptor
Validation Errors
Real-Time Updates
Polling Pattern
WebSocket (if implemented)
Batch Operations
Bulk Delete
Export/Import
Export to Excel
Import from Excel
Caching Strategies
Service-Level Caching
HTTP Caching Headers
Performance Tips
Deployment Guide
Architecture Overview
Prerequisites
Environment Configuration
Backend Environment Variables
Frontend Environment
Docker Deployment
Backend Dockerfile
Frontend Dockerfile
Frontend Nginx Config
Docker Compose
Deploy with Docker Compose
Kubernetes Deployment
Directory Structure
Backend Helm Values
Frontend Helm Values
Deploy with Helm
Manual Helm Commands
Database Setup
Initial Migration
Database Backup
SSL/TLS Configuration
Using cert-manager
Manual TLS Secret
Health Checks
Backend Health Endpoint
Kubernetes Probes
Monitoring & Logging
Application Logs
Metrics (Prometheus)
Log Aggregation
Scaling
Horizontal Pod Autoscaler
Database Scaling
Troubleshooting
Common Issues
Debug Mode
Rollback
Kubernetes Rollback
Helm Rollback
Security Checklist
Canvas LMS Integration
Overview
Configuration
Environment Variables
Getting an API Token
Sync Architecture
User Synchronization
Student Sync
Teacher Sync
Manual Sync Trigger
Course Synchronization
Course Creation
Blueprint Courses
Enrollment Synchronization
Student Enrollment
Teacher Enrollment
Assignment & Grade Sync
Import Assignments
Import Grades
Force Sync Student Assessments
Background Jobs
CanvasSyncJob
CanvasSyncCourseEnrollmentsJob
CanvasBlueprintSyncJob
Running Jobs Manually
API Endpoints
Course Template Endpoints
Canvas Data Endpoints
Error Handling
Sync Errors
Viewing Sync Errors
Common Errors
Password Synchronization
Monitoring
Sync Status Dashboard
Job Logs
Best Practices
LTI Integration Guide
Overview
Configuration
Environment Variables
LTI Endpoints
OIDC Configuration
JWKS (JSON Web Key Set)
Authorization
Launch
Canvas Setup
1. Create Developer Key
2. Install in Course/Account
Launch Flow
Security
Troubleshooting
OIDC/SSO Setup Guide
Overview
Supported Providers
Configuration
Add OIDC Provider (Admin API)
Login Flow
1. Initiate Login
2. Authorization
3. Callback
4. Token Exchange
5. User Provisioning
Provider Configuration Examples
Google Workspace
Microsoft Azure AD
Okta
Admin Endpoints
List Providers
Get Provider
Update Provider
Delete Provider
Get Provider Configuration
User Mapping
Security Considerations
Troubleshooting
SIS Documentation
Index
Index