Skip to content

Engineering Standards, Testing & ADRs (HUB-ENG-001)

Field Value
Document ID HUB-ENG-001
Pillar Software Engineering
Standard Alignment ISO/IEC/IEEE 12207 & 29119
Status Active / Synchronized with Codebase
Last Updated 2026-11-21
Source of Truth package.json, CLAUDE.md, CONTRIBUTING.md, vite.config.js, .github/workflows/portal.yml, tests/*.test.mjs, tests/sql/*.sql, tests/pendampingan-synthetic.sql, ops/p3mdi-sso/*_test.ts

soedirman-hub/
├── src/
│ ├── main.js / App.vue / style.css # Vue bootstrap, error boundary, Tailwind v4 tokens & shell CSS
│ ├── router/index.js # 33 routes, 30 lazy view imports, auth/setup/RBAC/demo guards
│ ├── store/portal.js # Reactive store, offline outbox drain, LRU photo cache, sync engine
│ ├── layouts/DashboardLayout.vue # Desktop sidebar, mobile bottom nav + sheet, role switcher
│ ├── components/ # 26 reusable modals, nav bars, SSO panels, charts, pagination
│ ├── composables/ # useDialog, useScrollLock, usePwaInstall
│ ├── lib/ # Supabase PostgREST/RPC adapter, SSO PKCE, offlineQueue, services
│ ├── utils/ # constants, helpers (Permissions/WIB), attendance, xlsxExport, etc.
│ ├── data/ # Static reference catalogs + synthetic demoData.js (901-912)
│ └── views/ # 31 SFC views (30 routed + InfoDigitalView embedded in PamView)
├── supabase/
│ ├── schema_complete.sql # Consolidated baseline schema
│ ├── migrations/ # 39 sequential SQL migrations (20261024 .. 20261130080000)
│ └── private/ # Git-ignored sensitive roster data & generated seed scripts
├── ops/
│ ├── p3mdi-sso/ # Deno TypeScript SSO & Core Directory broker + 4 Deno test files
│ ├── authentik/p3mdi_hub/ # Django Guardian RBAC scoping app mounted into Authentik
│ ├── deploy-ssh.sh # Forced-command SSH wrapper validating SHA & run number
│ └── release-on-vm.sh # Atomic flock Docker build, smoke test & automatic rollback
├── google-apps-script/Code.gs # Session-verified Google Drive image upload webhook
├── scripts/generate-master-sql.mjs # Local bcrypt PIN & seed SQL generator
├── public/ # PWA manifest, Service Worker template (sw.js), WebP/PNG media
├── tests/ # 41 Node test files + 1 synthetic SQL script + 4 SQL tests in sql/
├── graphify-out/ # Knowledge graph output queried per CLAUDE.md / CONTRIBUTING.md
└── docs/ # Architecture, Design, Data, Security, API, Eng & Ops docs

2. Engineering Conventions & Knowledge Graph Workflow

Section titled “2. Engineering Conventions & Knowledge Graph Workflow”
  1. Vue 3 Composition API & Styling: All views and components use <script setup>, Vue Router 4.5 lazy imports, Lucide icons (lucide-vue-next), and Tailwind CSS v4 (@tailwindcss/postcss) supplemented by utility/component layers in src/style.css.
  2. Code Navigation (CLAUDE.md & CONTRIBUTING.md): Before touching unfamiliar subsystems, contributors query the repository structural graph (graphify-out/graph.json) using graphify query, graphify path, graphify explain, or graphify section. The graphify-out/ directory is maintained separately and must not be manually altered during unrelated edits.
  3. Zero Third-Party Bloat for Exports & QR: Client exports and QR generation rely on internal zero-dependency modules (src/utils/xlsxExport.js uncompressed storedZip OpenXML builder; pure JS QR matrix encoder tested in tests/perizinan.test.mjs) rather than heavy Office/PDF runtime bundles.
  4. Strict Git Hygiene: Private credentials (supabase/private/*, .env) stay out of Git. Any change altering PII storage, RLS policies, or edge headers must preserve existing static invariant tests or update them with security review.
  5. Definition of Done (CONTRIBUTING.md & CI):
    • npm test (240 tests / 62 suites) passes cleanly with zero failures or skipped assertions.
    • npm run build succeeds with clean chunk generation and SHA-256 SW stamping.
    • Deno unit tests and Postgres SQL fixture tests pass when modifying ops/p3mdi-sso/ or supabase/migrations/.
    • Local npm audit --audit-level=high and Gitleaks history scans remain clean.

Soedirman Hub employs a three-runtime automated verification pyramid totaling 41 Node test files (240 tests across 62 suites), 4 Deno unit test files (19 tests), and 5 SQL verification scripts (4 in tests/sql/ + 1 synthetic harness in tests/):

3.1 Node Built-In Test Runner (npm test -> node --test tests/*.test.mjs — 41 Files, 240 Tests)

Section titled “3.1 Node Built-In Test Runner (npm test -> node --test tests/*.test.mjs — 41 Files, 240 Tests)”
Domain Focus Test Files (tests/*.test.mjs) Verified Scope & Key Assertions
Security, Auth & Privacy security.test.mjs (12), scoped-duties-and-retention.test.mjs (5), info-digital.test.mjs (3), pendampingan.test.mjs (2) RBAC (Permissions) fail-closed defaults, anti-NOSIS-spoofing, PIN complexity, GAS HTTPS host allowlist, Vercel Permissions-Policy, absence of legacy bypasses/secrets, portal_serdik_directory security_invoker = false, IB 7-day purge SQL contracts, EXIF/quota/no-anon rules, Pendampingan privacy.
SSO & Identity Lifecycle sso-callback.test.mjs (1), sso-identity-management.test.mjs (7), sso-security-callback.test.mjs (1) PKCE link vs login vs re-auth mode isolation, 20261125 SQL schema/audit invariants, broker endpoint checks, docs/p3mdi-sso.md documentation invariant assertions.
RBAC & Demo Sandbox admin-role-switch.test.mjs (5), demo-mode.test.mjs (6) AdminRoleSwitcher role boundary, sessionStorage isolation, logout reset, fallback routing; synthetic personas (901–912), network/storage isolation under ?demo=true.
Admin Console Separation & UI admin-console-separation.test.mjs (5), admin-console-shell.test.mjs (3), admin-console-table.test.mjs (3), admin-console-tabs-refine.test.mjs (4) Separation from SettingsView, komandan_batch view-only vs super_admin write gating, filter chips, pagination, audit CSV export.
Attendance, Evidence & GPS attendance-evidence.test.mjs (6), attendance-sync.test.mjs (1), live-photo-location.test.mjs (4), camera-modals.test.mjs (2), kerapian-kamar-review.test.mjs (9) GPS accuracy (<= 100 m) & staleness (<= 15 s), teleport/static anti-spoof checks, Nominatim timeout handling, WIB daily-condition windows, MediaStream/canvas cleanup, 3-slot room tidiness review & mixed-element filters.
Offline Queue & Photo Cache offline-queue.test.mjs (4), store-photo-cache.test.mjs (3), resilience.test.mjs (6) Scoped outbox FIFO ordering, navigator.locks mutex, retry limits (8 retries), corrupt JSON recovery, IndexedDB granular keys & 2-session LRU eviction, state stripping.
Corps & Pengasuh Governance korps-batch-visuals.test.mjs (11), korps-finishing-touches.test.mjs (9), korps-pengasuh-governance.test.mjs (5), korps-prefill-autosave.test.mjs (10), korps-review-flow.test.mjs (5) 17-unit draft/submit/review state transitions, 21:30 WIB deadline logic, batch matrix & sparklines, Pengasuh dual workspace & notes.
Perizinan, Poldik & Ops perizinan.test.mjs (18), poldik-operasional.test.mjs (10) 3-tier Izin Keluar approval & rejection, GPS 3-decimal rounding, WhatsApp formatters, ISO QR matrix generator, Lapor Kembali, discipline & Ops task workflows.
Shell, Mobile UX & Perf shell-modal-a11y.test.mjs (7), mobile-ux.test.mjs (9), absensi-mobile-perf.test.mjs (2), boot-assets-perf.test.mjs (6), dashboard-perf-mobile.test.mjs (4), modals-popovers-mobile.test.mjs (6), pam-mobile-ux.test.mjs (5), poldik-mobile-ux.test.mjs (4), pwa-install.test.mjs (1), pwa-perf.test.mjs (6), laporan-harian-print.test.mjs (16), prayer-schedule.test.mjs (6), xlsx-export.test.mjs (4) Z-index hierarchy (--z-base..--z-toast), 44 px coarse touch targets, 16 px iOS auto-zoom guard, ref-counted useScrollLock, tablet nav dead-zone elimination, deferred loadDirectory(), < 8 MB WebP asset caps, print readiness waits, OpenXML spreadsheet escaping & ZIP validity.

3.2 Deno Broker Unit Tests (ops/p3mdi-sso/*_test.ts — 4 Files, 19 Tests)

Section titled “3.2 Deno Broker Unit Tests (ops/p3mdi-sso/*_test.ts — 4 Files, 19 Tests)”
  • setup_test.ts (6 tests): First-login input bounds, unauthenticated/completed rejections, stage ordering, secret exclusion from audit.
  • security_test.ts (5 tests): Stale confirmation rejection, session revocation on password change, non-admin cross-account protection, unlinked creation checks.
  • accounts_test.ts (3 tests): Live session admin gate, group-scoped listing, activation boundaries.
  • profile_test.ts (5 tests): validateProfilePatch, validateCreatePayload, maskSubject, PKCE 43-char isValidCallback rules. (CI runs setup_test.ts security_test.ts accounts_test.ts; run all 4 locally inside ops/p3mdi-sso with deno test --no-lock --allow-env --allow-net *_test.ts.)

3.3 Disposable PostgreSQL Verification Scripts (tests/sql/*.sql & tests/pendampingan-synthetic.sql)

Section titled “3.3 Disposable PostgreSQL Verification Scripts (tests/sql/*.sql & tests/pendampingan-synthetic.sql)”
  • tests/sql/first-login-setup.test.sql: Validates guided onboarding PIN/mark/finish constraints.
  • tests/sql/sso-management.test.sql: Runs in CI against postgres:16-alpine; sources first-login-setup.test.sql and 20261127_sso_account_management.sql to verify anon/authenticated privilege revocation and fresh-auth confirmation enforcement.
  • tests/sql/info-digital.test.sql: Verifies Paminfo scope isolation, 5/day quota enforcement, JPEG APPn/COM EXIF byte stripping, and restrictive pam_reports policy.
  • tests/sql/kerapian-kamar-review.test.sql: Verifies room tidiness RLS, mixed-element room scope intersection, IB exemptions, room commander appointments, and evidence RPC guards.
  • tests/pendampingan-synthetic.sql: Synthetic end-to-end SQL assertions (run inside BEGIN ... ROLLBACK) checking case uniqueness, access scopes, and deletion audit.
Terminal window
# 1. All 240 Node tests across 41 .test.mjs files (also alias: npm run test:security)
npm test
# 2. Production Vite bundle + SW build-hash verification
npm run build
# 3. Deno SSO broker unit suite (inside ops/p3mdi-sso or via Docker image)
deno test --no-lock --allow-env --allow-net setup_test.ts security_test.ts accounts_test.ts profile_test.ts
# 4. PostgreSQL migration invariant tests (inside disposable Postgres 16 container)
psql -h 127.0.0.1 -U postgres -f /tests/sql/sso-management.test.sql

3.5 Critical Static Invariants (Break-Glass Warnings)

Section titled “3.5 Critical Static Invariants (Break-Glass Warnings)”

Modifying any of the following will immediately fail CI (tests/security.test.mjs, tests/shell-modal-a11y.test.mjs, tests/sso-identity-management.test.mjs):

  1. Changing public.portal_serdik_directory to security_invoker = true (breaks REST directory sync with 42501).
  2. Removing docs/p3mdi-sso.md or breaking assertions in tests/sso-identity-management.test.mjs.
  3. Adding z-index to .main-wrapper or mobile < 1024px .top { backdrop-filter }, or switching .portal-app to overflow-x: hidden instead of overflow-x: clip.
  4. Removing camera/geolocation permissions from vercel.json or reintroducing bulk serdik?select= reads in src/lib/supabase.js.

ADR-001: Custom 32-Byte x-portal-token Session Header Instead of Supabase Auth JWTs

Section titled “ADR-001: Custom 32-Byte x-portal-token Session Header Instead of Supabase Auth JWTs”
  • Context: Cohort rosters already used 3-digit nosis / nrp identifiers paired with issued 6-digit PINs rather than verified emails, and needed seamless switching into Authentik OIDC later without duplicating user accounts.
  • Decision: Store pgcrypto bcrypt hashes on serdik/pengasuh (20261024) and manage 12-hour opaque 32-byte tokens via portal_private.sessions passed on x-portal-token. RLS policies evaluate portal_private.current_session().
  • Consequences: Enables deterministic PIN/OIDC convergence, instant server-side session revocation on PIN change or admin reset, and strict onboarding boundaries (session_identity() vs current_session()). Trade-off: custom RPC maintenance instead of native auth.uid() helpers.

ADR-002: security_invoker = false + security_barrier = true on public.portal_serdik_directory

Section titled “ADR-002: security_invoker = false + security_barrier = true on public.portal_serdik_directory”
  • Context: Direct SELECT on PII columns (telepon, email, alamat, tanggal_lahir) on public.serdik was revoked from anon/authenticated (20261116). Enabling Postgres 15 security_invoker = true caused PostgREST queries to evaluate column grants as anon, triggering a production-wide 42501 outage.
  • Decision: Explicitly pin WITH (security_barrier = true, security_invoker = false) and match view ownership to public.serdik (20261121), performing per-session field masking via CASE expressions against portal_private.current_session().
  • Consequences: Restores directory sync with zero leakage of private columns to unprivileged roles, accepting Postgres Security Advisor’s security_definer_view warning as an intentional trade-off.

ADR-003: Isolated Deno SSO & Core Sidecar (ops/p3mdi-sso/)

Section titled “ADR-003: Isolated Deno SSO & Core Sidecar (ops/p3mdi-sso/)”
  • Context: Authentik administrative tokens (P3MDI_ACCOUNT_API_TOKEN), OIDC client secrets, Core Bridge tokens, and SUPABASE_SECRET_KEY cannot live in the browser SPA or Edge static host.
  • Decision: Deploy a minimal single-purpose Deno container on port 8000 behind Traefik routing /api/sso* paths on app.p3mdi.id (compose.yaml). Every privileged endpoint validates the caller’s live Hub x-portal-token against portal_me and requires 5-minute OIDC re-authentication (sso_confirmations) for sensitive mutations.
  • Consequences: Strong blast-radius containment with trivial Docker build and built-in Deno TypeScript type checking/testing in CI.

ADR-004: Scoped localStorage Outbox + Granular IndexedDB Attendance Photo Cache

Section titled “ADR-004: Scoped localStorage Outbox + Granular IndexedDB Attendance Photo Cache”
  • Context: Field attendance and operational updates occur under intermittent connectivity, while base64 selfie photos quickly exceed localStorage’s ~5 MB cap and stall JSON serialization.
  • Decision: Isolate offline writes in src/lib/offlineQueue.js serialized with navigator.locks and bounded retry (8 attempts), while stripping photoUrl/gps/locationName from localStorage into granular IndexedDB entries (soedirman-attendance-photos) capped to 2 hydrated in-memory sessions.
  • Consequences: Survives reloads and multi-tab races reliably while wiping all user artifacts cleanly on logout (purgeBrowserCaches()).

ADR-005: Lazy-Loaded Route Splitting & Conditional Roster Hydration (meta.requiresDirectory)

Section titled “ADR-005: Lazy-Loaded Route Splitting & Conditional Roster Hydration (meta.requiresDirectory)”
  • Context: Loading all 384+ student records on initial dashboard navigation delays interactive paint on mobile devices.
  • Decision: Split every route component dynamically in src/router/index.js (vue-vendor & icons manual chunks in vite.config.js), and defer loadDirectory() until navigating to routes flagged meta.requiresDirectory: true.
  • Consequences: Fast initial app boot; stale chunk hashes during rolling deploys are caught by router.onError with a single-attempt hard reload (sessionStorage['soedirman_chunk_reload']).