Sentra Tutoring Management Smartboard

Longitudinal Operational Intelligence for Indonesian Tutoring Centres

Sentra Academic Solutions · Private Product Candidate

Sentra Tutoring Management Smartboard is a governed operating system for Indonesian tutoring centres. It turns schedules, learning sessions, attendance, evaluations, tutor compensation, payroll, and institutional reporting into one traceable longitudinal record centred on Sesi Pembelajaran.

Guided by Human Insight, Powered by Artificial Intelligence.

Why It Exists · Positioning · System Map · Runbook · Governance

Note

The product visual above is expected as a repository-local asset at docs/assets/smartboard-product-overview.png. Runtime documentation must not depend on externally hosted image assets.

Executive Summary

Sentra Tutoring Management Smartboard is a full-stack institutional operations platform for tutoring centres that need academic execution, administrative control, tutor compensation, and parent-safe progress visibility to operate from the same verified source of truth.

Most tutoring operations are fragmented across spreadsheets, messaging groups, manual attendance books, generic learning platforms, and isolated payroll records. Each tool can store a fragment of activity, but none guarantees that a schedule, completed session, student attendance, tutor evaluation, honor calculation, and payroll outcome describe the same real-world event.

Smartboard resolves this fragmentation by treating Sesi Pembelajaran as the primary operational record. Every material consequence must be linked to a session, verified by an authorized role, and carried forward through governed state transitions.

The product serves six operational personas: Owner, Admin Akademik, Tentor, Finance, Murid / Orang Tua, and Content Manager. It includes route-level and API-level authorization, controlled approval queues, longitudinal student progression, audit-aware financial workflows, parent-safe information boundaries, and optional AI-assisted evaluation drafting.

Smartboard is an independent private product candidate inside The Abyss monorepo. It is not an autonomous academic evaluator, an unsupervised payroll authority, a generic content-delivery LMS, or a replacement for institutional judgment. Human review remains mandatory for evaluation publication, session verification, master-data approval, payroll closure, and financial correction.

Dimension	Definition
Product type	Full-stack institutional operations platform
Product family	Sentra Academic Solutions
Repository path	`apps/academic/bimbingan-belajar`
Primary users	Owners, academic administrators, tutors, finance staff, students, and parents
Operational SSOT	`Sesi Pembelajaran` / `learning_sessions`
Primary lifecycle	Schedule → session → attendance → evaluation → verification → honor → payroll
Intelligence model	Longitudinal, role-bounded, verification-driven
Deployment posture	Private product candidate
Interface language	Bahasa Indonesia
Current status	Active development
Product steward	Dr. Ferdi Iskandar

Product Thesis

A tutoring centre becomes governable when every academic, administrative, and financial consequence can be traced back to one verified learning session.

The product does not begin with dashboards. It begins with a stronger data contract: one session must describe what was planned, what actually happened, who participated, what was learned, who verified it, and what institutional consequences followed.

This makes Smartboard a longitudinal intelligence engine rather than a collection of administrative forms. A single score is a snapshot. A sequence of verified sessions becomes a learning trajectory.

Executive Summary
Product Thesis
Why This Product Exists
Strategic Positioning
System Map
Longitudinal Intelligence Model
Experience by Persona
Core Capabilities
Core Domain Architecture
Operational Lifecycle
Trust and Verification Model
Role-Based Access Control
Architecture
Technology Stack
API Surface
Security and Data Governance
Product Experience Principles
Success Metrics
Local Runbook
Environment Variables
Usage
Testing and Governance
Design Language
Documentation
Known Limitations
Contributing
License
Contact
Instrumentation

Why This Product Exists

Tutoring centres often grow through operational improvisation. Schedules live in spreadsheets, attendance is confirmed through messaging groups, tutor notes are stored in personal documents, parent updates are rewritten manually, and honor calculations are reconstructed at the end of each month.

The problem is not that these tools are individually unusable. The problem is that they do not share one governed event model.

Fragmented Operating Model

flowchart LR
    Schedule["Spreadsheet Schedule"]
    Chat["Messaging Group"]
    Attendance["Manual Attendance"]
    Notes["Tutor Notes"]
    Payroll["Separate Payroll Sheet"]
    Reports["Manual Reports"]

    Schedule -. re-entry .-> Attendance
    Chat -. confirmation .-> Attendance
    Attendance -. copy .-> Notes
    Notes -. summarize .-> Reports
    Attendance -. reconcile .-> Payroll
    Schedule -. compare .-> Payroll

    Error["Contradictory Records"]
    Delay["Delayed Decisions"]
    Audit["Weak Auditability"]

    Attendance --> Error
    Payroll --> Error
    Reports --> Delay
    Error --> Audit

    classDef source fill:#FFF7D6,stroke:#D97706,color:#422006,stroke-width:2px;
    classDef risk fill:#FEE2E2,stroke:#DC2626,color:#7F1D1D,stroke-width:3px;

    class Schedule,Chat,Attendance,Notes,Payroll,Reports source;
    class Error,Delay,Audit risk;

This operating model creates predictable institutional risks:

the scheduled tutor may differ from the tutor who actually taught;
attendance may exist without an evaluation;
evaluations may be published before academic verification;
tutor honor may be calculated from a schedule instead of a completed session;
payroll corrections may silently overwrite historical values;
parent-facing information may expose internal operational notes;
management reports may amplify unresolved upstream inconsistencies.

Smartboard Operating Model

flowchart LR
    Plan["Plan"] --> Session["Verified Learning Session"]
    Session --> Attendance["Attendance"]
    Session --> Evaluation["Evaluation"]
    Session --> Tasks["Operational Tasks"]
    Session --> Honor["Tutor Honor"]
    Honor --> Payroll["Payroll Period"]
    Attendance --> Progress["Student Progression"]
    Evaluation --> Progress
    Payroll --> Reports["Institutional Reports"]
    Progress --> Reports

    Governance["RBAC + Approval + Audit"]
    Governance --> Session
    Governance --> Evaluation
    Governance --> Honor
    Governance --> Payroll

    classDef context fill:#FFF7D6,stroke:#D97706,color:#422006,stroke-width:2px;
    classDef core fill:#111827,stroke:#EB5939,color:#FFFFFF,stroke-width:3px;
    classDef academic fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px;
    classDef finance fill:#F3E8FF,stroke:#8B5CF6,color:#4C1D95,stroke-width:2px;
    classDef governed fill:#ECFDF5,stroke:#10B981,color:#064E3B,stroke-width:2px;

    class Plan context;
    class Session core;
    class Attendance,Evaluation,Tasks,Progress academic;
    class Honor,Payroll finance;
    class Governance,Reports governed;

