talos-access / progress /advisor_assessment.md
Greg
Claude Opus 4.7 (1M context)
Preparar despliegue en fly.io: monolito dockerizado + seeder demo
6aa6081
|
Raw History Blame Contribute Delete
9.76 kB

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)

  1. No email/SMS notifications β€” Schools will eventually want automated parent notifications for absences. Acceptable to defer.
  2. No mobile app β€” The web app is mobile-responsive but not a dedicated mobile experience. Acceptable for MVP.
  3. No QR code check-in β€” Some schools use QR codes at entrances. Not a blocker.
  4. 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.