E-Pondok Developer Reference

E-Pondok is a presence & relations system for the modern pondok. A browser camera at the gate records who comes and goes, a digital guest book manages visits, and the dashboard weaves that data into reports and a living map of institutional relationships.

Built for the realities of a pondok: it grows with many pondok (multi-tenancy) and keeps things secure without heavy operational burden.

What you get

• Touchless face attendance with automatic entry/exit detection, plus an offline kiosk for the gate.
• Anti-spoofing — rejects photos, videos, and fake face masks.
• Academics: cohorts, memorization, report cards, and daily-deed tracking with per-student reports.
• Finance & payroll: SPP invoices, QRIS/transfer payments, emailed receipts, payroll from real attendance.
• Pondok modules: library, clinic, dormitory, online admission, conduct, inventory, permits, EMIS, and an AI assistant.
• Digital guest book with categories, purpose, and visit contributions.
• Automatic parent updates: an email on every check-in/check-out, proof photo included.
• Summary dashboard + attendance analytics.
• Passwordless magic-link login for every user.

Pondok = tenant

One pondok is one isolated tenant. Every pondok gets its own subdomain, e.g. pondokabc.epondok.id. Its data never mixes with another pondok’s, even though they share one database cluster.

Three surfaces

• Apex. The parent domain epondok.id for the public landing, signup, checkout, and these docs.
• Platform. The platform.epondok.id subdomain for super-admins who manage accounts, subscriptions, and new pondok provisioning.
• Tenant. The *.epondok.id subdomain for each pondok’s admin app (dashboard, attendance, visitors, and relations).

Roles

A person in a pondok has one of the following roles:

App-level admin roles: admin (full access including Payroll & Finance), pengurus, and platform (super-admin at apex).

From zero to automatic attendance in five steps.

The tenant home page. A real-time summary across all modules. Data source: GET /api/dashboard.

Summary cards

• Attendance — present today, absent, late, total population, daily trend.
• Visitors — visits today, this month, lecturer visits over 3 years.
• Relations — new, active partners, potential, strategic, alumni network.
• Follow-ups — number due.

Person = every individual in the pondok (santri, ustadz, staff, pengurus). Full CRUD via /api/persons.

Face enrollment

Enrollment captures a face, converts it to a 512-dimensional embedding, then stores it as an indexed per-pondok template. On enroll, the checkDuplicates option prevents the same face from being registered twice, and qualityScore records capture quality.

capture frame
→ anti-spoofing check        // reject photo/video/mask
→ 512-d face template
→ POST /api/persons/:id/enrollments
      { embedding, deviceId, qualityScore, checkDuplicates: true }

• POST /api/persons/:id/verify-face. Match a new embedding against the person’s enrollments.
• DELETE /api/persons/:id/enrollments/:eid. Deactivate an old enrollment rather than deleting it permanently.

The product’s core. The check-in camera — the web Check-in page on any webcam device — captures a face at the gate → matches it against the pondok’s face index → entry/exit direction is detected automatically → the event is stored with a confidence score (confidence) and, when applicable, a device id (device_id).

Queries

• GET /api/attendance. Event list (Paged), filterable by personId, role, from, and to.
• GET /api/attendance/presence. Who is currently inside.
• GET /api/attendance/analytics. Daily in/out totals, most-late, most-punctual, with time-range and role filters.

The digital guest book. Every visit carries a category, a purpose, check-in/out times, and a visitor number (visitor_no).

Categories

parent_guardianlecturerteachergovernment_officialcommunity_leaderalumnivendorgeneralother

Visit contributions

Each visit can record a contribution for reporting — workshop, guest_lecture, training, mentoring, community_service, research_collaboration, recruitment_opportunity, or other — with topic, audience, participants, and outcomes.

The pondok’s living institutional network, kept traceable over time.

Contacts

RelationshipContact stores name, institution, title, expertise, status (new / active / potential / alumni / strategic), and notes.

Collaboration tags

CollaborationTag (slug + label) can be attached or removed from contacts to group partners, e.g. guest-teacher and scholarship.

Follow-ups

Scheduled follow-ups: contact_id, due_date, assigned_to, status (open / in_progress / completed / cancelled). The overdue filter highlights what’s past due.

Every module below follows the same pattern: a paginated list (Paged<T>), writes via POST/PATCH, soft delete (trash + restore), and CSV export. Full routes are in the API reference tables below. Modules tied to a plan tier answer 402 payment_required when the pondok’s plan doesn’t cover them.

Academic

/api/academic — cohorts (classes / halaqah) with bulk import, memorization records per student, and report-card periods.

Mutaba’ah (daily deeds)

/api/mutabaah — pondok-owned daily-deed templates, per-student entries with ratings, and GET /summary for the per-student report: current streak, longest streak, per-deed progress, and average rating.