The strategic shift is simple: data is not accepted merely because it was entered. It becomes authoritative only after it passes the appropriate operational and governance state.

Strategic Positioning

Smartboard is positioned between four common categories: informal operational tools, generic learning platforms, school information systems, and isolated financial applications.

The comparison below is an architectural positioning matrix, not a market benchmark or claim about every product in each category.

Capability	Spreadsheet + Messaging	Generic LMS	School SIS / ERP	Standalone Payroll	Sentra Smartboard
Schedule administration	Partial	Partial	Strong	None	Strong
Session-as-operational-SSOT	None	Limited	Variable	None	Core model
Tutor check-in and attendance	Manual	Variable	Strong	None	Integrated
Per-session student evaluation	Manual	Strong	Variable	None	Integrated
Longitudinal learning narrative	Weak	Course-centred	Record-centred	None	Session-centred
Parent-safe note boundary	Manual	Variable	Variable	None	Explicit
Substitute tutor handling	Manual	Limited	Variable	None	Integrated
Tutor honor calculation	Manual	None	Variable	Strong	Session-derived
Payroll-period locking	Manual	None	Variable	Strong	Governed
Academic-to-financial traceability	Weak	Weak	Variable	Weak	End-to-end
Owner approval queue	Manual	Rare	Variable	Variable	Explicit
AI-assisted evaluation draft	External / manual	Variable	Rare	None	Optional and reviewed
Role-bounded operational dashboard	Manual	Learning-centric	Administration-centric	Finance-centric	Cross-functional
Immutable correction workflow	Rare	Not applicable	Variable	Variable	Required after lock

What Makes Smartboard Different

Design Decision	Institutional Consequence
Session-centred domain model	Academic and financial records share the same operational origin
Verification before compensation	Tutor honor is based on governed execution, not only planned schedules
Parent/internal note separation	Family communication is useful without exposing staff-only context
Longitudinal progression	Management can observe direction and change, not only isolated scores
Role-specific work surfaces	Each persona sees the decisions and actions relevant to its authority
Approval queue for controlled writes	High-impact changes cannot silently bypass ownership controls
Locked payroll with corrections	Historical financial records remain explainable after closure
Human-reviewed AI assistance	Language support improves efficiency without transferring authority to AI

What Smartboard Is Not

It is not a generic virtual classroom or video-conferencing platform.
It is not primarily a content marketplace or course-authoring system.
It is not a school-wide student information system for every formal education process.
It is not an autonomous academic scoring engine.
It is not a payroll system detached from academic operations.
It is not a dashboard that infers truth from unverified records.

System Map

The system connects institutional actors to one governed operational core. Each actor receives a bounded work surface; each downstream artifact remains traceable to an authorized workflow.

flowchart TB
    subgraph People["Institutional Actors"]
        Owner["Owner"]
        Admin["Admin Akademik"]
        Tutor["Tentor"]
        Finance["Finance"]
        Parent["Murid / Orang Tua"]
        Content["Content Manager"]
    end

    subgraph Experience["Role-Bounded Experience Layer"]
        Console["React Operations Console"]
        ParentView["Parent-Safe Progress View"]
        ActionQueue["Required Actions + Notifications"]
    end

    subgraph Core["Governed Operational Core"]
        Session["Sesi Pembelajaran SSOT"]
        Approval["Approval Queue"]
        Verification["Session Verification"]
        Audit["Audit Events"]
    end

    subgraph Academic["Academic Operations"]
        Schedule["Schedules"]
        Attendance["Attendance"]
        Evaluation["Evaluations"]
        Progression["Student Progression"]
        Tasks["Tasks + Routines"]
    end

    subgraph Financial["Financial Operations"]
        Rates["Rate Rules"]
        Honor["Tutor Earnings"]
        Overtime["Overtime"]
        Payroll["Payroll + Corrections"]
    end

    subgraph Intelligence["Institutional Intelligence"]
        Dashboard["Operational KPIs"]
        Reports["Academic + Finance Reports"]
        Alerts["Actionable Alerts"]
    end

    Owner --> Console
    Admin --> Console
    Tutor --> Console
    Finance --> Console
    Content --> Console
    Parent --> ParentView

    Console --> ActionQueue
    Console --> Session
    ParentView --> Progression

    Schedule --> Session
    Session --> Attendance
    Session --> Evaluation
    Session --> Tasks
    Session --> Verification
    Approval --> Session
    Verification --> Audit

    Rates --> Honor
    Attendance --> Verification
    Evaluation --> Verification
    Verification --> Honor
    Overtime --> Payroll
    Honor --> Payroll
    Payroll --> Audit

    Attendance --> Progression
    Evaluation --> Progression
    Progression --> Dashboard
    Payroll --> Dashboard
    Audit --> Reports
    Dashboard --> Alerts
    Reports --> Alerts

    classDef actor fill:#FFF7D6,stroke:#D97706,color:#422006,stroke-width:2px;
    classDef surface fill:#FFE8EE,stroke:#EB5939,color:#4A1020,stroke-width:3px;
    classDef core fill:#111827,stroke:#EB5939,color:#FFFFFF,stroke-width:3px;
    classDef academic fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px;
    classDef finance fill:#F3E8FF,stroke:#8B5CF6,color:#4C1D95,stroke-width:2px;
    classDef governed fill:#ECFDF5,stroke:#10B981,color:#064E3B,stroke-width:2px;

    class Owner,Admin,Tutor,Finance,Parent,Content actor;
    class Console,ParentView,ActionQueue surface;
    class Session,Approval,Verification,Audit core;
    class Schedule,Attendance,Evaluation,Progression,Tasks academic;
    class Rates,Honor,Overtime,Payroll finance;
    class Dashboard,Reports,Alerts governed;

Longitudinal Intelligence Model

The platform is designed to transform repeated operational events into an explainable learning history.

