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 |
1. Repository Layout & Module Boundaries
Section titled “1. Repository Layout & Module Boundaries”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 docs2. Engineering Conventions & Knowledge Graph Workflow
Section titled “2. Engineering Conventions & Knowledge Graph Workflow”- 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 insrc/style.css. - Code Navigation (
CLAUDE.md&CONTRIBUTING.md): Before touching unfamiliar subsystems, contributors query the repository structural graph (graphify-out/graph.json) usinggraphify query,graphify path,graphify explain, orgraphify section. Thegraphify-out/directory is maintained separately and must not be manually altered during unrelated edits. - Zero Third-Party Bloat for Exports & QR: Client exports and QR generation rely on internal zero-dependency modules (
src/utils/xlsxExport.jsuncompressedstoredZipOpenXML builder; pure JS QR matrix encoder tested intests/perizinan.test.mjs) rather than heavy Office/PDF runtime bundles. - 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. - Definition of Done (
CONTRIBUTING.md& CI):npm test(240tests /62suites) passes cleanly with zero failures or skipped assertions.npm run buildsucceeds with clean chunk generation and SHA-256 SW stamping.- Deno unit tests and Postgres SQL fixture tests pass when modifying
ops/p3mdi-sso/orsupabase/migrations/. - Local
npm audit --audit-level=highand Gitleaks history scans remain clean.
3. Comprehensive Test Suite Inventory
Section titled “3. Comprehensive Test Suite Inventory”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(6tests): First-login input bounds, unauthenticated/completed rejections, stage ordering, secret exclusion from audit.security_test.ts(5tests): Stale confirmation rejection, session revocation on password change, non-admin cross-account protection, unlinked creation checks.accounts_test.ts(3tests): Live session admin gate, group-scoped listing, activation boundaries.profile_test.ts(5tests):validateProfilePatch,validateCreatePayload,maskSubject, PKCE43-charisValidCallbackrules. (CI runssetup_test.ts security_test.ts accounts_test.ts; run all 4 locally insideops/p3mdi-ssowithdeno 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 againstpostgres:16-alpine; sourcesfirst-login-setup.test.sqland20261127_sso_account_management.sqlto verifyanon/authenticatedprivilege 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 restrictivepam_reportspolicy.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 insideBEGIN ... ROLLBACK) checking case uniqueness, access scopes, and deletion audit.
3.4 Execution Commands
Section titled “3.4 Execution Commands”# 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 verificationnpm 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.sql3.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):
- Changing
public.portal_serdik_directorytosecurity_invoker = true(breaks REST directory sync with42501). - Removing
docs/p3mdi-sso.mdor breaking assertions intests/sso-identity-management.test.mjs. - Adding
z-indexto.main-wrapperor mobile< 1024px.top { backdrop-filter }, or switching.portal-apptooverflow-x: hiddeninstead ofoverflow-x: clip. - Removing camera/geolocation permissions from
vercel.jsonor reintroducing bulkserdik?select=reads insrc/lib/supabase.js.
4. Architecture Decision Records (ADRs)
Section titled “4. Architecture Decision Records (ADRs)”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/nrpidentifiers paired with issued 6-digit PINs rather than verified emails, and needed seamless switching into Authentik OIDC later without duplicating user accounts. - Decision: Store
pgcryptobcrypt hashes onserdik/pengasuh(20261024) and manage 12-hour opaque 32-byte tokens viaportal_private.sessionspassed onx-portal-token. RLS policies evaluateportal_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()vscurrent_session()). Trade-off: custom RPC maintenance instead of nativeauth.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
SELECTon PII columns (telepon,email,alamat,tanggal_lahir) onpublic.serdikwas revoked fromanon/authenticated(20261116). Enabling Postgres 15security_invoker = truecaused PostgREST queries to evaluate column grants asanon, triggering a production-wide42501outage. - Decision: Explicitly pin
WITH (security_barrier = true, security_invoker = false)and match view ownership topublic.serdik(20261121), performing per-session field masking viaCASEexpressions againstportal_private.current_session(). - Consequences: Restores directory sync with zero leakage of private columns to unprivileged roles, accepting Postgres Security Advisor’s
security_definer_viewwarning 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, andSUPABASE_SECRET_KEYcannot live in the browser SPA or Edge static host. - Decision: Deploy a minimal single-purpose Deno container on port
8000behind Traefik routing/api/sso*paths onapp.p3mdi.id(compose.yaml). Every privileged endpoint validates the caller’s live Hubx-portal-tokenagainstportal_meand 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.jsserialized withnavigator.locksand bounded retry (8attempts), while strippingphotoUrl/gps/locationNamefromlocalStorageinto 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&iconsmanual chunks invite.config.js), and deferloadDirectory()until navigating to routes flaggedmeta.requiresDirectory: true. - Consequences: Fast initial app boot; stale chunk hashes during rolling deploys are caught by
router.onErrorwith a single-attempt hard reload (sessionStorage['soedirman_chunk_reload']).