Payroll

/api/payroll — staff salary profiles, payroll runs generated per period from real attendance (including late deductions), then lock & email payslips.

Parent notifications

/api/notifications — automatic emails on student check-in/check-out (optionally with a proof photo), Email/WhatsApp/Telegram channels, and a delivery log with per-notification status.

Library

/api/perpustakaan — book catalog, per-copy codes, due-dated loans + email reminders, and reservations.

Clinic & health (UKS)

/api/kesehatan — clinic visits (complaint → diagnosis → treatment), medication given, incidents, and immunizations.

Dormitory

/api/asrama — building → room → bed, student placement, and gate passes (leave / home visit) with approval.

Admission (PPDB)

/api/ppdb — a public application form on the pondok’s subdomain, applicant review, accept (becomes a student + enrollment invoice), and period settings.

Finance

/api/finance — fee items, per-period invoices (auto-generated per cohort), multi-method payments with emailed receipts, arrears recap, and payment reminders.

Conduct (tata tertib)

/api/tata-tertib — a point-based violation catalog, incident logging, cumulative points per student, and graduated sanctions.

Inventory

/api/inventaris — assets with condition/location/value, asset lending, and a movement log.

Leave permits

/api/keperizinan — home-leave/out-pass/sick requests with request → approve/reject → return flow, plus parent notification.

EMIS

/api/emis — student data completeness checks for EMIS reporting (flags only, no NIK/NISN values), a CSV export in documented column order, and /api/emis/santri/rows (JSON, includes NIK; admin/pengurus only) which the dashboard uses to build the .xlsx export and fill an uploaded EMIS template in the browser.

AI assistant

/api/asisten — student anomaly summaries from attendance/memorization/clinic data (/brief), and Ask the Kitab under /api/asisten/kitab: upload and manage the kitab corpus, then ask questions answered with references (answers stream over SSE).

Device management API for hardware clients. Attendance currently runs web-first, so the Devices page is hidden in the admin app and no device registration is needed for daily use. Every registered kiosk has its own unique identity and key; each sync request is verified before processing, and a revoked kiosk is rejected outright.

• POST /api/devices/register. Register a new kiosk.
• POST /api/devices/:id/revoke. Revoke access so the kiosk can no longer sync.
• POST /api/devices/:id/activate. Reactivate a kiosk.
• last_seen_at tracks the last successful sync.

The platform surface (platform.epondok.id) is the super-admin space for provisioning new pondok, managing subscriptions, and changing pondok status (active / suspended). Platform tokens are separate from tenant tokens because the two live on different origins.

One system, many pondok. Each pondok gets its own subdomain and isolated data. Access is enforced in the platform’s data layer — no tenant endpoint can read another pondok’s records.

Passwordless login: request a link by email, click to sign in. Links are single-use and expire quickly. A password remains available as a fallback for platform admins.

Pondok isolation is layered: subdomain → pondok resolution, pondok_id on every row, and the pondok id carried inside each token. No tenant endpoint can read another pondok’s data. All traffic is encrypted in transit (TLS).

Your pondok’s data is a trust. The principles we keep:

• Tenant isolation. Your pondok’s data can never be read by another pondok — enforced in the access layer, not just the UI.
• Encrypted in transit. All traffic runs over TLS.
• Face = template, not photo. What’s stored is a 512-dimensional mathematical template that cannot be reversed into a face image. Templates are per-pondok and can be deactivated at any time.
• Anti-spoofing. Frames are checked by an anti-spoofing model before processing; printed photos, videos, and masks are rejected.
• On-device face processing. Detection and template creation run locally in the gate’s browser/device — raw images are never shared with third parties.
• Soft delete + archive. Deleted data is recoverable during the trash window, then disappears from every list.
• Sensitive data stays home. NIK and NISN appear only in admin/pengurus EMIS downloads and are never sent to Kemenag or any third party; an uploaded EMIS template is filled in the browser, not on our server.

Before a face template is created, the frame is checked by an anti-spoofing model to tell a real face apart from a photo, video, or mask. Only a real face is processed further. The check runs on the gate device (web or kiosk) without sending images to any third party.

Core entities and their key fields:

All tenant entities also carry pondok_id for isolation.

JSON API behind the app. Session tokens and API keys both authenticate — create a key under Settings → API keys and send X-API-Key: pk_live_… per request to the pondok subdomain. Keys are shown once at creation and revocable anytime. Plan-gated modules answer 402 payment_required. Every list route returns a paginated envelope:

{
"items":  T[],
"total":  number,
"limit":  number,
"offset": number
}

Example request with a token:

curl -H "Authorization: Bearer <token>" "https://pondokabc.epondok.id/api/attendance?from=2026-01-01&limit=50"

Tenant routes

Platform routes (apex)