flowchart LR
    S1["Session 01"] --> S2["Session 02"] --> S3["Session 03"] --> S4["Session 04"]

    S1 --> E1["Attendance + Evaluation"]
    S2 --> E2["Attendance + Evaluation"]
    S3 --> E3["Attendance + Evaluation"]
    S4 --> E4["Attendance + Evaluation"]

    E1 --> Trend["Longitudinal Progression"]
    E2 --> Trend
    E3 --> Trend
    E4 --> Trend

    Trend --> Pattern["Growth Pattern"]
    Trend --> Risk["Learning Friction"]
    Trend --> Action["Tutor / Admin Action"]
    Action --> S4

    classDef session fill:#111827,stroke:#EB5939,color:#FFFFFF,stroke-width:3px;
    classDef evidence fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px;
    classDef intelligence fill:#ECFDF5,stroke:#10B981,color:#064E3B,stroke-width:3px;
    classDef attention fill:#FFF7D6,stroke:#D97706,color:#422006,stroke-width:2px;

    class S1,S2,S3,S4 session;
    class E1,E2,E3,E4 evidence;
    class Trend,Pattern intelligence;
    class Risk,Action attention;

Intelligence Layers

Layer	Question Answered	Primary Evidence	Output Boundary
Event layer	What happened in this session?	Schedule, attendance, tutor, subject, duration	Factual operational record
Evaluation layer	How did the student perform in context?	Tutor ratings, summary, parent note, internal note	Human-authored or human-approved assessment
Progression layer	How is the student changing over time?	Repeated verified evaluations	Trend and trajectory, not diagnosis
Operational layer	What requires institutional action?	Missing evaluations, unverified sessions, exceptions	Prioritized action queue
Financial layer	What compensation follows verified work?	Session verification, rate rules, overtime	Governed honor and payroll entries
Governance layer	Can this record be trusted and disclosed?	Role, approval, verification, audit history	Allow, redact, block, or request revision

Experience by Persona

Smartboard does not expose the same application to everyone. It creates a role-bounded institutional experience around authority, responsibility, and information need.

Persona	Primary Question	Core Workspace	Must Not Access
Owner	Is the institution operating correctly and sustainably?	Approvals, KPIs, payroll locking, audit, exception management	None beyond system policy
Admin Akademik	What must be scheduled, completed, verified, or corrected?	Master data, schedules, sessions, attendance, evaluation completion	Owner-only governance overrides
Tentor	What do I teach, record, evaluate, and complete?	Assigned sessions, check-in, attendance, evaluation, tasks, own honor	Other tutors' payroll or unrestricted student records
Finance	Which verified obligations must be processed and closed?	Rate rules, honor recap, overtime approval, payroll, corrections	Internal academic notes without finance purpose
Murid / Orang Tua	What happened and how is learning progressing?	Parent-safe session history and evaluation summaries	Internal notes, staff workflow, unrelated students
Content Manager	Which evaluation structures support consistent teaching?	Rubrics, templates, content standards	Payroll and private financial records

Persona Journey

sequenceDiagram
    participant O as Owner
    participant A as Admin Akademik
    participant T as Tentor
    participant S as Smartboard
    participant F as Finance
    participant P as Parent

    A->>S: Create schedule template
    S-->>A: Generate future sessions
    T->>S: Check in and record attendance
    S-->>T: Create evaluation task
    T->>S: Submit reviewed evaluation
    A->>S: Verify completed session
    S-->>F: Create governed honor basis
    F->>S: Generate and verify payroll period
    S-->>P: Publish parent-safe progression view
    O->>S: Review approvals, exceptions, and institutional KPIs

Core Capabilities

Capability	Operational Purpose	Evidence Source	Status
Authentication and RBAC	Enforce persona-specific route and API access	Auth session, role guards	Active
Master Data	Manage institutional entities and rate rules	Controlled CRUD records	Active
Approval Queue	Gate high-impact master-data changes	Owner decision record	Active
Schedule and Session Sync	Generate recurring or one-off sessions and synchronize future changes	Schedule templates and session instances	Active
Attendance and Substitute Coverage	Record tutor execution, student presence, catch-up, and substitute tutor context	Session attendance records	Active
Evaluation Workflows	Capture structured per-student learning evidence	Human-reviewed evaluation records	Active
AI-Assisted Drafting	Prepare optional evaluation language without publishing autonomously	Prompt provenance and human submission	Active, optional
Tasks and Routines	Convert lifecycle events into accountable work items	Triggered task records	Active
Overtime	Submit, review, and route approved overtime into payroll	Approval and payroll linkage	Active
Tutor Honor	Calculate earnings from verified work and rate rules	Verified session + rate evidence	Active
Payroll	Aggregate, verify, pay, lock, and correct compensation periods	Payroll period state and immutable corrections	Active
Unified Reports	Export academic, operational, finance, and compliance views	Governed source records	Active
Student Progression	Present learning history and longitudinal trends	Verified session evaluations	Active
In-App Notifications	Surface required actions and workflow exceptions	Role-bounded event delivery	Active

Capability Boundaries

AI-generated content is a draft, never an autonomous academic decision.
A scheduled session does not automatically prove that teaching occurred.
Tutor honor becomes authoritative only after required session verification.
Parent-facing responses must exclude internal_note and staff-only context.
Locked payroll periods must not be silently mutated.
Reports are only as trustworthy as the records and verification states beneath them.
Roadmap work must not be represented as current capability.

Core Domain Architecture

The bimbel_ops database is organized around learning_sessions. A schedule is an instruction to create sessions; the session is the authoritative record of execution.

