0%
balqalam Logo
balqalam
FeaturesCommunityPricingDocumentation
Login
  • Introduction
  • Pitch
  • Hogwarts
  • Live Demo
  • MVP
  • Roadmap
  • Launch Sprint
  • PRD
  • Get Started
  • Localhost
  • Architecture
  • Structure
  • Pattern
  • Page
  • Layout
  • Content
  • Types
  • Config
  • Actions
  • Queries
  • Authorization
  • Validation
  • Form
  • Table
  • Detail
  • Card
  • Util
  • Hooks
  • List Params
  • Views
  • README.md
  • ISSUE.md
  • Technology Stack
  • Database
  • File
  • CDN Assets
  • Entry Points
  • Dashboard
  • Authentication
  • Credentials
  • OAuth
  • Flow Diagrams
  • Multi-Tenancy
  • Offline
  • Onboarding
  • Onboarding Videos
  • Add Values
  • Admission
  • Application
  • Attendance
  • Compliance
  • Profile
  • Exams
  • Exam Wizard
  • Timetable
  • Classrooms
  • Notifications
  • Conference
  • LMS (Lumos)
Finance
  • Finance
  • Fee Management
  • Invoice
  • Wallet
  • Salary
  • Payroll
  • Timesheet
  • Expenses
  • Budget
  • Receipt
  • Accounts
  • Banking
  • Reports
  • Dashboard
  • Permissions
  • Messages
  • Integration Flow
  • Provision
  • AI Document Processing
  • Document Intelligence
  • Internationalization
  • Translation
  • Translation Guide
  • Icons
  • Docs Factory
  • Inspiration
  • Listings
  • Teachers
  • Students
  • Catalog
  • Library
  • Contributing
  • Code of conduct
  • GitHub Workflow
  • Database Seeds
  • Database Safety
  • Test Accounts
  • Playwright
  • Prettier
  • Block Rebound
Sales & GTM
  • Marketing Brief
  • Sales
  • Go-to-market
  • Marketing
  • Admission — Feature Spotlight
  • Pilot Program
  • Leads
  • Proposal
  • Outreach Templates
  • Case Study
  • Competitors
  • Landing-page teardown
  • Competitor FAQ
  • Business model
  • Shared economy
  • Traction
Fundraising & Ecosystem
  • Get Support
  • Investor Deck
  • Data Room
  • Investors
  • Accelerators
  • Incubators
  • Grants
  • Sponsors
  • Partners
  • Competitions & Hackathons
  • Universities & Training Centers

Compliance

PreviousNext

Generic regulator-submission framework — first provider is ADEK eSIS (Abu Dhabi), with daily attendance upload, 2-hour parent-contact SLA, and circuit-breakered shared credentials.

The compliance block lets schools submit data to a government regulator on a scheduled cadence and prove they met regulator-specific SLAs. ADEK eSIS (Abu Dhabi Department of Education and Knowledge) is the first provider; the framework is generic so future authorities (SEC KSA, MoE Qatar, MoE Sudan) plug in by adding one ComplianceProvider enum value and a sibling directory under src/lib/compliance/providers/<authority>/.

Ship tracker: databayt/hogwarts#1 — consolidated attendance + compliance master tracker. See also Aldar Epic 01.

Status

CapabilityStatusNotes
Daily CSV submissionProduction (DRY_RUN)Generic mapper, ADEK 2025/26 absence categories
2-hour parent-contact SLA cronProduction/api/cron/absence-followup, every 30 min, UTC arithmetic
Per-school settings UIProduction/{lang}/compliance (ADMIN/STAFF/DEVELOPER)
Cross-tenant credential groupsProductionDEVELOPER only, /{lang}/(saas-dashboard)/compliance
Circuit breakerProduction3 failures within 1h → halt; 1h cooldown → HALF_OPEN
Encryption (AES-256-GCM)ProductionCOMPLIANCE_ENCRYPTION_KEY env, key-version rotation supported
Audit log integrationProductionNamespaced compliance.* action strings
ADEK piggyback connectorWiredAwaits Aldar group eSIS credentials
ADEK official API connectorStubAwaits ADEK developer access
RPA worker (Playwright)Scaffoldtools/adek-rpa-worker/, awaits eSIS portal selectors
ADEK async webhook receiverWired/api/webhooks/adek (HMAC + ProcessedWebhookEvent dedupe)

