Installation

Complete guide to installing InstitutionKit on your WordPress site.

System Requirements

Installation Steps

1. Upload the Plugin

Via WordPress Admin: Go to Plugins → Add New → Upload Plugin, choose institutionkit.zip, click Install, then Activate.

Via FTP: Extract and upload to /wp-content/plugins/, then activate from Plugins menu.

2. Automatic Setup

Upon activation, InstitutionKit creates 40+ custom database tables, registers 5 custom post types (ik_student, ik_class, ik_exam, ik_certificate, ik_period), registers 2 taxonomies, creates 5 user roles, inserts default data, and creates the default "Main Campus".

Troubleshooting

Tables not created: Go to Settings → System Status → Recreate Tables.

Memory exhausted: Add to wp-config.php:

define('WP_MEMORY_LIMIT', '256M');
define('WP_MAX_MEMORY_LIMIT', '512M');

Quick Setup Guide

Configure InstitutionKit for your school in under 30 minutes.

Step 1: Configure Your Campus

Go to InstitutionKit → Campuses. Edit "Main Campus":

Step 2: Classes

Go to Setup → Classes. Add "Grade 1", "Grade 2", etc.

Step 3: Subjects

Go to Setup → Subjects. Add Mathematics, English, Science and assign to classes.

Step 4: Sections (Optional)

Go to Setup → Sections. Add "A", "B", "C".

Step 5: Grading Periods

Step 6: Grade Scale

Step 7: Fee Types & Structures

Create fee types (Tuition, Transport, Library) and structures with amounts per class at Fee Management.

Step 8: Add Staff

Go to Payroll & Expenses → Staff. Add staff with name, email, role, campus, and contract type. Teaching staff automatically get WordPress accounts with welcome emails.

Step 9: School Settings

Set currency symbol, school hours, and academic year at InstitutionKit → Settings.

License Activation

Activate your license to receive updates and premium support.

Activation Steps

1. Go to InstitutionKit → Settings → License
2. Enter your key (format: IK-XXXX-XXXX-XXXX-XXXX)
3. Click Activate License

Troubleshooting

Multi-Campus Architecture

True multi-tenancy — unlimited campuses with complete data isolation.

Core Principles

Two-Tier Admin Model

Data Partitioning Layers

Custom Tables

SELECT * FROM wp_institutionkit_attendance WHERE campus_id = 3;

Post Meta

SELECT p.ID FROM wp_posts p JOIN wp_postmeta pm ON p.ID = pm.post_id WHERE pm.meta_key = '_ik_campus_id' AND pm.meta_value = 3;

Application Context

$campus_id = IK_Campus_Manager::get_current_campus_id(); // 0=All, 1-99=specific

Cross-Campus Financial Intelligence

Roles & Capabilities

62 custom capabilities across 5 user roles with granular access control.

Role Comparison

Campus Management Deep-Dive

Technical architecture of campus context, data partitioning, and the campus switcher.

Campus Context Lifecycle

// Runs on every admin page load at priority 5
IK_Campus_Manager::determine_current_campus();

// Returns 0 for "All Campuses", 1-99 for specific campus
$campus_id = IK_Campus_Manager::get_current_campus_id();

SQL Filtering

// For custom tables — returns " AND i.campus_id = 3" or ""
$where = IK_Campus_Manager::get_campus_where_clause('i');

// For WordPress posts — returns meta query fragments
$filter = IK_Campus_Manager::get_campus_sql_filter();
$join = IK_Campus_Manager::get_campus_join_clause();

Campus Switcher

Super Admins access the switcher from Admin Bar (location icon dropdown), Dashboard (inline form dropdown), or URL parameter (?campus_id=X). Campus selection persists via 1-hour transient.

Transient Persistence

set_transient('ik_current_campus_' . $user_id, $campus_id, HOUR_IN_SECONDS);
$saved = get_transient('ik_current_campus_' . $user_id);

Database Schema

40+ custom tables powering every module of InstitutionKit.

Table Organization

Key Unique Constraints

Custom Post Types & Taxonomies

5 CPTs and 2 taxonomies for core educational entities.

Custom Post Types

Taxonomies

Security Model

7-layer security architecture protecting every aspect of the system.

Security Layers

1. WordPress Authentication — Every page requires valid login
2. Role Verification — Role-specific access checks
3. Capability Enforcement — 62 granular capabilities
4. Campus Boundary — SQL-level data isolation
5. Nonce Verification — CSRF protection on all forms
6. Data Sanitization — All input sanitized before processing
7. SQL Escaping — All queries use $wpdb->prepare()

Capability Check Pattern

private function verify_access($caps) {
    if (current_user_can('manage_options')) return;
    if (is_string($caps) && current_user_can($caps)) return;
    if (is_array($caps)) {
        foreach ($caps as $cap) {
            if (current_user_can($cap)) return;
        }
    }
    wp_die('Permission denied.');
}