flowchart TB
    Schedule["Schedule Template"] -->|generates| Session["Learning Session"]

    Session --> Identity["Tutor + Students + Subject + Time + Room"]
    Session --> Attendance["Attendance"]
    Session --> Evaluation["Evaluation"]
    Session --> Task["Tasks"]
    Session --> Verification["Verification"]

    Verification --> Earnings["Tutor Earnings"]
    Rates["Rate Rules"] --> Earnings
    Overtime["Approved Overtime"] --> Payroll["Payroll Period"]
    Earnings --> Payroll
    Payroll --> Slip["Honor Slip"]
    Payroll --> Correction["Immutable Correction"]

    Attendance --> Progression["Student Progression"]
    Evaluation --> Progression

    Approval["Approval Queue"] --> Schedule
    Approval --> Rates
    Audit["Audit Events"] --> Verification
    Audit --> Payroll

    classDef source fill:#FFF7D6,stroke:#D97706,color:#422006,stroke-width:2px;
    classDef core fill:#111827,stroke:#EB5939,color:#FFFFFF,stroke-width:3px;
    classDef academic fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px;
    classDef finance fill:#F3E8FF,stroke:#8B5CF6,color:#4C1D95,stroke-width:2px;
    classDef governed fill:#ECFDF5,stroke:#10B981,color:#064E3B,stroke-width:2px;

    class Schedule,Rates,Overtime source;
    class Session core;
    class Identity,Attendance,Evaluation,Task,Progression academic;
    class Earnings,Payroll,Slip,Correction finance;
    class Verification,Approval,Audit governed;

Main Domain Collections

Collection	Responsibility	Authority Condition
`learning_sessions`	Session identity, assignments, lifecycle, verification state	Authoritative after governed state transition
`schedules`	One-off and recurring planning templates	Planning source, not proof of execution
`attendance`	Tutor check-in/out and per-student presence	Valid only within an authorized session context
`evaluations`	Ratings, summaries, parent notes, internal notes, AI provenance	Publishable after required human action
`tutor_earnings`	Rate-derived honor entries linked to verified work	Financial basis after verification
`payroll_periods`	Payroll lifecycle and closure state	Authoritative when verified or locked
`payroll_items`	Per-tutor obligations and payment metadata	Bound to a payroll period
`payroll_corrections`	Post-lock immutable adjustments	Required after period closure
`overtime_requests`	Submission, approval, and payroll integration	Financial effect after approval
`tasks`	Routine operational work and evaluation triggers	Actionable by assigned role
`approval_queue`	Owner decisions for controlled writes	Required for configured high-impact changes
`notifications`	Role-bounded delivery state	Informational, not source of truth

Operational Lifecycle

stateDiagram-v2
    [*] --> Planned
    Planned --> Scheduled: schedule generates session
    Scheduled --> InProgress: tutor checks in
    InProgress --> Completed: attendance and teaching completed
    Completed --> EvaluationPending: evaluation task open
    EvaluationPending --> ReviewReady: tutor submits evaluation
    ReviewReady --> Verified: admin or owner verifies session
    Verified --> HonorGenerated: rate rules applied
    HonorGenerated --> PayrollDraft: finance aggregates obligations
    PayrollDraft --> PayrollVerified: finance verifies period
    PayrollVerified --> Paid: payment metadata recorded
    Paid --> Locked: period formally closed
    Locked --> Corrected: immutable correction approved

    Planned --> Cancelled
    Scheduled --> Rescheduled
    Rescheduled --> Scheduled
    Completed --> RevisionRequired: verification fails
    RevisionRequired --> ReviewReady

Lifecycle Responsibilities

Schedule creation — Admin Akademik or Owner defines a one-off or recurring schedule template.
Session generation — Smartboard creates future session instances with explicit date, time, tutor, students, subject, and location context.
Session execution — The assigned tutor checks in, records attendance, and identifies substitute or catch-up conditions when applicable.
Evaluation completion — The tutor records structured student evidence and reviews any optional AI-generated draft before submission.
Session verification — Admin Akademik or Owner confirms that the record is complete enough to become an institutional source.
Honor generation — Verified session evidence is combined with rate, duration, transport, substitution, and overtime rules.
Payroll closure — Finance creates, verifies, pays, and locks a payroll period.
Correction — Any post-lock change uses an explicit correction record, preserving historical explainability.

Trust and Verification Model

Smartboard distinguishes entered data, reviewed data, and authoritative data. This prevents the interface from treating every form submission as institutional truth.

flowchart LR
    Entered["Entered"] --> Validated["Structurally Validated"]
    Validated --> Reviewed["Human Reviewed"]
    Reviewed --> Verified["Operationally Verified"]
    Verified --> Authoritative["Authoritative for Downstream Use"]

    Entered -. invalid .-> Rejected["Rejected"]
    Validated -. incomplete .-> Revision["Revision Required"]
    Reviewed -. unauthorized .-> Blocked["Blocked"]
    Verified -. sensitive .-> Redacted["Role-Bounded / Redacted"]

    classDef neutral fill:#FFF7D6,stroke:#D97706,color:#422006,stroke-width:2px;
    classDef process fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px;
    classDef safe fill:#ECFDF5,stroke:#10B981,color:#064E3B,stroke-width:3px;
    classDef risk fill:#FEE2E2,stroke:#DC2626,color:#7F1D1D,stroke-width:3px;

    class Entered neutral;
    class Validated,Reviewed,Verified process;
    class Authoritative,Redacted safe;
    class Rejected,Revision,Blocked risk;

Authority Rules

Record	Entered By	Verified By	Authoritative For
Schedule	Owner / Admin Akademik	Workflow validation or configured approval	Future session generation
Attendance	Tentor / authorized admin	Session verification	Progression evidence and honor eligibility
Evaluation	Tentor	Tutor submission plus configured review boundary	Parent-safe progress history
Rate rule	Owner / authorized finance role	Controlled approval policy	Honor calculation
Tutor earning	System	Verified session and rate evidence	Payroll draft
Payroll period	Finance	Finance / Owner according to policy	Payment and closure
Payroll correction	Authorized finance governance role	Formal approval	Post-lock adjustment

Role-Based Access Control

Authorization is enforced at both the frontend route layer and backend require_roles() guards. Interface visibility is not considered a security boundary by itself.

Capability	Owner	Admin Akademik	Tentor	Finance	Murid / Orang Tua	Content Manager
Institutional dashboard	Full	Operational	Personal	Financial	No	Limited
Master data	Full	Manage	Read assigned	Bounded rates	No	Template-related
Approval queue	Approve	Submit / view status	No	Bounded	No	Submit where configured
Schedule management	Full	Full	Assigned view	Read as needed	Linked view	No
Session execution	Override	Manage	Assigned sessions	Read as needed	Linked view	No
Attendance	Full	Manage / catch-up	Record assigned	Read as needed	Linked summary	No
Evaluations	Full	Review / manage	Create assigned	No	Parent-safe view	Template governance
Internal notes	Full	Authorized	Own assigned context	No by default	Never	No by default
Honor recap	Full	Bounded	Own only	Full	Never	Never
Payroll	Lock / govern	No	Own slip	Create / verify / pay	Never	Never
Audit access	Full	Bounded	Own events where useful	Financial audit	Never	Template events only

