Back to Projects
Jun 2024

Surau Quran API

One backend for student records, registration, attendance, tuition, teacher payroll, and Xendit payment/disbursement flows.

Overview

Surau Quran API handles student and teacher records, program registration, tuition, attendance, and teacher payroll. I built the schema, multi-role authentication, Xendit invoice/disbursement flows, recurring jobs, and PM2 deployment setup.

These workflows share the same people and finance records, so I kept them in one backend instead of splitting them into separate services.

One service was enough

The system runs as one API with one relational database.

Auth, students, finance, attendance, and payroll still have separate application logic, but the workload did not justify network boundaries between them. This kept deployment and data access simpler.

Role-based access

A central user identity maps to student, teacher, or administrator context. JWT middleware protects server routes based on that role.

Frontend visibility is not used as a permission check; access is enforced when the API receives the request.

Xendit callbacks

Xendit handles invoice and disbursement delivery. Callback handlers verify the request, load the current record, and only apply transitions that still make sense for that state.

This provides basic duplicate protection through persisted state. A stable provider event key with a database uniqueness constraint would make callback deduplication stronger.

Scheduled jobs

Small recurring jobs run in-process because the workload is limited and the jobs are repeatable.

If those jobs become heavy or must survive process failure with stronger guarantees, they should move to a durable queue/scheduler instead of making the current deployment more complex prematurely.

Current limits

The highest-value improvements are stronger authorization regression tests, provider-event deduplication, finance integration tests, and more durable scheduling where the workload actually requires it.

Gambaran umum

Surau Quran API mengelola siswa dan guru, pendaftaran program, SPP, presensi, serta payroll guru. Saya membangun schema, autentikasi multi-role, alur invoice/disbursement Xendit, recurring jobs, dan konfigurasi deployment PM2.

Semua workflow memakai data orang dan finansial yang sama, jadi saya memilih satu backend dibanding memecahnya menjadi beberapa service.

Satu service sudah cukup

Sistem berjalan sebagai satu API dengan satu relational database.

Auth, data siswa, finance, presensi, dan payroll tetap memiliki application logic masing-masing, tetapi workload belum memerlukan batas network antar-service. Ini menyederhanakan deployment dan akses data.

Role-based access

Identitas pengguna pusat dipetakan ke konteks siswa, guru, atau administrator. JWT middleware melindungi route server berdasarkan role tersebut.

Visibilitas di frontend bukan pemeriksaan izin; akses ditegakkan saat API menerima request.

Xendit callbacks

Xendit menangani invoice dan pengiriman disbursement. Callback handler memverifikasi request, memuat record terkini, dan hanya menerapkan transisi yang sesuai dengan state tersebut.

Ini memberikan perlindungan dasar terhadap duplikasi melalui state tersimpan. Provider event key stabil dengan database uniqueness constraint akan membuat deduplikasi lebih kuat.

Scheduled jobs

Recurring jobs kecil berjalan in-process karena workload terbatas dan job bisa diulang.

Jika job menjadi berat atau membutuhkan jaminan recovery dari process failure, proses tersebut sebaiknya dipindahkan ke durable queue/scheduler daripada menambah kompleksitas deployment terlalu dini.

Keterbatasan saat ini

Perbaikan yang paling bernilai adalah authorization regression tests, deduplikasi provider event, finance integration tests, dan scheduling yang lebih durable saat workload memerlukannya.

Resumen

Surau Quran API gestiona alumnos, docentes, inscripciones, cuotas, asistencia y payroll. Desarrollé el schema, autenticación multi-role, flujos de invoice/disbursement Xendit, recurring jobs y configuración de deployment PM2.

Todos los workflows comparten personas y registros financieros, por lo que mantuve un solo backend en lugar de separarlos en services.

Un único servicio era suficiente

El sistema funciona como una API con una relational database.

Auth, alumnos, finanzas, asistencia y payroll mantienen su lógica independiente, pero el workload no necesitaba límites de red entre services. Esto simplifica el deployment y el acceso a datos.

Role-based access

Una identidad central se asocia al contexto de alumno, docente o administrador. JWT middleware protege las rutas según el rol.

La visibilidad en el frontend no se considera control de permisos; la API verifica el acceso al recibir el request.

Callbacks de Xendit

Xendit gestiona invoices y disbursements. Los callback handlers verifican el request, consultan el registro actual y aplican únicamente transiciones compatibles con su state.

Esto proporciona protección básica contra duplicados mediante estado persistido. Un provider event key estable con database uniqueness constraint ofrecería deduplicación más sólida.

Scheduled jobs

Pequeños recurring jobs se ejecutan in-process porque el workload es limitado y las tareas son repetibles.

Si aumentan de tamaño o necesitan sobrevivir fallos del proceso, deberían migrarse a una durable queue/scheduler antes que complicar innecesariamente el deployment.

Límites actuales

Las mejoras prioritarias son authorization regression tests, deduplicación de provider events, finance integration tests y scheduling más durable cuando sea necesario.

Présentation

Surau Quran API gère élèves, enseignants, inscriptions, frais de scolarité, présence et payroll. J’ai réalisé le schema, l’authentification multi-role, les flux Xendit invoice/disbursement, les recurring jobs et le deployment PM2.

