AENS InfoSys — User Guide

1. System Overview

AENS InfoSys is a DepEd K–12 Senior High School Student Information System for Aparri East National High School. It covers the complete academic lifecycle: student enrolment, quarterly grade encoding, attendance, observed values, official form generation (SF9, SF10, E-Card, IIF), honor roll, year-end promotion/retention processing, and school-year rollover.

Access the system at https://aenhsinfosys.downstreamtech.net from any modern browser on desktop, tablet, or mobile. Students sign in with their 12-digit LRN; staff sign in with their school email.

3. User Roles & Portals

Every user has one or more roles. A teacher can simultaneously be a Subject Teacher and a Class Adviser — the system shows both portals with a switch link.

4. RBAC Permission Matrix

Which features each role can access. SA = Super Admin, T = Subject Teacher, Adv = Class Adviser, R = Registrar, G = Guidance, S = Student.

5. Logging In (Email or LRN)

The single login form at /login accepts either input format:

• Staff (super admin, teacher, adviser, registrar, guidance) — sign in with their school email address.
• Students — sign in with their 12-digit LRN (no @ symbol). The system auto-detects by counting digits.

Lockout kicks in after 5 wrong attempts (15-minute cooldown). First-time users are asked to change their password.

6. Super Admin Guide

The Super Administrator has unrestricted access. Only one or two people should hold this role. The account is created during the one-time /setup flow and can never be demoted or deleted through the UI.

6.1 First-run setup (one-time)

1. Immediately after deploy, visit /setup on the server's URL.
2. Enter your name, email, and a strong password (minimum 12 chars, mixed case + digit). This becomes the super_admin account.
3. On submit, the setup endpoint is locked and cannot be re-used — a 404 is served on any subsequent hit.
4. Log in, go to Settings → School, and fill the school name, School ID, division, region, district, principal name, and address. These values flow into SF1, SF9, SF10, and the Enrollment Slip headers.

6.2 Managing teachers

• Admin → Teachers lists every staff account with search.
• Click + New teacher to add one by hand: employee ID, name, email, position. The system auto-creates a login account with the initial password = the employee ID (forced change on first sign-in).
• Bulk import via the Import CSV button. Template: employee_id, last_name, first_name, middle_name, email, position, role. Duplicates are skipped; errors are reported per-row.
• Edit / archive teacher via the row actions. Archived teachers keep their historical grade records but can no longer sign in.

6.3 Managing students (admin-only operations)

