XPrivate v2 — Admin-MVP-1 Design Plan

0. READ THIS FIRST — Context & Background

0.1 Tentang XPrivate (product context)

XPrivate = Indonesian les-privat (private tutoring) marketplace. Operational platform existing dengan 4 sub-systems:

• xp-backend — Spring Boot 3.1.10, Java 17, PostgreSQL 15
• xp-app — Angular 20 PWA buat siswa + tutor
• xp-backoffice — Angular 20 + Clarity v17 admin panel buat operator
• xp-landingpage — Next.js 15 marketing + WhatsApp lead capture

Customer base: orangtua + siswa (SD - Mahasiswa - Profesional), tutor (independent contractor, golongan tier 1-4 + non-gol). Postpaid monthly billing. Sesi di rumah siswa atau online (Zoom manual). Indonesia Jakarta-region primarily.

0.2 Why greenfield rewrite (bukan selective refactor)

Existing platform punya tech debt yang block fitur baru + ops scale:

• Schedule state machine kacau: /schedule/cancel ≠ terminate (re-queue ke SUB), /schedule/start no state validation (callable any status), 3 asymmetric /confirm/* endpoints behave significantly different
• Pricing flat per-row di TypeStudent/TypeTeacher table, no versioning — historical billing accidentally protected by amount snapshot only at confirm time
• No audit log despite admin sentral di 6 financial touch-points (create / approve / cancel / finalize / reconcile bill / reconcile payout)
• No bulk operations — per-row click untuk monthly mark-paid honorarium = #1 ops pain documented
• Notification surface kosong — 1 template (registForm) wired ke HR email only, despite full MailTemplate infra
• Photo PUBLIC_READ di CDN including ID cards (security gap)
• OAuth2 client credentials hardcoded di xp-app source (base64 mobile:Xpedu123)
• TimeSlot double-booking possible — no DB unique constraint, race condition concurrent create

Hard deadline driver: Tahun Ajaran Jul 2026 enrollment. Pricing matrix wajib aktif sebelum siswa daftar ulang TA baru. Selip = kehilangan enrollment cycle.

Decision lock: greenfield rebuild full, BUKAN selective refactor. Legacy 4 repos di-deprecate. Data migration deferred (fresh schema v2, bulk-import reference data only — Tutor, Siswa, Subject, Tingkat, Config — transactional history archive read-only).

0.3 Why admin-first iter

Iter 1 = admin/ops backoffice ONLY. Customer-facing (siswa/tutor self-service) defer iter berikutnya. Reasoning:

1. De-risk foundation — operator catch bugs sebelum customer kena impact
2. Smaller user surface — admin = 1-5 orang vs customer = ratusan/ribuan. Iterate fast tanpa support load
3. Validate data model — pricing matrix + state machine v2 + snapshot pattern proven jalan untuk ops sebelum expose ke customer
4. Industry pattern — Stripe, Shopify, Square = backoffice-first then customer-facing

0.4 Why this stack (locked)

• Modern 2026 stack, AI-friendly (AI Claude well-trained on TanStack ecosystem + React 19 + shadcn/ui)
• Founder + partner both fluent (no learning curve cost) + Ralph loop velocity (snake_case data + camelCase code = LLM consistency win)
• Cloudflare Workers + Neon Postgres 18 + Hyperdrive = serverless, auto-scale, low ops burden, edge-cached connection pool
• shadcn/ui + Tailwind v4 = pre-built accessible components, accelerate UI dev (kompensasi sprint ketat), official TanStack Form integration
• TanStack universe (Start + Form + Query + Router + Table) = one ecosystem, integrated routing + data + form state, type-safe end-to-end
• React 19 = mature ecosystem, broadest hiring pool, Compiler auto-memo (eliminates useMemo/useCallback boilerplate)
• Hono /api/* + @hono/zod-openapi = auto-generated OpenAPI spec from Zod, minimal API ceremony
• Better Auth + Negation ACL = permission-list-based RBAC (NOT role-based), future-proof for team support iter-3+
• Cloudflare R2 zero egress cost + S3 presigned URL pattern (full private ACL iter-1, PDP UU 27/2022 compliance step)
• SigNoz OpenTelemetry-based observability
• Paraglide JS ~5kb runtime i18n, type-safe message functions, AI-friendly DX (BI iter-1 + EN iter-2 ready)

Engineering implementation micro-decisions (ORM, routing, validation lib, monorepo tool, repo structure, deployment pipeline, testing strategy) = partner authority (see Section 3).

0.5 Why Option (b) cancellation policy (financial double-down)

Multi-voice council review (Architect + Skeptic + Pragmatist + Critic premortem + Forecaster + Red-Teamer) recommended Option (a) — industry standard zero pay + 3-strike access sanction (mirror Italki / Preply / Cambly pattern).

Founder override pilih Option (b) — zero pay + additional 1-sesi denda graduated (100%/50%/25% berdasar lead time). Rationale:

• Kontrak existing udah cover explicit deduction language
• Tutor accountability culture di Indonesian formal tutoring
• Stronger deterrent than access-only sanction
• Risk accepted: tutor 12-mo retention projected 38% (vs Option a 55%) — kill criterion 90d post-launch kalo retention <40% → revisit

Full council voices + decision log: companion file 2026-05-25-xprivate-tutor-cancel-policy-v1.md (Downloads). Wajib baca kalo lu mau understand WHY policy keras ini chosen against council recommendation.

0.6 Existing platform reference state (legacy)

Legacy 4 sub-repos tetap accessible buat reference behavior current. Lu udah ada akses (per founder confirm 2026-05-25):

Detailed code-level archaeology available on-demand: file 2026-05-23-business-flow-overview.md (~51KB, 600 lines). Cover 9 domain modules, endpoint inventory, state machine current behavior, file storage pipeline, security gaps. Kontak founder kalo lu butuh reference deep current behavior selama rebuild.

0.7 Working methodology

• Ralph loop: AI Claude iterative coding loop. Doc handover ini = Ralph-loop feedable. Partner feed spec → AI build → review → iterate until done.
• Cagan-style PM: founder owns product/scope/business decisions, partner owns engineering/implementation/quality. Authority boundary explicit di Section 3.
• Cadence:
  • Daily async sync via WhatsApp / Slack
  • Weekly Friday demo + JPD (Jira Product Discovery) opportunity grooming
  • Bi-weekly retro
  • Monthly stakeholder update
• Mid-sprint health gate: 2026-06-16 mandatory check-in (scope cut option kalo behind plan)
• 5-week intensive sprint — founder commit full-time eng + partner part-time + AI augment. Combined ~100-130 productive hours/week. Burnout signal monitored, mandatory pause kalo fire

0.8 Indonesia-specific context

Legal entity status (penting buat finance + compliance):

• Belum berbadan hukum (PT), belum PKP (Pengusaha Kena Pajak)
• PPN tidak required — skip formal Faktur Pajak compliance iter 1
• Invoice format simpler — kuitansi biasa OK
• PPh withholding tetap relevan — PPh 21 (orang pribadi pekerjaan) atau PPh 23 (jasa) buat honor tutor. Iter 1 = placeholder field di system, deduction handle off-system manual
• Berbadan hukum + PKP = future TODO (kalo revenue >4.8B IDR/year atau founder mau formalize)

Legal context cancellation policy:

• KUHPerdata Pasal 1244-1245 (force majeure) — tutor force majeure exempted dari penalty. Workflow L1 review + L2 banding 14d window.
• UU 8/1999 (perlindungan konsumen) — siswa restitution rights kalo sesi gagal. Postpaid model + sesi cancelled = no charge handles this.
• UU ITE Pasal 27A revision 2024 — defamation via elektronik. Reliability score tutor BOLEH publish ke tutor sendiri (self-view), TIDAK publish ke siswa (defamation risk).
• PDP UU 27/2022 (Perlindungan Data Pribadi) — data privacy basic compliance iter 1 (operator explain via WhatsApp + parent verbal consent), formal DSAR endpoint defer iter 2 saat customer-facing.

Tutor relationship: independent contractor (perjanjian kerja sama, NOT UU Ketenagakerjaan employment). Contract clause WAJIB explicit untuk deduction enforce. Founder schedule legal counsel review (~1-2h consultation, budget Rp 1-3M, target Jun week 2) sebelum tutor re-sign.

Cultural context: tutor relationship lebih personal dari transactional di Indonesia formal tutoring. Strict policy bisa lose tutor faster. Goodwill belasungkawa budget (off-system, finance authority) untuk severe FM cases (keluarga inti meninggal, kecelakaan parah).

0.9 Founder commitment context

Founder originally pure PM role (75% product, 25% product-eng). Untuk meet hard deadline 2026-06-30, founder commit full-time eng + PM (~40h/week dev + 5-10h/week PM decisions) selama sprint. Combined dengan partner part-time (~20h/week) + AI augment = ~100-130 productive hours/week capacity. 5-week intensive sprint sustainable, beyond risky.

0.10 Pre-launch tutor pilot

Sebelum full v2 rollout (post 2026-06-30 ship), founder pilot Option (b) cancel policy ke 5 candidate tutors. Re-onboarding conversation + Option (b) policy explanation + observe reaction. Kill criterion: ≥2 refuse re-sign citing cancel policy → revisit Option (b) → (a). Pilot target: Jun week 3-4. Founder owns.

0.11 What's already done vs pending

0.12 How to navigate this doc

1. Read Section 0 (this) — context
2. Skim diagrams (5-10): journey × 3 + state machine + pricing model + cancel flow
3. Domain glossary (Section 4) — lock terms
4. Epic List (Section 11) — table + full story detail
5. Data Model (Section 12) — schemas (Drizzle illustration, partner pick ORM)
6. Workflows narrative (11.5) — text complement diagrams
7. Roadmap + Kill Criteria (Section 13) — sprint plan
8. UX critical affordances (Section 14) — must-haves UI
9. Open questions (Section 17) — resolve di writing-plans phase

Companion docs di same Downloads folder:

• admin-mvp-1-design-plan.md — clean markdown same content, Ralph-loop feedable ke Claude Code lu
• 2026-05-25-xprivate-tutor-cancel-policy-v1.md — cancel policy decision log w/ council voices preserved (READ kalo butuh understand WHY Option b)

On-demand reference (kontak founder kalo butuh):

• Business flow archaeology current platform (~51KB code-level)
• Full brainstorm + reviewer history (spec v1.3 di vault)
• Other decision logs (scope direction, MVP scope expansion, etc.)

1. Overview

XPrivate adalah Indonesian private tutoring (les-privat) marketplace. Existing platform (Spring Boot 3.1.10 + Angular 20 + Next.js + PostgreSQL) di-deprecate. v2 = full greenfield rebuild.

Iter 1 fokus: admin/ops backoffice ONLY. Customer-facing (siswa/tutor self-service signup, payment gateway, auto-notif) defer ke iter berikutnya.

2. Goals + Non-goals

Goals (iter 1)

• Clean state machine + audit-trailed schedule lifecycle
• Configurable pricing matrix (5D versioned per tahun ajaran) + cancellation policy editor
• Operator-friendly daily ops (approval queue, bulk mark-paid, calendar view, drill-down reports)
• HR discipline + termination flow
• Finance period close + reconciliation
• Ship-ready by 2026-06-30

Non-goals (defer iter 2+)

• Customer-facing siswa/tutor self-service signup
• Payment gateway (Midtrans / Xendit) — manual proof upload tetap iter 1
• Auto-trigger notifications (booking confirm, reminder, receipt)
• Semi-privat sesi (1:N), bundling programs, diskon programs
• Online video sessions (Zoom / Meet)
• Mobile push (FCM)
• Tutor reserve pool + premium pay

Known-risk skips (explicit, with mitigation)

3. Tech Stack

Locked — founder authority (product/UX scope)

Locked — partner authority (engineering implementation, locked 2026-05-26)

Pending partner Sprint 0 (still partner authority)

• Definition of Done specifics (partner define per team standards)
• RTO/RPO targets + backup detail (partner define per ops capacity)
• ESLint config detail (override @typescript-eslint/naming-convention for snake_case data props)
• Session expiry config (recommend 1-week + 30-day remember-me, partner final pick)
• Better Auth invite expiry (recommend 7 days, partner config)

4. Domain Glossary (LOCKED)

5. Admin Journey

6. Tutor Journey

7. Siswa / Parent Journey (admin-led iter 1)

8. Schedule State Machine (M3)

9. Pricing Matrix Model (M2)

Snapshot semantic

Pricing matrix di-snapshot ke schedule.pricing_matrix_id_student + schedule.pricing_matrix_id_tutor saat sesi APPROVED. Schedule immune dari pricing change kemudian. Tahun ajaran transition = bulk-clone + bump, atomic operation (1 click).

10. Cancellation Flow

Denda graduated (CONFIG, runtime-editable)

Siswa cancel rules

11. Epic List (8 epics)

Epic Stories — Full Detail

M1 — User Management (Admin)

• Operator login (email/password + Google OAuth — primary, Workspace domain restrict @xprivate.education)
• Forgot password (email reset token, 1 jam expire, single-use)
• Session timeout + remember-me
• Admin CRUD admin users (create, edit, deactivate)
• Admin assign role (minimal: ADMIN, OPS, FINANCE)
• Admin assign granular privilege per role
• Operator profile view (own info, role, last login)
• Manual trigger welcome email (link ke A2)
• Admin onboarding checklist: enforce Google account 2FA on (policy + training)

M2 — Master Data Management

1. Tutor CRUD — profile (nama, golongan, kontak, alamat, lat/long, bio, foto, kontrak PDF upload + signed flag), subject list, slot mgmt
2. Siswa + Parent CRUD — profile (nama, tingkat, segmentasi, parent fields, alamat, lat/long, foto), preferred tutor (TeacherMatch)
3. Subject + SubjectLevel — parent+child schema, has_levels flag
4. Tingkat CRUD — stable individual rows
5. Segmentasi CRUD — operator-managed
6. Kategori CRUD — operator-managed
7. Pricing Matrix (Student) — 5D versioned per Tahun Ajaran, mid-flight override OK, sparse allowed
8. Pricing Matrix (Tutor) — same + Golongan dim
9. Cancellation Policy Editor — bracket threshold + denda % runtime configurable
10. App Config — transport bracket, session default duration, strike decay, FM appeal window, dll
11. Pricing audit log — every matrix change (who, when, from-to, reason)
12. Bulk operations — copy row, copy column, %-bump, atomic clone+bump Tahun Ajaran
13. Coverage gap detector — warn "Subject X has 60% combos populated"
14. Soft-delete + cascade rules — Subject/Tingkat delete = ARCHIVED, FK preserved
15. Data validation rules — phone, email, lat/long, required fields
16. Duplicate detection — siswa/tutor by phone/email → soft-warn
17. Pricing matrix sanity check — negative amount prevent, abnormally high flag

M3 — Schedule Management

• Operator create sesi (admin direct, 1:1 mode)
• Operator approve/reject sesi (single or bulk w/ state validation)
• Operator edit sesi before APPROVED
• Sesi reschedule workflow — RESCHEDULED state, new linked sesi, slot release+lock, audit
• Sesi materi log entry — topik utama, sub-topik, halaman, PR/tugas, target next sesi, foto report
• Calendar view — siswa weekly/monthly + tutor weekly/monthly + global ops
• Sesi conflict detection — validate at approve, DB unique constraint backup
• No-show handling — NO_SHOW_STUDENT (charge full), NO_SHOW_TUTOR (escalate cancel flow)
• Bulk reschedule — operator pick tutor + date range + new tutor/slot
• Operator cancel sesi (terminal w/ reason + denda config calc)
• TimeSlot DB uniqueness constraint
• Tutor mark attendance + materi + foto report (R2 storage)
• Admin validate completion (2-step COMPLETED gate)
• Approval queue UI w/ SLA flag (REQUESTED >24h warn)
• Cancellation calc engine — system auto-calc per config bracket, operator override w/ alasan + audit
• Force majeure workflow — L1 operator review + L2 banding 14d window
• Substitute matching UI (admin-side) — list tutors sort by distance, manual dispatch via WhatsApp
• Cancellation policy snapshot at APPROVED — config_id locked

M4 — Reporting

• Generate monthly student progress per siswa
• Generate monthly tagihan siswa (snapshot-based)
• Generate monthly honorarium tutor (golongan-based, snapshot)
• Export Excel per report
• Bulk mark Settlement.PAID
• Bulk mark SettlementTeacher.PAID
• Outstanding aging — buckets 0-30/31-60/61-90/90+ days, drilldown
• Manual adjust per settlement (nominal + alasan + audit)
• Privacy guard: siswa scoped to caller.studentId, tutor scoped to caller.teacherId, admin all
• Audit-trail mark-paid actions
• Reconciliation export template (Excel)
• Sesi materi visibility — admin dashboard view: materi per siswa timeline, search/filter, export
• Manual reminder broadcast trigger — WhatsApp template (late payment / low completion)

A1 — Audit Trail (cross-cutting)

• Audit middleware logs: actor, action, entity_type, entity_id, before_state, after_state, timestamp, ip
• Schedule, Settlement, Master-data, FM workflow events
• Minimal viewing UI: list view by date range + actor filter
• Audit immutable — DB constraint: insert-only
• Audit retention 7 years — storage planning + archive policy
• Basic search by entity_id — dispute case pull tutor X / siswa Y history

A2 — Notification Trigger (narrowed)

• "Send welcome email" checkbox di M1 admin user create form
• Same di M2 tutor create form, siswa create form
• Wiring ke existing MailTemplate infra (template welcome baru)
• Send log entry (who sent, to, template, timestamp)

M6 — HR Discipline + Termination

• Strike count visible per tutor (active dalam 90d window)
• Strike detail audit (when, why, by whom, alasan)
• Manual escalation UI (HR/admin decide suspend / final-warning / terminate)
• Suspend tutor temporarily (block from booking, reason + duration, audit)
• Terminate tutor kerjasama (final + audit)
• Termination checklist (final settlement payout, document return, access revoke, archive)
• Tutor archive (preserved data + read-only access)
• Tutor reactivation flow (senior approval + audit)
• Final settlement at termination event — auto-trigger settlement payout calc untuk remaining unpaid sesi. Legal obligation.
• Access revoke immediate — terminate = revoke OAuth tokens + login disabled (implementation pattern: partner pick)
• Pending FM claim blocker — block termination if FM claim status PENDING_L1 or PENDING_L2

M7 — Finance Workflow

Refund / credit note flow:

• Operator initiate refund (sesi cancelled post-bill, dispute, special case)
• Credit note generation (reduce siswa bill, audit, reason mandatory)
• Refund disbursement tracking (off-system, status notes)
• Settlement reversal (mark UNPAID → reversed, audit)

Financial period close:

• Monthly close checklist UI (step-through)
• Period lock flag (no backdated bookings, no late-mark-paid retroactive)
• Period close blocker: if any sesi IN_PROGRESS at close time, block until finalized
• Lock audit + Re-open option (senior approval + audit)

Outstanding aging integration: reuse M4 dashboard + bad debt write-off flow (senior approval).

Reconciliation: export template (Excel finance-familiar) + adjustment audit trail.

PPh withholding placeholder: pph_withheld_amount field per honor batch, operator input manual.

Honor payment slip: tutor receive slip w/ breakdown (base + transport + extra-time + adjustments + PPh). Export PDF per tutor per month.

Backup + DR strategy: daily backup procedure + restore drill cadence + retention policy. RTO/RPO targets + implementation: partner authority.

11.5 Workflows Narrative

Booking happy path

1. Admin create sesi → REQUESTED
2. Admin review approval queue → APPROVED (or REJECTED)
3. Tutor mark Start → IN_PROGRESS (validation: only from APPROVED)
4. Tutor mark attendance + materi + foto report
5. Admin validate completion → COMPLETED (2-step)
6. Settlement auto-created (UNPAID, snapshot pricing dari APPROVED config)
7. Monthly billing cycle (M4):
   - Tagihan siswa generated
   - Siswa bayar offline, upload bukti
   - Operator mark Settlement PAID (bulk capable)
8. Monthly honorarium cycle (M4):
   - Honorarium tutor generated
   - Finance batch transfer offline
   - Operator mark SettlementTeacher PAID (bulk capable)

Force Majeure workflow

Tutor claim FM (via WhatsApp ke admin iter 1)
  ↓
Admin entry claim di backoffice + evidence
  ↓
L1 Operator review → APPROVE (no penalty) atau REJECT (normal escalate)
  ↓ (if REJECT)
Tutor banding dalam 14d window
  ↓
L2 Admin review → UPHOLD (final) atau OVERTURN (refund penalty)
  ↓
Audit log all events
Optional comp_notes field — finance off-system bayar belasungkawa

Substitute matching (admin-side, iter 1)

Tutor X cancel via WhatsApp → admin info
  ↓
Admin open schedule detail X → klik [Cari Sub]
  ↓
List candidates sorted by distance ascending:
  Filter: subject match + slot bebas + status ACTIVE
  Display: nama, distance km, golongan, last_active, [Pilih]
  ↓
Admin pilih candidate Z → dispatch via WhatsApp manual
  ↓
Z accept via WhatsApp → admin update sesi assignment ke Z
  ↓
Sesi jalan dengan Z

12. Data Model (key schemas)

Subject + SubjectLevel (parent + nullable child)

// Example syntax (Drizzle illustration — partner pick ORM)
const subject = pgTable('subject', {
  id: serial('id').primaryKey(),
  nama: text('nama').notNull(),
  kategoriId: integer('kategori_id').references(() => kategori.id),
  hasLevels: boolean('has_levels').default(false),
  deskripsi: text('deskripsi'),
  sortOrder: integer('sort_order').default(0),
  status: text('status').default('ACTIVE'),
});

const subjectLevel = pgTable('subject_level', {
  id: serial('id').primaryKey(),
  subjectId: integer('subject_id').references(() => subject.id).notNull(),
  nama: text('nama').notNull(),
  kode: text('kode').notNull(),
  sortOrder: integer('sort_order').default(0),
  status: text('status').default('ACTIVE'),
});

Pricing Matrix

const pricingMatrix = pgTable('pricing_matrix', {
  id: serial('id').primaryKey(),
  subjectId: integer('subject_id').references(() => subject.id).notNull(),
  subjectLevelId: integer('subject_level_id').references(() => subjectLevel.id),
  tingkatId: integer('tingkat_id').references(() => tingkat.id).notNull(),
  segmentasiId: integer('segmentasi_id').references(() => segmentasi.id).notNull(),
  audience: text('audience').notNull(), // STUDENT | TUTOR
  golonganId: integer('golongan_id').references(() => golongan.id),
  amount: numeric('amount', { precision: 20, scale: 4 }).notNull(),
  effectiveFrom: date('effective_from').notNull(),
  effectiveUntil: date('effective_until'),
  status: text('status').default('ACTIVE'),
});

Schedule (key fields)

const schedule = pgTable('schedule', {
  id: serial('id').primaryKey(),
  status: text('status').notNull(), // 7 states
  subjectId: integer('subject_id').references(() => subject.id).notNull(),
  subjectLevelId: integer('subject_level_id').references(() => subjectLevel.id),
  tutorId: integer('tutor_id').references(() => tutor.id).notNull(),
  siswaId: integer('siswa_id').references(() => siswa.id).notNull(),
  sesiDateTime: timestamp('sesi_date_time').notNull(),
  sesiMode: text('sesi_mode').notNull(),

  // Pricing snapshot (immune from later changes)
  pricingMatrixIdStudent: integer('pricing_matrix_id_student').references(() => pricingMatrix.id),
  pricingMatrixIdTutor: integer('pricing_matrix_id_tutor').references(() => pricingMatrix.id),
  amountStudent: numeric('amount_student'),
  amountTutor: numeric('amount_tutor'),
  transportFee: numeric('transport_fee'),

  // Cancellation policy snapshot
  cancellationPolicyConfigId: integer('cancellation_policy_config_id'),

  // Lifecycle
  createdAt: timestamp('created_at').defaultNow(),
  approvedAt: timestamp('approved_at'),
  startedAt: timestamp('started_at'),
  completedAt: timestamp('completed_at'),
  cancelledAt: timestamp('cancelled_at'),
  cancelReason: text('cancel_reason'),
  cancelInitiator: text('cancel_initiator'),
  cancelLeadTimeHours: numeric('cancel_lead_time_hours'),
  cancelDendaAmount: numeric('cancel_denda_amount'),
  cancelDendaAmountOverride: numeric('cancel_denda_amount_override'),

  // Linked
  rescheduledToScheduleId: integer('rescheduled_to_schedule_id'),
});

Cancellation Policy Config + Bracket

const cancellationPolicyConfig = pgTable('cancellation_policy_config', {
  id: serial('id').primaryKey(),
  policyType: text('policy_type').notNull(), // TUTOR_CANCEL | SISWA_CANCEL
  effectiveFrom: date('effective_from').notNull(),
  effectiveUntil: date('effective_until'), // NULLABLE = current
  status: text('status').default('ACTIVE'),
  notes: text('notes'),
});

const cancellationBracket = pgTable('cancellation_bracket', {
  id: serial('id').primaryKey(),
  configId: integer('config_id').references(() => cancellationPolicyConfig.id).notNull(),
  sortOrder: integer('sort_order').notNull(),
  thresholdHours: numeric('threshold_hours', { precision: 5, scale: 2 }).notNull(),
  chargePctSiswa: numeric('charge_pct_siswa', { precision: 5, scale: 2 }), // SISWA_CANCEL
  honorPctTutor: numeric('honor_pct_tutor', { precision: 5, scale: 2 }), // SISWA_CANCEL
  substitutionDendaPct: numeric('substitution_denda_pct', { precision: 5, scale: 2 }), // TUTOR_CANCEL
  basePenaltyEnabled: boolean('base_penalty_enabled').default(true),
  strikeAdded: integer('strike_added').default(0),
  notes: text('notes'),
});

Force Majeure (claim + review + appeal)

const forceMajeureClaim = pgTable('force_majeure_claim', {
  id: serial('id').primaryKey(),
  scheduleId: integer('schedule_id').references(() => schedule.id).notNull(),
  tutorId: integer('tutor_id').references(() => tutor.id).notNull(),
  category: text('category').notNull(), // SAKIT | DUKA | DARURAT | BENCANA | LAINNYA
  reasonText: text('reason_text'),
  status: text('status').notNull(), // PENDING_L1 | APPROVED_L1 | REJECTED_L1 | PENDING_L2 | UPHELD | OVERTURNED
  compNotes: text('comp_notes'), // optional, operator catat info comp manual
  createdAt: timestamp('created_at').defaultNow(),
});

const forceMajeureReview = pgTable('force_majeure_review', {
  id: serial('id').primaryKey(),
  claimId: integer('claim_id').references(() => forceMajeureClaim.id).notNull(),
  reviewerUserId: integer('reviewer_user_id').notNull(),
  reviewLevel: text('review_level').notNull(), // L1 | L2
  decision: text('decision').notNull(), // APPROVE | REJECT | UPHOLD | OVERTURN
  reasonText: text('reason_text'),
  createdAt: timestamp('created_at').defaultNow(),
});

const forceMajeureAppeal = pgTable('force_majeure_appeal', {
  id: serial('id').primaryKey(),
  claimId: integer('claim_id').references(() => forceMajeureClaim.id).notNull(),
  tutorId: integer('tutor_id').references(() => tutor.id).notNull(),
  additionalReason: text('additional_reason'),
  submittedAt: timestamp('submitted_at').defaultNow(),
  deadline: timestamp('deadline').notNull(), // claim.review.created_at + 14d
});

12.5 App Config Keys (runtime-editable)

All editable via admin UI, audit-tracked. Defaults locked, runtime override allowed.

13. Roadmap + Kill Criteria

Kill Criteria (Duke states + dates)

1. 2026-06-01: Sprint 1 belum done → retro + scope cut (drop Google OAuth, email/pwd only) OR push deadline
2. 2026-06-15: Sprint 2 belum done → defer Cancellation Policy Editor + Tutor contract upload ke iter 1.5
3. 2026-06-25: Sprint 3 belum done → defer FM workflow + substitute matching UI ke iter 1.5
4. 2026-06-30: Sprint 4 belum done → defer M6 + M7 ke iter 1.5 (post-Jul)
5. 2026-07-15: Full scope belum done + burnout signal → mandatory pause, re-plan, escalate
6. Pre-launch tutor pilot 5 tutors: ≥2 refuse re-sign citing cancel policy → revisit Option (b) → (a)

14. Critical UX Affordances (don't skip)

1. Atomic "Clone Tahun Ajaran" button — handles BOTH effective_until update on old rows + insert bumped new rows in single op (NOT 2 manual steps)
2. Hierarchical drill-down navigation — Subject → Level → matrix per audience. NOT flat 6-column entry.
3. Coverage gap detector — warn "Subject X has 60% combos populated (12/20)" with link to fix
4. has_levels auto-show/hide — operator only sees Level picker when relevant
5. CSV import — bulk entry path mandatory
6. Per-row validation — surface errors immediately at input

15. Pre-Sprint-1 Checklist

16. Repo Structure + DoD + Sprint 1 Kickoff

Repo structure — Partner authority

Founder gak prescribe folder layout. Partner pick monorepo tool + structure per familiar patterns + AI-augmented workflow.

Definition of Done — Partner authority

Partner define per team standards + ops capacity. Founder hanya require:

• Acceptance criteria per story (locked di Jira tickets — to be generated)
• Manual operator walkthrough validation (founder review)
• Audit log entries for state-changing actions (per A1 epic scope)

Sprint 1 Kickoff

Founder commits (this doc + companion markdown + IA handover — TBD):

• Pricing matrix RAT result + design plan
• Domain glossary locked
• 8-epic scope + acceptance criteria per story
• Kill criteria + dates

Partner commits (Sprint 0, before 2026-05-26 kickoff):

• Repo bootstrap (tool + structure pick)
• Deployment pipeline setup
• Database + observability provisioning
• Local dev setup doc
• Stack micro-decision lock (ORM, routing, validation, monorepo)

Sprint 1 kickoff: 2026-05-26 — pair sync on Sprint 1 stories M1 + A1.

17. Open Questions (resolve di writing-plans phase)

• Operator role granularity — final list (ADMIN/OPS/FINANCE only, or sub-tier?)
• Tutor contract template — Word/PDF design (legal counsel saat BH; lighter version untuk pre-BH iter 1)
• Siswa ToS document drafting (lighter pre-BH, formal saat customer-facing iter)
• FM tier classification — define detailed guideline (operator decision matrix per category)
• Stack pick micro-detail (ORM, routing, validation, monorepo tool) — partner authority decide saat Sprint 0
• Hosting + infra detail (DigitalOcean Spaces continued, atau pindah R2?) — partner authority
• Migration strategy from v0 (legacy data) — deferred per scope direction decision; bulk-import reference only, transactional history archive read-only
• Backup + DR setup detail (cron schedule, R2 backup target, restore drill procedure) — Sprint 4 task, partner authority