Important

API responses for murid_ortu must remove internal_note, staff workflow metadata, unrestricted identifiers, and any unrelated student information before serialization.

Architecture

The product uses a React single-page application, a FastAPI service, and a MongoDB operational database. Domain routers remain separated by responsibility while authorization, audit behaviour, data redaction, and state-transition rules are centralized.

apps/academic/bimbingan-belajar/
├── backend/                         # FastAPI service — Python 3.12
│   ├── server.py                    # App entrypoint, CORS, routers, auto-seed
│   ├── db.py                        # Motor client and audit helper
│   ├── models.py                    # Pydantic models and status vocabularies
│   ├── auth.py                      # Session tokens and role guards
│   ├── ai_client.py                 # Provider-agnostic AI draft client
│   ├── routes_approvals.py          # Owner approval queue
│   ├── routes_master.py             # Master-data operations
│   ├── routes_ops.py                # Schedules, sessions, attendance, evaluations
│   ├── routes_finance.py            # Tutor earnings and honor recap
│   ├── routes_dashboard.py          # KPIs and actionable alerts
│   ├── routes_tasks.py              # Tutor routine tasks
│   ├── routes_overtime.py           # Overtime workflow
│   ├── routes_payroll.py            # Payroll, payments, corrections, PDF slips
│   ├── routes_reports.py            # CSV, PDF, and XLSX reporting
│   ├── routes_templates.py          # Evaluation templates
│   ├── routes_progression.py        # Student progression
│   ├── routes_notifications.py      # In-app notifications
│   ├── seed_data.py                 # Idempotent synthetic data
│   ├── scripts/                     # Local testing utilities
│   ├── tests/                       # Pytest integration suite
│   └── requirements.txt             # Backend dependencies
│
├── frontend/                        # React 19 SPA — CRA / CRACO
│   ├── public/                      # Static and brand assets
│   ├── src/
│   │   ├── App.js                   # Router and role-gated routes
│   │   ├── App.css                  # Shared layout and surface utilities
│   │   ├── index.css                # Typography and semantic aliases
│   │   ├── sentra-tokens.css        # Vendored Sentra CSS tokens
│   │   ├── sentra-tokens.json       # Vendored Sentra JSON tokens
│   │   ├── pages/                   # Bahasa Indonesia product screens
│   │   ├── components/ui/           # Shared UI primitives
│   │   └── lib/                     # API client, auth context, label mappings
│   └── package.json                 # Yarn scripts and dependencies
│
├── brand/                           # Official Sentra Academic Solutions marks
├── docs/                            # Architecture, runbooks, governance, assets
├── memory/PRD.md                    # Product requirements and phase status
├── AGENTS.md                        # Agent and developer operating contract
├── CONTRIBUTING.md                  # Contribution and verification rules
└── README.md                        # Canonical product entrypoint

Application Architecture

flowchart LR
    Browser["Browser"] --> React["React Operations Console"]
    React --> API["FastAPI REST API"]
    API --> Auth["Authentication + RBAC"]
    API --> Domain["Domain Services / Routers"]
    Domain --> Mongo["MongoDB bimbel_ops"]
    Domain --> Reports["CSV / PDF / XLSX Exports"]
    Domain --> AI["Optional AI Draft Provider"]

    Auth --> Audit["Audit Events"]
    Domain --> Audit
    AI --> Review["Mandatory Human Review"]
    Review --> Domain

    classDef entry fill:#FFF7D6,stroke:#D97706,color:#422006,stroke-width:2px;
    classDef product fill:#FFE8EE,stroke:#EB5939,color:#4A1020,stroke-width:3px;
    classDef service fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px;
    classDef data fill:#F3E8FF,stroke:#8B5CF6,color:#4C1D95,stroke-width:2px;
    classDef governed fill:#ECFDF5,stroke:#10B981,color:#064E3B,stroke-width:2px;

    class Browser entry;
    class React product;
    class API,Domain,Reports,AI service;
    class Mongo data;
    class Auth,Audit,Review governed;

Key Components

Component	Responsibility
`backend/auth.py`	Exchange session tokens and enforce role gates
`backend/routes_ops.py`	Protect the schedule-to-session operational lifecycle
`backend/routes_payroll.py`	Govern generation, verification, payment, locking, correction, and slips
`backend/ai_client.py`	Generate provider-agnostic drafts without bypassing human authority
`backend/routes_progression.py`	Assemble longitudinal learning history within role boundaries
`backend/routes_reports.py`	Export governed institutional records into operational formats
`frontend/src/App.js`	Define role-gated navigation and product surfaces
`frontend/src/sentra-tokens.css`	Apply canonical Sentra visual tokens

Technology Stack

Versions below reflect the repository-declared baseline and must be reconciled with manifests and lockfiles before release claims are updated.

Layer	Technology	Version	Responsibility
Frontend	React + CRA / CRACO	`19`	Role-gated single-page application
Backend	FastAPI	Repository-pinned	REST API and workflow orchestration
Backend runtime	Python	`3.12`	Service execution environment
Frontend runtime	Node.js	`20+`	Build and development environment
Database	MongoDB	`7`	Operational document storage
Database client	Motor	Repository-pinned	Asynchronous MongoDB access
Package manager	Yarn Classic	`1.22.22`	Frontend dependency and script management
Testing	Pytest	Repository-pinned	Backend integration validation
Styling	Tailwind CSS + Radix UI + Sentra Tokens	Repository-pinned	Product interface composition
Reporting	ReportLab + CSV / XLSX tooling	Repository-pinned	Operational and financial exports
Local infrastructure	Docker	Current supported release	Reproducible MongoDB service
AI integration	OpenAI-compatible provider interface	Configurable	Optional evaluation drafting

API Surface

All backend endpoints are prefixed with /api. Protected routes require an approved Bearer token or authenticated cookie and the appropriate role.