Multi-tenant boundary

  • Per-school config table: SchoolComplianceConfig (one row per school × provider, opt-in default off).
  • Worker / claim endpoint requires a SchoolApiToken with scope compliance.rpa_claim — the token's schoolId IS the tenant; request body schoolId is never trusted.
  • DEVELOPER-only saas-dashboard at /{lang}/(saas-dashboard)/compliance for cross-tenant credential groups. Page is role-gated at the layout level.
  • All compliance.* audit entries record schoolId (or null for DEVELOPER cross-tenant actions like creating a credential group).

Sidebar visibility

  • The school-dashboard /compliance entry appears in the sidebar for ADMIN | STAFF | DEVELOPER roles.
  • The page itself enforces a country gate: schools where school.country !== "AE" are redirected to /dashboard unless the actor is a DEVELOPER.

Connector modes

ModeBehavior
DRY_RUNBuild CSV → persist inline (csvArtifactContent) → mark SUBMITTED. School registrar uploads to eSIS manually. Default for the Yasmina BA pilot.
PIGGYBACKDecrypt shared-group credentials, upload via the group's eSIS account. Circuit breaker halts cascading failures across all schools in the group.
OFFICIAL_APIDocumented vendor contract. Currently returns OFFICIAL_API_NOT_AVAILABLE.
RPALeaves the row at QUEUED for the external Fly.io worker. Worker claims via POST /api/compliance/worker/claim, runs Playwright session against eSIS, acks via POST /api/compliance/worker/ack.
DISABLEDSkipped in cron.

Cron schedules (vercel.json)

  • /api/cron/esis-submit — 0 10 * * * (10:00 UTC = 14:00 GST, ADEK rule). Enqueues one ComplianceSubmission row per eligible school whose configured submissionTimeUtc has already passed; fans out via after() for non-RPA modes.
  • /api/cron/absence-followup — */30 * * * *. For each compliance-enabled school, finds ABSENT rows older than parentContactSlaMinutes, dispatches absence_unreported_followup to guardians on in_app + email + whatsapp, and writes an AttendanceIntervention row of type PARENT_EMAIL as audit evidence.

Audit namespace

All compliance events log to AuditLog with action prefix compliance.*:

  • compliance.config.enabled / disabled / mode_changed
  • compliance.credential.created / rotated / revoked
  • compliance.submission.queued / submitted / accepted / rejected / failed / claimed
  • compliance.parent_contact.queued / delivered / failed
  • compliance.circuit_breaker.opened / closed / half_open

AuditLog.userId is nullable so cron / worker / webhook events record with userId: null rather than violating the FK.

Schema

Models live in prisma/models/compliance.prisma:

  • ComplianceProvider enum (ADEK_ESIS, CUSTOM)
  • ConnectorMode enum (DRY_RUN, PIGGYBACK, OFFICIAL_API, RPA, DISABLED)
  • ComplianceSubmissionStatus + CircuitBreakerState enums
  • SchoolComplianceConfig, SharedComplianceCredentialGroup, SchoolComplianceCredential, ComplianceSubmission (idempotency key: [schoolId, provider, submissionDate, attemptNumber])

Environment variables

  • COMPLIANCE_ENCRYPTION_KEY — 32-byte hex (openssl rand -hex 32). Required in production; encryption helper throws at module load if absent.
  • ADEK_WEBHOOK_SECRET — HMAC secret for the async receipt webhook (/api/webhooks/adek).
  • CRON_SECRET — shared with all other Vercel crons.

See also

  • Attendance — the upstream data and notification triggers
  • Notifications — multi-channel dispatch
  • Multi-tenancy — tenant boundary enforcement
AttendanceProfile

On This Page

StatusMulti-tenant boundarySidebar visibilityConnector modesCron schedules (vercel.json)Audit namespaceSchemaEnvironment variablesSee also

Built by Databayt ·

Welcome to balqalam.

A great journey is about to begin.