Dashboard

Command center with real-time stats, attendance, financial summaries, and quick actions.

The dashboard displays 4 key stat cards (Students, Teachers, Classes, Subjects), today's attendance for both students and staff with clickable drill-downs, a 7-day attendance trend chart, fee management summary (outstanding, collected, overdue, collection rate), announcements, upcoming events, performance charts, outstanding fees by class, recent payments, and 9 quick action buttons.

Fee Summary Cards

Student Management

Complete student lifecycle — admission, attendance, promotion, certificates.

The Student Management dashboard provides 12 action cards: All Students, Add New Student, New Admission, Homework, Student Attendance, Gradebook, Campus Transfer, Student Promotion, Assign Homework, All Grading Periods, Certificates, and Attendance Report.

Student Meta Fields

Students are stored as ik_student posts with 20+ meta fields including class, campus, roll number, date of birth, gender, guardian information, parent contacts, address, and emergency contact.

New Admission

Process new student enrollments with full data collection.

Access via Student Management → New Admission (admin) or [institutionkit_admission_form] shortcode (frontend). The form collects student information (name, DOB, gender, class), guardian details, parent contacts, ID card (validated as 13-digit), and address.

Validation Rules

Student Attendance

Daily attendance tracking with four status options.

Access via Student Management → Attendance (admin) or [institutionkit_attendance] shortcode (frontend). Status options: Present, Absent, Late, On Leave. Remarks field dynamically shown for Late/Leave status.

Teachers are campus-restricted via primary_campus_id from the staff table. After saving, the frontend form becomes read-only showing who submitted and when.

Student Promotion

End-of-year class advancement with full history tracking.

Promotions move students between classes and record the transition in ik_student_promotions with academic year, performance percentage, status (promoted/retained), and the promoting user. Supports bulk promotion and individual promotion with manual override.

Certificates

Generate Leaving, Character, Achievement, and Employment certificates.

Four certificate types supported: Leaving Certificate, Character Certificate, Achievement Certificate, Employment Certificate. Each certificate gets a unique number. Public verification available via [ik_certificate_verify] shortcode.

Teacher & Staff Management

Complete staff lifecycle — hiring, contracts, attendance, meetings.

All staff are stored in institutionkit_staff table (not WordPress posts). 8 predefined roles: Permanent Teacher, Visiting Teacher, Campus Head, Office Staff, Roving Admin, Maintenance, Security, Other. Teaching roles automatically get WordPress user accounts with welcome emails.

Staff Records

Add, edit, and manage all staff members.

The Add/Edit Staff modal includes 7 sections: Personal Information, Profile Photo (WordPress media library), Salary Information (dynamic fields per contract type), Bank Details, Emergency Contact, Salary Components (flexible earnings/deductions), and Loans. Employee codes auto-generate as EMP{YY}{XXXX}.

Contract Types

Staff Attendance

Daily staff attendance with time tracking.

Records check-in, check-out, hours worked, and lectures delivered. Status options: Present, Absent, Half Day, Leave. Check-in/out auto-filled from school operating hours. Emergency contact displayed for Absent/Leave status. Bulk actions: Mark All Present/Absent/Leave.

Parent-Teacher Meetings

Slot creation, parent booking, topic management, and feedback.

Teachers create availability slots with date, time, duration, max bookings, and location. Parents book via Parent Portal with topic selection. 10 predefined discussion topics included. Booking increments current_bookings; slots auto-mark as "Full" when capacity reached.

Teacher Comments

Two-way communication between teachers and parents.

Teachers leave comments about students with type classification (General, Academic, Behavioral, Attendance). Parents view comments in Parent Portal and can respond. Read status tracked. Comments reference staff_id from the staff table.

Fee Management

Complete financial lifecycle — fee types, structures, invoices, payments.

Four action cards: Fee Types (define categories), Fee Structures (group types with amounts per class), Assign Fees (apply to students individually or by class), Invoices (generate and manage bills). Auto monthly invoice generation via cron on the 1st of each month at 06:00.

Fee Types

Define categories of fees your institution charges.

Simple name-based definition. Common types: Tuition Fee, Admission Fee, Exam Fee, Transport Fee, Library Fee, Sports Fee, Computer Lab Fee, Development Fee. Fee types flow through: Types → Structures → Student Assignments → Invoice Items.

Fee Structures

Group fee types with amounts into reusable billing templates.

Example: "Primary Monthly Fees" = Tuition (3,500) + Transport (1,000) + Library (200) = 4,700. Structures can differ per class level, campus, or academic year. Assigned to students individually or by class/campus.

Invoices

Generate, track, and manage student invoices with PDF download.