• Day-to-day enrollment is now adviser-driven — the adviser captures SF1/BEEF fields during enrollment day (see the Class Adviser Guide below). The admin only handles the irreversible operations:
  • Delete a student record (soft-delete; recoverable by direct DB access).
  • Change an LRN (reshapes the student's login username).
  • Cross-section transfer (move a student between sections mid-year).
  • Re-enrol a former student into a new SY / semester.
  • Reset a student's password (issues a new one with the forced-change flag).
• Bulk import via Admin → Students → Import CSV. Template: lrn, last_name, first_name, middle_name, sex, date_of_birth, religion, address, phone, email, guardian_name, guardian_contact, section_code. Each imported student gets a generated password shown on the import result page (download as CSV for distribution).

6.4 Managing sections, subjects, strands, subject assignments

1. Strands — create one per DepEd track you offer (HUMSS, ABM, STEM, GAS, TVL, Sports, Arts). Fill code + name.
2. Subjects — create each subject with code, title, units, and which strand(s) it belongs to. Core subjects are shared across strands; specialized subjects are per-strand.
3. Sections — one row per class section (e.g. SEC-01, HUMSS 1 - 11 (Charity)). Assign grade level (11 / 12), strand, capacity, and the adviser (a teacher account). A teacher can adviser only one section per SY.
4. Subject Assignments — for each section × subject, pick the subject teacher. This controls who sees which class in the Teacher portal.

6.5 School Year lifecycle

• Only one SY is active at a time. The active SY is the one advisers/teachers work against.
• Admin → Settings → School Year lets you create a new SY, mark it active, or close the current SY.
• Year rollover: run the End-of-Year flow first (see §6.7), then close the SY and create + activate the next one.

6.6 Feature locks (audit season)

• Toggle per-feature locks under Settings → Feature Locks: sf9, esf10, grades, attendance, values.
• When ON, the matching feature returns 403 for everyone except super_admin — used during DepEd audit / ranking periods when records must stay frozen.
• Activity logs capture each lock toggle with timestamp + user.

6.7 End-of-year + Year Rollover

1. Go to Admin → End of Year.
2. Run the Promotion / Retention calculation — the system applies DepEd rules (all subjects ≥ 75 = Promoted; 1–2 subjects < 75 = Conditionally Promoted; 3+ < 75 = Retained). Review the per-student verdicts and override individual cases if the adviser/registrar has evidence (e.g. successful remedial).
3. Lock in the verdicts — this freezes the SY's records.
4. Run the Honor Roll — applies DO 36, s. 2016 (With Highest Honors ≥ 98, With High Honors ≥ 95, With Honors ≥ 90; all subjects ≥ 75).
5. Create the next SY under Settings → School Year, mark it active, then close the previous one.
6. Advisers enrol returning G11 → G12 students (Grade 12 section assignment is an admin action because it crosses grade levels).

6.8 Activity logs (audit trail)

• Admin → Activity Logs shows an append-only record of every significant action: logins, logouts, student create/update, credentials generated, feature lock toggles, grade finalizations, IIF saves.
• Each row has timestamp, user, action, resource, details (JSON), ip_address, user_agent.
• Retention: 12+ months. No DELETE is possible via the UI — an append-only trigger enforces it at the DB level.

6.9 Lost password / credential reset

• Student lost their temp password and the adviser's 5-minute reveal window expired: go to Admin → Students, find the student, click Reset Password. A new 12-char password is generated and shown once in a yellow banner; hand it to the adviser to deliver.
• Staff lost their password: Admin → Teachers → Reset Password. Same pattern.
• Super admin lost their own password: no UI path — connect to the DB host and run the recovery SQL in docs/ADMIN_RUNBOOK.md §7.

7. Subject Teacher Guide

Only for teachers with one or more subject assignments. If you are ALSO a class adviser, use the Switch Portal link in the sidebar to reach the Adviser Portal.

Encoding grades

1. Go to My Classes → click a class to open the grade-entry page.
2. Both quarters are shown side-by-side with a live-computed Sem Avg column. Compute each student's quarter-final grade in your official e-class record, then type the whole number (60–100) into the Q1 (or Q2) input.
3. As soon as both quarters are encoded, the Sem Avg and a Remarks descriptor (Outstanding / Very Satisfactory / Satisfactory / Fairly Satisfactory / Did Not Meet Expectations) appear automatically.
4. Click Save grades. Out-of-range values are rejected with a flash message; in-range values save immediately.
5. When every student has the active-quarter grade encoded, click Submit Q#. That quarter becomes read-only and the Teacher Progress monitor flags the class as Finalized.

Quarter icons

• 🔒 — the quarter has been submitted, OR the administrator has applied a feature lock.
• ⏳ — the quarter is not the active one yet.
• No icon — open for editing.

8. Class Adviser Guide

Use the Adviser Portal (/adviser). If you are also a subject teacher, the sidebar shows a "Switch Portal" link to jump to /teacher for grade entry.

8.1 Advisory roster

• Landing page shows your section's students with quick ✏️ Edit · Slip · SF9 · SF10 · IIF buttons per row (same tab — use the browser back button to return, or Ctrl+click for a new tab).
• Use the search box at the top to jump to a student by LRN or name.
• The 🖨 SF1 Register quick action prints the full section register (all learners, sorted by sex then last name).

8.2 Enrolling a new student (SF1 + BEEF)

This replaces the old bulk-import-only workflow. The adviser now encodes each new student during enrollment day with the official SF1 field set.

1. The student (or parent) arrives at your room with their 12-digit LRN (verify on DepEd LIS if unsure). Go to ➕ Enroll student.
2. Fill the Learner Information block:
   • LRN (12 digits, auto-grouped as you type)
   • Last / First / Middle name + Extension (Jr. / III). Title-case is applied on blur; compound surnames and Spanish particles (de, dela, del) format correctly.
   • Sex, Date of Birth, Place of Birth, Mother Tongue, Religion.
3. Fill the Current Address block: House No., Sitio/Street, Barangay, Municipality, Province, ZIP. Province and Municipality have typeahead from section history (sticks across enrollments in the same sitting).
4. Fill the Contact, Father's Name, and Mother's Maiden Name blocks. Tick Deceased next to either parent if applicable — this tag appears on the Enrollment Slip and adviser-facing IIF print, but NOT on the student's own IIF form (student answers "Yumao na?" independently) and NOT on the DepEd SF1 copy.
5. Tick Legal Guardian different from parents only if needed (e.g. lives with uncle/aunt/grandparent). Use the Same as Father / Same as Mother quick-copy if convenient.
6. Pick the Learning Modality: Face to Face (default), Modular, Blended, or Online.
7. Tick any SF1 Remarks codes that apply:
   • T/O Transferred Out → reveals receiving school + last-attendance date
   • T/I Transferred In → reveals first-attendance date (previous school goes in Balik-Aral)
   • CCT 4Ps/CCT recipient → reveals control/reference number + effectivity
   • B/A Balik-Aral → reveals last school + grade + SY
   • SNED Special Needs Education → reveals exceptionality
   • ACL Accelerated → reveals level + effectivity
8. Click Enroll student. The server saves the profile, creates the matching user account, and generates a 12-character random password.
9. The Enrolled success page shows the Username (LRN) and Temporary password in a yellow box. You have 5 minutes to either write it down or click Open printable Enrollment Slip to print a hardcopy with the password baked in. After 5 minutes or a page reload, the password is gone forever — admin would have to reset.
10. Hand the printed Enrollment Slip to the student + parent for signatures.

8.3 Editing an existing advisee

• Click the ✏️ button on any row to correct identity, contact, address, parent, guardian, or SF1 remark details. All fields except LRN, section, and grade level are editable.
• Changing an LRN is a super-admin action (it reshapes the login username).
• Re-enrolment across semesters, cross-section transfers, and deletion are also super-admin-only.

8.4 Printing the Enrollment Slip

• Per-row Slip button on the advisory roster opens the printable A4/Folio-portrait slip with student profile, parent/guardian block, signature lines (Student / Parent / Adviser), and a dashed credentials box.
• If the Slip is opened within 5 minutes of enrollment, the temp password is printed automatically. After the window expires the credentials box shows a blank line for hand-writing (or instructions to request an admin reset).
• Use the browser Print / Save as PDF dialog. Paper is Long Bond (Folio) 8.5 × 13" portrait.

8.5 Printing the SF1 School Register

• 🖨 SF1 Register quick-action on the advisory page renders the DepEd-standard School Form 1 for your section:
  • DepEd seal + official title + DepEd text banner
  • Full header grid (School Name, ID, District, Division, Region, Semester, SY, Grade Level, Track/Strand, Section)
  • Data table sorted by sex (M first, F second), name ascending
  • TOTAL MALE / TOTAL FEMALE / COMBINED subtotal rows in the standard <=== TOTAL X format
  • REMARKS legend (T/O, T/I, CCT, B/A, SNED, ACL) with required info
  • REGISTERED table (M/F/Total × Beginning/End of Semester)
  • "Prepared by;" with your signature line + beginning/end semester date boxes
• Paper: Long Bond (Folio) 8.5 × 13" landscape.

8.6 Attendance

• Go to Attendance in the adviser sidebar.
• Set school-day count per month (Jun → Mar, 10 months) — this stays the same for every student in the section.
• Record days absent per student per month. Absent counts auto-clamp to the school-day max.
• Months without a saved row render blank on the SF9 (not zero) so an unfinished attendance register doesn't look like "perfect attendance".

8.7 Observed Values

• Rate each DepEd core value (AO = Always Observed, SO = Sometimes Observed, RO = Rarely Observed, NO = Not Observed) for each student per quarter.
• Data appears on the printed SF9 (page 2) and SF10.

8.8 Class Grade Summary

• Summary — general-average grid (students × subjects) with Pending / Passed / Failed remarks. Hidden until every subject has both semesters encoded (so no misleading verdicts on partial data). Print button.
• Per Subject — one row per subject with a Print button that opens a DepEd-style class record (Q1, Q2, Sem Avg × 2 sems, Final, Remarks) for every student in the section.

8.9 Printing SF9 / SF10 / IIF

• Per-row buttons on the advisory roster. Each opens in the same tab.
• Use the browser's Print / Save as PDF dialog.
• If feature locks are on (set by the super admin for audit season), the button returns a 403 — contact the admin.

9. Registrar Guide

• Go to Students — searchable list of every enrolled and former student.
• Click a student to see their profile, then use SF9, SF10, or E-Card buttons to generate the form.
• Use the browser Print function (Ctrl+P / Cmd+P) to print or save as PDF.
• Feature locks apply to the registrar too (but not to the super admin).

10. Guidance Counsellor Guide

• Students — full list, searchable. Each links to the student's IIF.
• The IIF view shows every section the student filled: ID photo, personal info, family, household (assets + marital status), siblings, academic, health, and a red-bordered Confidential Psychosocial card.
• If the student pinned their home on OpenStreetMap, a static map image is embedded (with a link to open in OpenStreetMap).
• A Counselling Notes form at the bottom lets you add dated notes with categories (Academic, Behavioral, Personal, Referral, Follow-up, Other). Mark sensitive notes Confidential.
• The Print IIF button (top-right) generates the A4-portrait DepEd-style form for the student's permanent record.

11. Student Guide

First login

1. Your adviser handed you an Enrollment Slip at enrollment day. It has your 12-digit LRN (this is your username) and a temporary password.
2. Go to /login. Type the LRN in the identifier field — the system auto-detects it as a student login (no @ symbol, no @aenhs.local). Type the temporary password and click Sign in.
3. You'll be redirected to Change initial password. Pick a new password (minimum 12 characters, with mixed case + a digit). Confirm it.
4. After the change, you'll land on the Individual Inventory Form — fill it out fully before any other page (dashboard, grades, etc.) unlocks. The form is pre-filled with the BEEF fields your adviser entered; review and complete the remaining sections.

Lost your temp password? Ask the adviser — if it's within 5 minutes of enrollment, they can still reveal it. Otherwise the admin will reset it for you (you'll get a new temp password with the same forced-change flow).