Domain	Base Path	Representative Endpoints	Access Boundary
Auth	`/api/auth`	`GET /me`, `POST /login`, `POST /logout`, `GET /callback`	Authenticated users; callback public
Approvals	`/api/approvals`	`GET /pending`, `POST /{id}/action`	Owner only
Master Data	`/api/master`	Schools, subjects, grades, academic years, people, teams, rate rules	Owner and Admin Akademik; bounded Finance reads
Operations	`/api`	Schedules, sessions, check-in, attendance, evaluations, verification, reschedule, cancel	Role-specific operational access
Tasks	`/api/tasks`	`GET/POST /`, `PUT /{id}/status`	Owner, Admin Akademik, Tentor
Overtime	`/api/lembur`	`GET/POST /`, `POST /{id}/approval`	Tentor filing; Owner or Finance approval
Finance	`/api/finance`	Honor recap and rate rules	Owner, Finance, bounded personal Tutor view
Payroll	`/api/payroll`	Periods, locking, payments, corrections, slips	Owner and Finance; own-slip Tutor view
Dashboard	`/api/dashboard`	KPIs, required actions, today's schedule	Authenticated roles
Reports	`/api/reports`	Unified report and CSV/PDF/XLSX exports	Owner, Admin Akademik, Finance
Templates	`/api/templates`	Evaluation template operations	Owner, Admin Akademik, Content Manager
Progression	`/api/progression`	Student progression by identifier	Role- and relationship-bounded
Notifications	`/api/notifications`	Unread list and read state	Authenticated roles

For route-level request, response, and failure contracts, read the backend API specification and router source.

Security and Data Governance

Security Principles

Fail-closed authorization — missing, invalid, expired, or insufficient roles deny access.
Least-necessary disclosure — each persona receives only the fields needed for its task.
Parent-safe serialization — internal notes and staff workflow data never appear in parent responses.
Synthetic development data — real student, parent, tutor, attendance, and payroll records must not be used as local fixtures.
Human authority over AI — generated drafts cannot publish, verify, or financially authorize themselves.
Financial immutability — closed payroll changes require explicit correction records.
Auditability — high-impact actions must remain attributable to an actor, role, time, and affected record.
Explicit hard gates — authentication strategy, OWNER_EMAILS, schema redesign, secret rotation, and production deployment require explicit Chief GO.

Data Classification

Data Class	Examples	Minimum Handling Boundary
Public product metadata	Product name, non-sensitive documentation	May appear in repository documentation
Internal operational	Schedules, tasks, room assignments	Authenticated and role-bounded
Personal academic	Student identity, attendance, evaluations	Relationship-bounded, auditable, redacted where required
Staff confidential	Internal notes, tutor performance context	Staff-only, purpose-limited
Financial confidential	Rates, earnings, payroll, transfer metadata	Owner / Finance boundary
Secrets	Tokens, API keys, credentials	Server-side only; never committed

AI Data Boundary

flowchart LR
    Source["Academic Context"] --> Redact["Remove Direct Identifiers"]
    Redact --> Prompt["Bounded Draft Prompt"]
    Prompt --> Provider["Configured AI Provider"]
    Provider --> Draft["Non-Authoritative Draft"]
    Draft --> Human["Tutor Review"]
    Human --> Submit["Explicit Submission"]

    Source -. contains PII .-> Block["Block Prompt"]
    Draft -. unsafe / inaccurate .-> Revise["Revise or Discard"]

    classDef input fill:#FFF7D6,stroke:#D97706,color:#422006,stroke-width:2px;
    classDef process fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px;
    classDef safe fill:#ECFDF5,stroke:#10B981,color:#064E3B,stroke-width:3px;
    classDef risk fill:#FEE2E2,stroke:#DC2626,color:#7F1D1D,stroke-width:3px;

    class Source input;
    class Redact,Prompt,Provider,Draft process;
    class Human,Submit safe;
    class Block,Revise risk;

Private vulnerability reporting and security handling are defined in docs/SECURITY.md.

Product Experience Principles

Smartboard is designed as an operational instrument, not a collection of equal navigation destinations.

Principle	Product Behaviour
Action before decoration	Surfaces prioritize required decisions, exceptions, and incomplete work
One source, multiple views	Personas see different projections of the same governed domain records
Progressive disclosure	Sensitive or advanced controls appear only when authority and context justify them
Explainable status	Every state communicates what happened, who owns the next action, and what blocks progress
Longitudinal over episodic	Student views emphasize development over isolated scores
Exception-driven operations	Dashboards highlight missing, late, inconsistent, or approval-dependent records
Human-reviewed intelligence	AI accelerates drafting but does not own evaluation or institutional decisions
Financial traceability	Compensation remains linked to verified academic execution

Smartboard Information Hierarchy

flowchart TB
    Now["What Requires Action Now?"]
    Next["What Happens Next?"]
    Evidence["What Evidence Supports This?"]
    History["How Did This Develop Over Time?"]
    Governance["Who Can Verify or Change It?"]

    Now --> Next
    Next --> Evidence
    Evidence --> History
    History --> Governance

    classDef priority fill:#111827,stroke:#EB5939,color:#FFFFFF,stroke-width:3px;
    classDef information fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px;
    classDef governed fill:#ECFDF5,stroke:#10B981,color:#064E3B,stroke-width:2px;

    class Now priority;
    class Next,Evidence,History information;
    class Governance governed;

Success Metrics

The product should be evaluated by whether it improves institutional truth, workflow completion, and decision latency—not merely by page views or record volume.

These are measurement definitions, not claims of achieved performance.

Metric	Definition	Desired Direction	Guardrail
Session verification completion	Verified completed sessions ÷ completed sessions	Increase	Must not incentivize superficial verification
Evaluation completion latency	Time from session completion to submitted evaluation	Decrease	Quality and human review remain mandatory
Attendance completeness	Sessions with complete tutor and student attendance	Increase	Corrections remain attributable
Honor traceability	Payroll items linked to verified source evidence	Increase toward 100%	No manual orphan payments
Payroll correction rate	Corrections after period lock ÷ locked items	Decrease	Corrections must never be hidden
Parent-safe publication rate	Published evaluations passing redaction and relationship checks	Increase	Internal notes remain excluded
Approval turnaround	Time from controlled write submission to decision	Decrease	Owner governance must not be bypassed
Exception resolution time	Time from alert creation to governed resolution	Decrease	Closure requires evidence, not dismissal
Longitudinal coverage	Active students with sufficient verified session history	Increase	Avoid misleading trends from sparse data