Invoice status flow: Unpaid → Partial → Paid. Payment recording validates against balance due — cannot overpay. AJAX payment updates UI dynamically. PDF download with Dompdf. Overdue reminders via cron and manual trigger. Campus-restricted for staff.

Invoice Status Colors

Exams Management

Complete examination system — 7 categories, scheduling, verification workflow.

Workflow: Create Exam Types → Schedule Exams → Enter Results → Verify → Publish → Generate Report Cards → Analytics. Results workflow: Draft → Submitted → Verified → Published. 7 categories: Term, Midterm, Final, Monthly, Board, Quiz, Assessment.

Exam Types

Define exam categories with marks and weight configuration.

Properties: Name, Category (7 types), Max Marks (default 100), Weight Percentage (for final calculation). Soft delete protection — types used in schedules are deactivated instead of deleted. Campus-scoped.

Exam Schedule

Create date sheets with subjects, times, rooms, and invigilators.

Fields: Exam Type, Class, Subject, Date, Start/End Time, Room Number, Invigilator, Max Marks, Passing Marks. Status: Draft or Published. Published schedules appear in result entry dropdowns.

Result Entry

Enter marks, verify, and publish exam results.

Grade auto-calculation as marks are entered. Status workflow: Draft (teacher editing) → Submitted (ready for verification, locked) → Verified (checked by verifier) → Published (visible to students/parents). Unique constraint: one result per student per exam schedule.

Report Cards

Generate comprehensive report cards with PDF download.

Includes: Student info, subject-wise marks, total, percentage, GPA, class rank, attendance percentage, teacher/principal remarks. Supports individual and bulk generation. PDF via Dompdf with watermark.

Exam Analytics

Class performance, subject analysis, student tracking, comparisons.

Four views: Class Performance (averages by class), Subject Analysis (performance by subject), Student Performance (individual progress tracking), Comparative Analysis (cross-exam/cross-campus comparison). Data sourced from exam results, schedules, and report cards.

Payroll & Expenses

Complete financial suite — payroll, expenses, budgets, collections.

Module architecture uses 12 traits: Core_Setup, Render_Dashboard, Render_Expenses, Render_Staff, Render_Payroll, Render_Financial, Ajax_Handlers, Helpers, Salary_Structure, Loans, Payslips, PDF_Export. 18 AJAX endpoints registered. Dashboard data cached for 5 minutes via transients.

Payroll Dashboard

Financial overview with stats, charts, comparisons, and alerts.

Four stat cards: Revenue (MTD), Expenses (MTD), Payroll (MTD), Net Surplus. Charts: Monthly trend (6 months), Expense breakdown (top 5 heads), Campus comparison. Automated alerts: budget overruns, unbudgeted expenses, large transactions, missing recurring, spending spikes.

Staff Management (Payroll)

Employee records with contracts, salary components, and loans.

Staff modal with 7 sections. Auto-account creation for teaching/admin roles with welcome email. Employee codes: EMP{YY}{XXXX}. Flexible salary components (earnings + deductions). Complete loan management with EMI auto-calculation and payroll deduction.

Payroll Processing

Generate monthly payroll with automatic calculations.

Payroll = Base Salary (from contract) + Salary Components - Attendance Deductions - Loan Deductions - Income Tax. Income tax brackets: 0% (≤50k), 2.5% (50k-100k), 12.5% (100k-167k), 17.5% (167k-233k), 22.5% (233k-300k), 27.5% (>300k). Loan installments auto-processed on payroll generation.

Expense Management

Record, approve, and track all campus expenditures.

Payment sources: Campus Petty Cash, Central Admin, Split. Approval tiers: Level 1 (≤10k), Level 2 (10k-50k), Level 3 (>50k). Status flow: Pending → Approved → Reimbursed (or Rejected). 15 default expense heads created on installation. Severity flags: Green (routine), Yellow (important), Red (emergency).

Budget Management

Set monthly spending limits and track actuals per expense head.

One budget per campus + expense head + month (unique constraint). Status indicators: On Track (<80% used), Near Limit (80-99%), Over Budget (≥100%). Summary cards: Total Budget, Actual Spent, Remaining, Utilization %. Alerts trigger at 90% and 100% of budget.

Payslips

Detailed salary statements — HTML view and PDF download.

Payslip sections: Employee Info, Attendance Summary (5 badges), Earnings breakdown, Deductions breakdown (absent, tax, loans, components), Net Payable. PDF via Dompdf with "PAYSLIP" watermark. Amounts rounded to nearest 10. Print-optimized CSS. Working days exclude Sundays.

Gradebook

Multi-period grading system with automatic grade calculation.

Uses ik_grades_v2 table with unique constraint (student_id, subject_id, period_id). Grading periods: Weekly, Monthly, Quarterly, Yearly, Exam. Weighted average formula: SUM(Percentage × Weight) / SUM(Weights). Frontend gradebook via [institutionkit_gradebook] shortcode with real-time calculation, bulk operations, and keyboard navigation.