Filling the IIF

1. 📸 Larawan (ID Photo) — click the dashed tile or drag-and-drop a JPG / PNG / WEBP (max 10 MB). The image becomes your profile photo AND the photo printed on your IIF.
2. Impormasyong Personal — date of birth, contact number, height/weight, religion, dialect, complete address.
3. Lokasyon ng Tahanan (Map pin) — type your address into the textbox, click "Find on map", then fine-tune by clicking/dragging the pin on the map (OpenStreetMap).
4. Pamilya + Tagapag-alaga — father, mother (tick "Yumao na" if deceased), guardian, marital status, extended family info.
5. Mga Magkakapatid — up to 9 siblings.
6. Tahanan — household assets, house material, occupants, who supports your studies.
7. Akademiko / Pangkalusugan / Kompidensyal — subjects you find easy/hard, plans after SHS, health history, any abuse/problems (kept confidential).
8. Click Save form — you'll land on your dashboard.

What you can do afterwards

• Dashboard — current enrollment, general average, honor status.
• My Grades — all subjects with Q1/Q2 grades, sem average, descriptor.
• Report Card (E-Card) — print-ready report card (Ctrl+P).
• Attendance — month-by-month record.
• IIF Form — come back anytime to update your info or replace your photo.
• My Profile — change password or remove your profile pic (this does NOT blank your IIF photo — the two are tracked independently).