Ces workflows partagent les mêmes personnes et données financières ; j’ai donc choisi un backend unique plutôt que plusieurs services.

Un service suffisait

Le système fonctionne comme une API et une relational database.

Auth, élèves, finance, présence et payroll gardent leur logique séparée, mais le workload ne justifiait pas de communication réseau entre services. Cela simplifie le deployment et l’accès aux données.

Role-based access

Une identité centrale correspond à un élève, enseignant ou administrateur. JWT middleware protège les routes en fonction du rôle.

La visibilité dans le frontend n’est pas une vérification de permissions ; l’API contrôle l’accès lors de chaque requête.

Callbacks Xendit

Xendit fournit invoices et disbursements. Les callback handlers vérifient la requête, chargent le record actuel et appliquent seulement les transitions compatibles avec son state.

Le state persistant protège déjà contre certains doublons. Un provider event key stable avec database uniqueness constraint renforcerait la déduplication.

Scheduled jobs

De petits recurring jobs s’exécutent in-process, car le workload reste limité et ces tâches peuvent être rejouées.

Si elles deviennent lourdes ou doivent survivre à une panne du processus, une durable queue/scheduler serait préférable à une complexité prématurée du deployment.

Limites actuelles

Les priorités sont les authorization regression tests, la déduplication des provider events, les finance integration tests et un scheduling plus durable si nécessaire.

Überblick

Surau Quran API verwaltet Schüler- und Lehrerdaten, Anmeldung, Gebühren, Anwesenheit und Lehrer-Payroll. Ich entwickelte Schema, Multi-Role-Authentifizierung, Xendit-Invoice/Disbursement-Flows, Recurring Jobs und PM2-Deployment.

Die Workflows teilen dieselben Personen- und Finanzdaten. Deshalb wählte ich ein Backend statt getrennter Services.

Ein Service reichte aus

Das System läuft als eine API mit einer relationalen Datenbank.

Auth, Schüler, Finanzen, Anwesenheit und Payroll haben eigene Application Logic, doch der Workload erforderte keine Netzwerkgrenzen. Deployment und Datenzugriff blieben einfacher.

Role-based Access

Eine zentrale User-Identität wird dem Schüler-, Lehrer- oder Administrator-Kontext zugeordnet. JWT Middleware schützt Server-Routes entsprechend der Rolle.

Versteckte Frontend-Controls gelten nicht als Berechtigungsprüfung. Der API-Zugriff wird bei jedem Request geprüft.

Xendit Callbacks

Xendit übernimmt Invoice- und Disbursement-Verarbeitung. Callback Handlers prüfen Requests, laden den aktuellen Record und wenden nur für dessen State gültige Übergänge an.

Persistenter State bietet grundlegenden Duplikatschutz. Ein stabiler Provider Event Key mit Database Uniqueness Constraint würde die Deduplizierung verbessern.

Scheduled Jobs

Kleine Recurring Jobs laufen in-process, da der Workload begrenzt und die Jobs wiederholbar sind.

Werden sie umfangreicher oder benötigen zuverlässige Wiederherstellung nach Process Failure, sollten sie in eine Durable Queue/Scheduler wechseln, statt das Deployment voreilig zu verkomplizieren.

Aktuelle Grenzen

Die wichtigsten Verbesserungen sind Authorization Regression Tests, Provider-Event-Deduplizierung, Finance Integration Tests und bei Bedarf langlebigeres Scheduling.

概要

Surau Quran APIは生徒・教師情報、プログラム登録、授業料、出席、教師Payrollを管理します。私はSchema、Multi-role認証、Xendit Invoice/Disbursement Flow、Recurring Job、PM2 Deployment設定を担当しました。

これらのWorkflowは同じ人物情報と財務Recordを共有するため、複数Serviceに分割せず1つのBackendにまとめました。

1つのServiceで十分だった

システムは1つのAPIと1つのRelational Databaseで稼働します。

Auth、生徒、Finance、出席、PayrollのApplication Logicは分離していますが、WorkloadにはService間のNetwork境界は必要ありませんでした。これによりDeploymentとデータアクセスが簡潔になりました。

Role-based Access

共通のユーザーIDを生徒、教師、管理者のContextへ対応させ、JWT MiddlewareでRoleに応じたServer Routeを保護します。

Frontendの表示制御はアクセス権限の判定ではありません。APIがRequestを受け取る時点で権限を検証します。

Xendit Callbacks

XenditがInvoiceとDisbursementを処理します。Callback HandlerはRequestを検証し、現在のRecordを取得してStateに適合する遷移のみを適用します。

永続化されたStateで基本的な重複処理を防ぎますが、安定したProvider Event KeyとDatabase Uniqueness Constraintがあればさらに強化できます。

Scheduled Jobs

小規模で再実行可能なRecurring Jobは、現在のWorkloadに合わせてIn-processで実行しています。

Jobが重くなったりProcess Failure後の強いRecovery保証が必要になれば、Deploymentを複雑化するよりDurable Queue/Schedulerに移行するのが適切です。

現在の制約

優先課題はAuthorization Regression Tests、Provider Event重複排除、Finance Integration Tests、必要に応じたDurable Schedulingです。