# Advisor Assessment — Post-MVP Sprint (F006—F009) & MVP Demo Readiness **Date:** 2026-05-28 **Advisor:** Principal SME — Educational Software & Attendance Systems **Scope:** Domain audit of post-MVP sprint (F006-F009) and MVP demo readiness assessment --- ## Executive Summary The post-MVP sprint added 5 significant feature areas to the system. From a domain perspective, the system has evolved from "functional but rough" to **"demo-ready with minor caveats"**. The critical path coverage is strong; remaining gaps are primarily in reporting depth and edge-case polish, not core attendance workflow. **Provisional Verdict:** DOMAIN_VALIDATED — MVP demo is viable with the caveats documented below. --- ## Sprint Audit: New Features (F006—F009) ### F006a — Hide Sat/Sun in Schedule Grid ✅ **Domain verdict:** Correct. Venezuelan school weeks run Monday–Friday. Showing Saturday/Sunday in the default schedule view added visual noise. The configurable toggle ("Mostrar fin de semana") is appropriate since some schools have Saturday extracurricular activities. ### F006b — Holiday Calendar ✅ **Model:** `Holiday(id, account_id, name, date, type)` with `national/school/vacation` enum **Blocking logic:** `is_holiday()` utility blocks attendance creation at endpoint level **Domain verdict:** CORRECT with a nuance: - **Endpoint-level blocking** is pragmatic and verifiable. Each attendance-creation path explicitly calls `is_holiday()`. - **Coverage is thorough** — checkin, self-checkin, teacher swipe, batch-toggle, toggle, facial recognize, facial checkout, facial self — all blocked. - **Account isolation** via `account_id` ensures schools don't see each other's holidays. - **⚠️ Caveat:** Holiday blocking only prevents *new* attendance creation. If a holiday is added retroactively, existing attendance records for that date remain. This is acceptable for MVP since admins would typically configure holidays before the school year starts. ### F006.1 — Section Capacity Enforcement ✅ **Domain verdict:** Correct. The `_section_at_capacity()` helper is clean: `COUNT(enrollments) >= Section.max_students`. Returns 409 for single enrollment, skips with message for bulk. This is the expected real-world behavior — a teacher cannot have 45 students in a classroom designed for 40. ### F007a — Password Reset (Admin-Generated Token) ✅ **Flow:** Admin clicks "Reset Password" → system generates `secrets.token_urlsafe(32)` → token shown in modal with copy button → user visits `/reset-password` → enters token + new password → `must_change_password` flag cleared on success **Domain verdict:** HIGHLY CORRECT for Venezuelan schools: - **No email dependency** is the right call — many public schools lack institutional email or reliable internet for password reset emails. - **Admin-generated token** shown in UI is practical: the admin can tell the user the token verbally, write it on a note, or print it. - **`must_change_password` flag** ensures first login after reset forces a password change. - **Token expiry (24h)** prevents stale tokens from being exploited. - **Minimum 6-char validation** is reasonable for a school system (avoids forcing complex passwords that students will forget). ### F007b — Audit Log Viewer ✅ **Domain verdict:** Correct. Paginated, filterable audit trail is essential for school compliance. Schools in regulated environments (e.g., Fe y Alegría network, state-funded schools) often require audit logs for attendance record-keeping. The expandable JSON detail view is particularly useful for investigating specific actions. ### F008 — Role Workflows & Late Analytics ✅ **Domain verdict:** CORRECT with observation: - **Late arrival analytics** (`RETRASO:` / `SALIDA TEMPRANA:` in `note` column) is pragmatic — uses existing data without schema changes. The `LIKE` pattern is straightforward. - **⚠️ Caveat:** Late/early data quality depends on teachers actually writing the note prefix correctly. No enforcement mechanism exists for the `RETRASO:` / `SALIDA TEMPRANA:` prefix convention. This is acceptable for MVP but should be documented in training materials. - **Administrativo role** gaining student/section/report access is correct — this matches the "school secretary" role in Venezuelan schools who manages enrollment records. - **Obrero role** (gate/general staff) getting check-in access is correct. ### F009a — Documentation ✅ **Domain verdict:** Correct. `CHECKPOINTS.md`, `docs/architecture.md`, and `docs/conventions.md` provide the minimum viable documentation for handover and maintenance. ### F009b — Core Business Logic Tests ✅ **Coverage:** 12 tests in `tests/test_business.py` covering holiday isolation, section capacity, attendance counting, password validation **Domain verdict:** Acceptable for MVP. Tests cover the critical business invariants: - Holiday dates block attendance (account-scoped) - Section capacity prevents over-enrollment - Present/absent counting is correct - Password minimum length validation --- ## MVP Demo Readiness Assessment ### Scoring | Criteria | Score | Notes | |----------|-------|-------| | Core attendance flow | ✅ | Check-in, check-out, teacher swipe, facial all work | | Role-based access | ✅ | Admin, teacher, representative, administrativo, obrero | | Student management | ✅ | CRUD, import, card assignment | | Section/class management | ✅ | With capacity enforcement | | Enrollment | ✅ | Multi-section, duplicate-protected, capacity-enforced | | Schedule | ✅ | Weekly grid with weekday toggle | | Holiday calendar | ✅ | Blocking attendance on holidays | | Password reset | ✅ | Admin-generated token flow complete | | Late analytics | ✅ | Data + visual report page | | Audit log | ✅ | Viewable and filterable | | Representative portal | ✅ | "Mis Hijos" page with attendance and schedule | | Facial recognition | ✅ | Enrollment, recognition, checkout | | Spanish UI | ✅ | All labels in Spanish | | Documentation | ✅ | CHECKPOINTS, architecture, conventions | ### Gap Analysis (What a Client Would Notice) #### Moderate Gaps (should address before serious demo) 1. **No academic year separation** — Data from different school years is mixed. A client might ask "how do I start a new school year?" — we don't have a clean answer beyond manual section management. 2. **No student attendance report by section** — The late arrivals report is useful, but there's no "attendance rate by section" or "daily attendance summary" report that a school director would expect. #### Minor Gaps (acceptable for initial demo) 3. **No email/SMS notifications** — Schools will eventually want automated parent notifications for absences. Acceptable to defer. 4. **No mobile app** — The web app is mobile-responsive but not a dedicated mobile experience. Acceptable for MVP. 5. **No QR code check-in** — Some schools use QR codes at entrances. Not a blocker. 6. **No bulk holiday import** — Holidays must be added one by one. Minor UI inconvenience. #### Strengths for Demo 1. **Password reset flow** — This was the #1 question schools asked. Now solved without email. 2. **Holiday blocking** — "See, if it's a national holiday, the system simply won't let anyone check in." 3. **Late arrival tracking** — "We can tell which students are habitually late, by section." 4. **Multi-section enrollment** — "Ana can be in both 5to A English and 5to B Math." 5. **Representative access** — "Parents can see their children's attendance from home." --- ## Recommended Demo Script (Domain-Focused) 1. **Login as admin** → show dashboard → show users by role 2. **Create a student** → assign card → enroll in section 3. **Show schedule** → toggle weekend → show holiday 4. **Create a holiday** (e.g., "24 de Diciembre") → try to check in → see 409 block 5. **Teacher check-in flow** → swipe student → show attendance record 6. **Late arrival** → check in with "RETRASO: 15 min" → show late arrivals report 7. **Password reset** → admin generates token → show copy → user resets password 8. **Login as representative** → show "Mis Hijos" → attendance cards, schedule 9. **Audit log** → show all actions tracked, filter by user 10. **Capacity enforcement** → try to enroll 41st student → see error --- ## Risks & Remediation | Risk | Impact | Mitigation | Timeline | |------|--------|------------|----------| | Client asks about school year separation | Medium | Prepare verbal answer: "currently sections can be archived, academic year field is a future enhancement" | Pre-demo prep | | Client asks about attendance reports by section | Medium | Point to late arrivals + student reports; explain reporting dashboard is in roadmap | Pre-demo prep | | Facial recognition accuracy in poor lighting | Low | Configure camera settings; have manual check-in as fallback | Already handled | | Client wants bulk holiday import | Low | Show single-create, mention CSV import can be added | Pre-demo Q&A prep | --- ## Final Verdict **DOMAIN_VALIDATED** — The post-MVP sprint (F006—F009) correctly implements the business requirements. The system is **ready for an MVP demo with a potential client** given the documented caveats. The core attendance workflow is complete, role-based access covers all defined roles, and the new features (password reset, holiday calendar, capacity enforcement, late analytics, audit log) address the most common client demo questions. **Recommended focus for demo day:** Prepare verbal answers for the two moderate gaps (academic year separation, section-level attendance reports) and lead with the password reset flow and holiday blocking as key differentiators.