12. DepEd Compliance Notes

Grading (DO 8, s. 2015)

Quarter grades follow the DepEd 3-component formula (Written Work / Performance Task / Quarterly Assessment with category-specific weights) and Appendix B transmutation. In v1.2.0 the teacher computes this in their official e-class record and encodes the transmuted final directly into the system — we no longer duplicate the weighting math here. This matches DepEd memorandum practice of keeping the class record as the authoritative artifact.

Descriptors (DO 8, Table 6)

• 90–100: Outstanding
• 85–89: Very Satisfactory
• 80–84: Satisfactory
• 75–79: Fairly Satisfactory
• 60–74: Did Not Meet Expectations

Passing grade: 75.

Honors (DO 36, s. 2016)

• With Highest Honors: General Average ≥ 98, all subjects ≥ 75
• With High Honors: General Average ≥ 95, all subjects ≥ 75
• With Honors: General Average ≥ 90, all subjects ≥ 75

Promotion rules

• All subjects ≥ 75 → Promoted (or Graduated for G12)
• 1–2 subjects < 75 → Conditionally Promoted (requires remediation)
• 3+ subjects < 75 → Retained

13. Backup & Disaster Recovery

Admin-scope. These procedures protect the school's data against hardware failure, accidental deletion, ransomware, and migration errors. The global policy is daily automated backups with weekly automated restore verification — both are already wired into the repository.

13.1 Policy

• Frequency: nightly, 02:15 Asia/Manila (via cron).
• Retention tiers:
  • Daily: 7 rolling days
  • Weekly: 4 Sundays (one snapshot per week)
  • Monthly: 12 months (one snapshot on the 1st)
• Restore verification: every Monday 03:00 a throwaway Postgres container restores the newest daily backup and sanity-checks it. Cron mail surfaces any failure.
• Off-site: copy /home/richard/backups/anhs/ to a separate host (NAS / remote rsync) at least weekly. The sample cron snippet in docs/ADMIN_RUNBOOK.md includes an optional rsync line to a NAS.

13.2 What each backup contains

