Documentation

This application is an integrated pesantren (Islamic boarding school) administration system covering student (santri) management, new-student admissions (PPDB), attendance, finance, activities, student notes, and report cards. The system is multi-workspace: each pesantren (instance) has its own isolated workspace with its own configuration, access rights, and data.

All application identity — name, version, logo, pesantren name, address, bank accounts, and other policies — is stored in the database and can be changed from the interface, without changing program code.

A workspace is one isolated pesantren unit. Each workspace has its own modules, permissions, roles, routes, menus, users, and business data. Two workspaces never share data.

• System administrators can switch to any workspace using the workspace picker in the top bar.
• Regular users can only switch to workspaces where their account is registered (same username, active account).
• On switch, the session is re-issued to match the target workspace; menus, routes, and permissions are recalculated automatically.
• New workspaces are created by system administrators via System → Workspace (the configuration bootstrap runs automatically and is idempotent).
• Workspace identity (name, code, slug, contact, timezone, language, logo, status) can be edited with the "Edit" button on the same page.

Note: If the "Session invalid" screen appears, use the "Return to My Workspace" button to go back to your own workspace, or sign in again.

Sign in with the username and password provided by the workspace administrator. The workspace entered follows the workspace cookie (set via the top-bar workspace picker after login, or the login-time choice when more than one workspace is available).

Demo accounts are shown on the login page only when those accounts actually exist in the active workspace and the setting "Show demo accounts on the login page" (System → Settings, General group) allows it. On a clean production environment the list is automatically empty.

User access is determined by roles and direct permission overrides. Built-in roles include Administrator (all permissions), Student Affairs, Finance, Teachers, Education/Curriculum, and the PPDB Committee. Standard per-module permissions are Create, Read, Update, Delete, plus extras such as export.

• Roles are managed under System → Roles (add/remove permissions per role).
• Direct permissions can be granted or revoked per user under System → Users.
• System administrators have cross-workspace access and manage system-level configuration.
• Every application page verifies route, module, and permission automatically; if the check fails, the page shows "Access Denied".

• Students — student profiles, levels, classes, academic years, and status (active/returned/home-leave).
• PPDB — candidate registration, document verification, selection stages, and public status checking.
• Attendance — daily per-class attendance with presence statistics.
• Finance — cash & transfer payments (with proof verification), invoices, and tiered refund approvals.
• Activities & Calendar — pesantren program activities and agenda.
• Notes — progress notes, case handling, and workflow-based follow-ups.
• Report Cards — per-subject grading, ranking, and grade reporting.

Each module can be enabled/disabled and configured (menus, routes, permissions) via System → Modules, Routes, and Menus. Adding a module only creates entities that do not yet exist — the bootstrap is idempotent and never duplicates data.

Everything that was previously fixed is now managed from the interface:

• System → Settings — pesantren name & address, report header, currency, bank accounts, NPSN, NIS prefix, required PPDB documents, and display flags (e.g. show demo accounts).
• System → Application — application name, code, version, base URL, and logo (replaces previously hardcoded text in footers, export documents, and page metadata).
• System → Workspace — workspace list, creating new workspaces, editing workspace identity, and re-running the bootstrap.
• System → Modules / Routes / Menus / Permissions / Roles — per-workspace application structure configuration.

Note: Changing the application name/version under System → Application immediately reflects in the app footer, export document header & metadata, and the browser tab title.

Data can be exported to Excel (.xlsx), CSV, and PDF via export links on list pages. The document header, publisher name, and version in the files come from the active settings & application record — not fixed text.

Every export is recorded in the audit log (who, when, type, row count, and filters used).

Important activities (login, logout, workspace switch, data creation/changes, exports, user & role administration) are recorded per workspace and can be viewed under System → Audit. Audit columns (created by/at, modified by/at) are filled automatically by database triggers on all persistent tables.

The application uses Bahasa Indonesia as its primary language. This documentation is available in Bahasa Indonesia at the non-prefixed address and in English at the "/en"-prefixed address. Use the language switcher in the documentation header to change languages.

Note: Other languages (if added later) inherit the Bahasa Indonesia translation for keys that are not yet provided.

The application uses Next.js (App Router) + PocketBase (REST API, via the `src/lib/db/` adapter) + JWT cookie sessions. Database setup: the schema is applied, then a per-workspace bootstrap (modules, permissions, roles, routes, menus, initial settings, and the first administrator) runs.

1. Provision PocketBase and fill in environment variables (URL + superuser credentials, JWT secret, etc.).
2. Run the schema migration (npm run db:migrate) — idempotent.
3. Run the seed/bootstrap (npm run db:seed) to create the demo workspace + demo accounts, or create a workspace via the /setup page.
4. Run the application (npm run dev / npm start). The administration instance runs on port 9003 and the public PPDB instance on port 9002 (per-instance mode is set via environment variables).