Local Runbook

Prerequisites

Requirement	Minimum / Required Version
Docker Desktop	Current supported release
MongoDB image	`mongo:7`
Python	`3.12`
Node.js	`20+`
Yarn	`1.22.22`

Note

Use 127.0.0.1 instead of localhost for local MongoDB and FastAPI access to avoid IPv6 / IPv4 resolution inconsistencies. Do not use Python 3.14 with the currently documented Motor dependency boundary.

Start MongoDB

docker run -d --name bimbel-mongo -p 27017:27017 -v bimbel-mongo-data:/data/db mongo:7
docker exec bimbel-mongo mongosh --quiet --eval "db.runCommand({ping:1})"

Start Backend

cd apps\academic\bimbingan-belajar\backend
Copy-Item .env.example .env
py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
uvicorn server:app --reload --host 127.0.0.1 --port 8001

Smoke test:

http://127.0.0.1:8001/api/

Expected response:

{
  "app": "Sentra Tutoring Management Smartboard",
  "version": "1.0.0",
  "status": "ok"
}

When MongoDB is empty, the backend may invoke the idempotent synthetic seed.

Start Frontend

cd apps\academic\bimbingan-belajar\frontend
Copy-Item .env.example .env
yarn install
yarn start

Local interface:

http://127.0.0.1:3000

Seed Local Test Sessions

docker cp apps\academic\bimbingan-belajar\backend\scripts\seed_test_sessions.js bimbel-mongo:/tmp/seed_test_sessions.js
docker exec bimbel-mongo mongosh bimbel_ops --quiet /tmp/seed_test_sessions.js

Documented local-only test tokens:

Persona	Token
Owner	`test_owner_session_bimbel_01`
Tentor	`test_tutor_session_bimbel_01`
Orang Tua	`test_parent_session_bimbel_01`

Example request:

curl -H "Authorization: Bearer test_owner_session_bimbel_01" http://127.0.0.1:8001/api/auth/me

Caution

Test tokens are development fixtures. They must never be enabled or accepted in production environments.

Environment Variables

Backend — `backend/.env`

Variable	Required	Scope	Purpose	Safe Example
`MONGO_URL`	Yes	Server	MongoDB connection string	`mongodb://127.0.0.1:27017`
`DB_NAME`	Yes	Server	Database name	`bimbel_ops`
`CORS_ORIGINS`	Yes	Server	Allowed frontend origins	`http://127.0.0.1:3000`
`OWNER_EMAILS`	Recommended	Server	Email allow-list mapped to Owner	`owner@example.com`
`COOKIE_SECURE`	Yes	Server	Require secure cookie transport	`false` locally
`COOKIE_SAMESITE`	Yes	Server	Cookie cross-site policy	`lax` locally
`AI_ENABLED`	No	Server	Enable optional evaluation drafting	`false`
`AI_BASE_URL`	Conditional	Server	OpenAI-compatible provider endpoint	`https://provider.example/v1`
`AI_MODEL`	Conditional	Server	Provider model identifier	`example/instruct-model`
`AI_API_KEY`	Conditional	Server	Provider secret	`replace_with_local_secret`

Frontend — `frontend/.env`

Variable	Required	Scope	Purpose	Safe Example
`REACT_APP_BACKEND_URL`	Yes	Client	Backend API base URL	`http://127.0.0.1:8001`
`ENABLE_HEALTH_CHECK`	No	Build	Enable CRACO health-check endpoint	`true`

Never commit production credentials, real student data, payroll metadata, or provider secrets.

Usage

Institutional Workflow

Sign in with an authorized role.
Configure master data, rate rules, and a schedule template.
Generate or open a Sesi Pembelajaran.
Record tutor execution and student attendance.
Complete and review student evaluations.
Resolve missing data or workflow exceptions.
Verify the session.
Review generated tutor earnings.
Create, verify, pay, and lock the payroll period.
Publish parent-safe progression information.
Export the required operational or financial report.

Example: Session-to-Payroll Trace

Schedule: SCH-2026-0019
└── Session: SES-2026-0142
    ├── Tutor attendance: complete
    ├── Student attendance: complete
    ├── Evaluation: submitted
    ├── Verification: approved by Admin Akademik
    └── Tutor earning: EARN-2026-0084
        └── Payroll period: PAY-2026-07
            └── Status: locked

The identifiers above are synthetic examples. Production identifiers and personal records must not be copied into public documentation.

AI Draft Boundary

AI support may prepare evaluation language from non-identifying academic context. The tutor must review, revise where needed, and explicitly submit the final evaluation.

AI-generated text must not:

become authoritative merely because it was generated;
receive student or parent names in prompts;
publish itself to a parent-facing surface;
assign payroll consequences;
bypass tutor, admin, owner, or finance authority.

Testing and Governance

flowchart TD
    Change["Code, Schema, Configuration, or Content Change"] --> Backend["Backend Tests"]
    Change --> Frontend["Frontend Tests"]
    Change --> Build["Production Build"]
    Change --> Security["Security + PII Review"]
    Change --> RBAC["Role Boundary Review"]
    Change --> Financial["Financial Integrity Review"]
    Change --> AI["AI Privacy + Authority Review"]
    Change --> Docs["Documentation Consistency"]

    Backend --> Merge["Eligible to Merge"]
    Frontend --> Merge
    Build --> Merge
    Security --> Merge
    RBAC --> Merge
    Financial --> Merge
    AI --> Merge
    Docs --> Merge

    Backend -. fail .-> Block["Block Merge"]
    Frontend -. fail .-> Block
    Build -. fail .-> Block
    Security -. fail .-> Block
    RBAC -. fail .-> Block
    Financial -. fail .-> Block
    AI -. fail .-> Block
    Docs -. fail .-> Block

    classDef check fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px;
    classDef pass fill:#ECFDF5,stroke:#10B981,color:#064E3B,stroke-width:3px;
    classDef block fill:#FEE2E2,stroke:#DC2626,color:#7F1D1D,stroke-width:3px;

    class Change,Backend,Frontend,Build,Security,RBAC,Financial,AI,Docs check;
    class Merge pass;
    class Block block;