Each backup is a single .tar.gz bundle containing:

• db.sql.gz — gzipped pg_dump of the entire database (every student, grade, attendance, IIF answer, audit log, settings row).
• uploads/ — verbatim copy of every user-uploaded file (student profile photos under avatars/, IIF photos under iif-photos/).
• MANIFEST.txt — human-readable inventory + restore instructions you can read with any text editor.

What's not in the bundle: the .env file (DB password, app secrets) — back that up separately and store it offline. Application code + Docker images come from git + the registry, so a fresh docker compose up rebuilds them.

13.3 Scripts in the repo

• scripts/backup-db.sh — runs pg_dump against the compose db service, copies storage/uploads/ alongside, writes a single .tar.gz bundle to the daily tier, promotes to weekly on Sundays and monthly on the 1st, then prunes each tier to its retention cap. Idempotent; fails loudly.
• scripts/restore-test.sh — starts a fresh postgres:16-alpine container named anhs-restore-verify, extracts the newest bundle, restores db.sql.gz into it, and queries schema_migrations for a non-empty result. Cleans up on exit.

13.4 Installing the cron jobs (one-time)

On the prod host, run crontab -e and add:

# Daily backup at 02:15
15 2 * * *  cd /home/richard/docker-apps/active/anhsinfosys && bash scripts/backup-db.sh >> /home/richard/backups/anhs/backup.log 2>&1

# Weekly restore verification at 03:00 every Monday
0 3 * * 1   cd /home/richard/docker-apps/active/anhsinfosys && bash scripts/restore-test.sh >> /home/richard/backups/anhs/restore-test.log 2>&1

13.5 Running a one-off backup

cd /home/richard/docker-apps/active/anhsinfosys
bash scripts/backup-db.sh

Tails to stdout. Successful output looks like:

[2026-04-15T02:15:00+08:00] Starting pg_dump for anhs@db
[2026-04-15T02:15:03+08:00] Wrote 142K → /app/storage/backups/anhs/daily/anhs-2026-04-15_021500.tar.gz  (uploads: 84 files)
[2026-04-15T02:15:03+08:00] Backup complete.

13.6 Verifying a backup is restorable

bash scripts/restore-test.sh

Exit code 0 = PASS, 1 = no backup found, 2 = unusable dump (schema_migrations empty). Safe to run any time — uses a throwaway container and never touches the live DB.

13.7 Restoring from a backup (destructive)

⚠ This overwrites both the live database AND the uploaded files. Notify staff first and take a fresh manual backup before restoring.

# 1. Take a safety snapshot first
bash scripts/backup-db.sh

# 2. Stop the app so no writes happen during restore
docker compose stop app web

# 3. Extract the chosen bundle into a temp dir
mkdir /tmp/anhs-restore && cd /tmp/anhs-restore
tar -xzf /home/richard/docker-apps/active/anhsinfosys/storage/backups/anhs/daily/anhs-YYYY-MM-DD_HHMMSS.tar.gz

# 4. Restore the database
gunzip -c db.sql.gz \
  | docker compose -f /home/richard/docker-apps/active/anhsinfosys/docker-compose.yml exec -T db psql -U anhs -d anhs

# 5. Restore the uploaded files (avatars + IIF photos)
rsync -a uploads/ /home/richard/docker-apps/active/anhsinfosys/storage/uploads/

# 6. Bring the app back
cd /home/richard/docker-apps/active/anhsinfosys
docker compose start app web

# 7. Smoke-test
curl -fsS https://aenhsinfosys.downstreamtech.net/health

Each bundle's MANIFEST.txt contains the exact restore commands — open it with any text editor before you run anything destructive.

13.8 Recovery priorities

• RPO (max data loss acceptable): 24 hours — the gap between nightly backups.
• RTO (max downtime acceptable): 1 hour — time to restore the newest backup and bring the stack back.
• For tighter RPOs, enable Postgres WAL archiving (see ADMIN_RUNBOOK §8) — optional, not yet wired by default.

Credits

AENS InfoSys was conceptualized and researched by Gina S. Rosal, MSIT of Aparri East National High School as her successfully-defended graduate-thesis research project, addressing the school's need for a DepEd-compliant Senior High School Student Information System. The requirements, the DepEd form templates (SF9, SF10, IIF), and the day-to-day workflow it automates all come from her direct experience as a teacher and designated school administrator.

Thesis Adviser: Richard R. Ayuyang, PhD — Professor II, Cagayan State University · chadlinuxtech.net

Design, development, and long-term maintenance: DownStreamTech · downstreamtech.net