Grading Periods

Time frames for assessing student performance.

5 period types with configurable weights: Weekly (0.25-0.50), Monthly (1.00), Quarterly (1.50-2.00), Yearly (3.00-5.00), Exam (2.00-3.00). Meta box fields: type, start/end date, academic year, weight, published status. Published periods make grades visible to students/parents.

Grade Scales

Percentage-to-grade mapping with GPA points.

Default 11-point scale: A+ (90-100, GPA 4.00) through F (0-49, GPA 0.00). Campus-specific scales supported. Scale cache via wp_cache with 1-hour expiry. Frontend gradebook uses simplified scale: A++ (98+), A+ (95+), A (90+), B (80+), C (65+), D (55+/40+), F (<40).

Grade Entry

Teacher interface for entering student marks.

Filter by period type, period, class, section, subject. Real-time percentage and grade calculation. Bulk operations: Fill All Marks, Set Max Marks, Apply Global Max. Keyboard navigation: Enter moves to next student; last student submits. AJAX save with upsert logic. Campus-restricted for teachers.

Homework Management

Create, assign, submit, and grade homework.

Fields: Class, Section, Subject, Title, Description, Attachment, Due Date. Recurring homework support (Daily/Weekly/Monthly with interval). Status: Active, Archived. Submission tracking with grade and feedback. Parents view via Parent Portal.

Parent Portal

Standalone application for parent access to student data.

Accessed at /parent-portal.php. Bypasses WordPress theme entirely. Sections: Student Profile, Academic Performance (dynamic — weekly/monthly/yearly/fallback), Homework, Teacher Comments (two-way), Fee Invoices, Upcoming Meetings (with booking). 4 AJAX endpoints for meetings and comments. Role-restricted to parent role only.

Frontend Modules

Public-facing modules extending InstitutionKit to your website.

All modules follow singleton pattern with campus restriction, nonce verification, and input sanitization.

Hooks & Filters

Extend InstitutionKit without modifying core files.

Available Hooks

Recommended custom hooks: ik_student_created, ik_student_promoted, ik_invoice_generated, ik_payment_recorded, ik_payroll_generated, ik_attendance_saved.

AJAX Endpoints

Complete reference of all AJAX handlers.

Exams Module

Centralized via ik_exam_ajax_handler with method parameter. 20+ methods: save_exam_type, save_schedule, save_results, verify_results, publish_results, generate_report_card, get_class_performance, etc.

Payroll Module

18 separate actions: ik_add_expense, ik_get_expenses, ik_approve_expense, ik_reject_expense, ik_add_staff, ik_generate_payroll, ik_get_payroll, ik_get_financial_summary, ik_get_dashboard_data, ik_add_loan, ik_get_payslip, etc.

Parent Portal

4 actions: ik_parent_get_upcoming_meetings, ik_parent_get_available_slots, ik_parent_book_meeting, ik_parent_respond_comment.

Database Tables Reference

Quick lookup for all 40+ custom tables.

All tables use WordPress prefix. Key relationships: institutionkit_staff links to attendance, salary components, loans, payroll, and meeting slots. wp_posts (ik_student) links to attendance, invoices, grades, exam results, report cards, parent links, and teacher comments. institutionkit_invoices links to invoice items and transactions.

Capabilities Reference

All 62 custom capabilities by module and role.

Shortcodes Reference

All available shortcodes for frontend integration.

Extending InstitutionKit

Best practices for custom development and integration.

Extension Methods

1. WordPress Hooks — Add behavior at specific points
2. Filter Hooks — Modify data before output
3. Class Extension — Add features to existing modules
4. Database Extension — Add custom tables and CRUD methods

Best Practices

• Never modify core plugin files
• Check for class existence with class_exists()
• Respect campus boundaries using IK_Campus_Manager
• Use proper nonces in all custom handlers
• Sanitize ALL input, escape ALL output
• Capability-check everything with current_user_can()

Troubleshooting

Solutions for common issues.

Common Issues

Changelog

Version history and upgrade notes.

v1.2.1 (Current)

License banner improvements, dashboard optimizations, bug fixes.

v1.2.0

Major: Teacher CPT removed — all staff in institutionkit_staff table. Payroll module (12 traits, 18 AJAX endpoints). Expense management with approval workflow. Budget planning. Staff loans with EMI. Payslips (HTML + PDF). Multi-campus financial comparison. Financial alerts. 12 new database tables.

v1.1.0

Multi-campus support. Gradebook Pro (v2). Exam Pro module. Homework. Meetings. Announcements & Events. 20+ new database tables.

v1.0.0

Initial release. Student management, fee management, attendance, basic gradebook, email notifications, settings.