Verification Commands

# Backend integration tests
cd apps\academic\bimbingan-belajar\backend
.\.venv\Scripts\Activate.ps1
python -m pytest tests/ -q

# Frontend unit tests
cd ..\frontend
yarn test --watchAll=false

# Frontend production build
yarn build

Required Gates

Area	Minimum Check
Backend	Relevant Pytest suites pass
Frontend	Unit smoke tests pass
Build	`yarn build` completes successfully
Authentication	Unauthorized and cross-role access fails closed
Parent safety	Internal notes remain absent from parent responses
Relationship boundary	Users cannot access unrelated student records
AI privacy	No directly identifying student data enters provider prompts
AI authority	Drafts require explicit human review and submission
Payroll	Locked periods require immutable correction flow
Auditability	High-impact state changes retain actor and timestamp evidence
Documentation	Commands, routes, variables, versions, and claims remain accurate

Repository-reported baseline dated 2026-07-26:

Backend: 76 passed, 2 skipped
Frontend unit smoke tests: passed
CRACO production build: success

This baseline is descriptive. It must be re-run before claiming a new change is verified.

Design Language

The frontend consumes the monorepo-wide Sentra Design System from packages/design-tokens.

Layer	Rule
Typography	Archivo for primary interface text; JetBrains Mono for labels, codes, and numeric surfaces
Color	Use Sentra semantic OKLCH tokens; do not hardcode raw colors in product UI
Geometry	Square corners, `1px` borders, disciplined 12-column layouts
Labels	Uppercase monospace labels with deliberate letter spacing
Assets	Vend assets locally; no runtime CDN or external font dependency
Storage	Do not use `localStorage` or `sessionStorage` for product state
Motion	Use motion only when it communicates state, progress, or sequence
Density	Prefer operational density without hiding hierarchy or authority
Status	Communicate state with text and structure, not color alone

Token sources:

frontend/src/sentra-tokens.css
frontend/src/sentra-tokens.json

Monorepo token verification:

pnpm check:tokens

GitHub Mermaid diagrams use canonical Sentra semantic fallback colors for renderer compatibility. Product UI remains governed by the OKLCH token source.

Documentation

The root README is the canonical product entrypoint. Detailed specifications, runbooks, governance policies, and component documentation remain in their specialized files.

Project Documentation Suite

Document	Purpose	Standard / Format
`PROJECT_CHARTER.txt`	Executive charter, strategic scope, and governance baseline	Plain text project charter
`docs/SOFTWARE_REQUIREMENTS_SPECIFICATION.md`	Functional, non-functional, and capability-gap requirements	ISO/IEC/IEEE 29148-aligned SRS
`docs/API_SPECIFICATION.md`	REST endpoints, schemas, authentication, and RBAC matrix	REST / OpenAPI-oriented specification
`docs/DATA_GOVERNANCE_AND_PRIVACY.txt`	Privacy rules, PII controls, audit logging, and AI provenance	ISO/IEC 27001-aligned governance document
`docs/OPERATIONAL_RUNBOOK.md`	Deployment, environment configuration, database seeding, and troubleshooting	SRE / DevOps runbook
`docs/README.md`	Unified documentation index and specification catalog	Technical documentation index

Repository Documentation

Document	Responsibility
`AGENTS.md`	Operating contract for agents and developers
`CONTRIBUTING.md`	Contribution workflow and verification matrix
`docs/ARCHITECTURE.md`	Architecture and detailed domain flows
`docs/DEVELOPMENT.md`	Local setup, scripts, and troubleshooting
`docs/ENVIRONMENT.md`	Environment-variable and secret contracts
`docs/SECURITY.md`	RBAC, cookie, PII, and security policy
`memory/PRD.md`	Product requirements, phase status, and backlog
`backend/README.md`	Backend service and router guide
`frontend/README.md`	Frontend architecture and token integration

Brand Assets

Official Sentra Academic Solutions marks are stored in brand/ and served to the application from frontend/public/brand/.

Asset	Intended Use
`*-lockup-transparent.svg`	Light surfaces, sidebars, and repository documentation
`*-lockup-dark.svg`	Dark surfaces and authentication panels
`-app-icon.svg` / `.png`	Favicons and application icons
`docs/assets/smartboard-product-overview.png`	Canonical README product visual

Known Limitations

Limitation	Risk	Current Boundary
External AI provider dependency	Availability, latency, or draft variability	AI is optional and human-reviewed
MongoDB document model	Cross-collection consistency requires disciplined services	Session-centred workflows and verification gates
CRA / CRACO lifecycle	Toolchain maintenance pressure	Pin Yarn and verify production builds
Operational PII concentration	Unauthorized access could expose education and payroll data	RBAC, redaction, private deployment, and audit controls
Report correctness	Exports may amplify upstream data errors	Verify sessions and payroll before export
Longitudinal sparsity	Small evidence sets may create misleading trends	Display evidence coverage and avoid overinterpretation
Human verification load	Strong governance may create operational bottlenecks	Prioritize exception queues and accountable ownership
Offline operational dependency	Connectivity loss may interrupt real-time workflows	Offline-first behavior is not represented as current capability
Integration breadth	External accounting, messaging, or biometric systems may require adapters	Planned integrations remain separate from active capability

Planned work must remain separated from active capability and tracked in product requirements documentation.

Contributing

Contributions must follow CONTRIBUTING.md and the local agent contract in AGENTS.md.

Minimum workflow:

read the governing documentation;
identify affected authorization, PII, academic, and financial boundaries;
state the intended invariant before implementation;
make the smallest safe change;
run the relevant backend, frontend, build, security, and documentation checks;
record unverified assumptions explicitly;
obtain explicit approval for Class C hard-gate changes.

License

Private proprietary product candidate under The Abyss monorepo.

Do not publish production credentials, real student PII, payroll records, internal infrastructure details, protected source code, or private product assets without explicit authorization.

Contact

Dr. Ferdi Iskandar
Owner and Principal Steward, Sentra Tutoring Management Smartboard
Sentra Academic Solutions

Operational escalation and repository support must use the approved internal Sentra channel or issue workflow defined for The Abyss monorepo.

Instrumentation