Software Requirements Specification
Neemias
1. Introduction
This document defines the functional and non-functional requirements for Neemias. The system is a backend-primary, browser-based attendance application with offline resilience, role-based access control, and LGPD and WCAG Level AA requirements.
2. System Overview
The system shall support a small number of concurrent users in a mobile and desktop browser environment. It shall be designed as a modular progressive web app with cloud synchronization.
3. Definitions
| Term | Meaning |
|---|---|
| Student | A person whose attendance is tracked. |
| Attendance action | A mark of present, absent, or another future attendance state. |
| Admin action | Any action performed by an admin user that overrides lower-privilege conflicting actions. |
| Backend-primary | The app works against the Cloudflare Worker backend; falls back to local SQLite WASM (OPFS) when offline. |
| Sync | The process of reconciling local changes with the server when connectivity returns. |
4. User Roles and Access Control
| Requirement ID | Requirement |
|---|---|
| FR-001 | The system shall support the roles ADMIN, CHAMADOR, RELATORIOS, CADASTRO, RESPONSAVEL, VOLUNTARIO, COORDENACAO_KIDS, and ADMINISTRATIVO_KIDS (8+ roles). |
| FR-001-A | The system shall support multi-role assignment — users can hold multiple roles simultaneously via a user_roles join table. (v0.56.0+) |
| FR-001-B | The system shall resolve AuthPrincipal.roles[] with a primaryRole for display, using an explicit role hierarchy. (v0.56.0+) |
| FR-001-C | requireRole() shall use any() match — the user passes if at least one role matches the allowed list. (v0.56.0+) |
| FR-001-D | Scope resolution for multi-role users shall produce a compound union (most permissive across roles). Sanitization shall apply most-restrictive across roles. (v0.56.0+) |
| FR-002 | The system shall enforce least privilege for all role actions. |
| FR-003 | The system shall allow Roll-caller users to search students and mark attendance. |
| FR-004 | The system shall allow Report user accounts to view reports only. |
| FR-005 | The system shall allow Data entry users to add students. |
| FR-006 | The system shall allow Admin users to access reports, mark attendance, add students, edit students, and remove students. |
| FR-007 | The system shall require a justification text field before any student removal is accepted. |
| FR-008 | The system shall reject unauthorized actions with a clear failure state and an auditable record. |
| FR-NEW-01 | The system shall allow ADMIN_USER to view all users with name, username, role, and status. |
| FR-NEW-02 | The system shall allow ADMIN_USER to create users with unique username (3 to 50 chars, /^[a-z0-9-]+$/), displayName (1 to 100 chars), role, and password (minimum 8 chars). |
| FR-NEW-03 | The system shall allow ADMIN_USER to edit any user's displayName and role. |
| FR-NEW-04 | The system shall allow ADMIN_USER to reset any user's password. |
| FR-NEW-05 | The system shall allow ADMIN_USER to deactivate users; deactivated users cannot log in. |
| FR-NEW-06 | The system shall block self-deactivation. |
| FR-NEW-07 | The system shall block deactivation of the last active ADMIN_USER. |
| FR-NEW-09 | The system shall implement PBKDF2-600k password hashing for local authentication. (v0.53.0+) |
| FR-NEW-10 | The system shall enforce login lockout with exponential backoff (5s→30s) after consecutive failures, and hard lockout after 10 failures (15min). (v0.53.0+) |
| FR-NEW-11 | The system shall implement Content Security Policy via a static hash-based CSP generated into app/public/_headers at build time. (v0.55.0+) |
| FR-NEW-12 | The system shall use EntityRepository pattern (D1EntityRepo + MemoryEntityRepo) for data access in the Worker layer. (v0.54.0+) |
| FR-NEW-13 | The system shall support runtime theme switching via data-theme attribute with 4 built-in themes (light, warm, dark, ijcp). (v0.54.0+) |
| FR-NEW-14 | The system shall provide an OnlineProxy storage adapter that delegates reads/writes through the Worker API when the backend is reachable. (v0.53.0+) |
| FR-NEW-15 | The system shall write immutable UserEvent records for all user management actions. |
5. Functional Requirements
| Requirement ID | Requirement |
|---|---|
| FR-010 | The system shall allow users to search for students by name and other configured identifiers. |
| FR-011 | The system shall display the student photo immediately when a matching result is shown. |
| FR-012 | The system shall support recording attendance for a student in a small number of steps. |
| FR-013 | The system shall preserve a history of student-related actions and attendance actions. |
| FR-014 | The system shall support offline creation of actions and defer sync until connectivity returns. |
| FR-015 | The system shall reconcile conflicting actions according to admin precedence, where admin actions supersede lower-privilege actions. |
| FR-016 | The system shall retain unsynced offline actions if the user session expires while offline. |
| FR-017 | The system shall require re-authentication before submitting actions after session expiry. |
| FR-018 | The system shall support future feature modules such as new reports without requiring a major redesign. |
| FR-019 | The system shall default all user-facing text to Brazilian Portuguese. |
| FR-020 | The system shall provide an architecture that allows additional languages to be added later. |
| FR-021 | The system shall provide visual and auditory feedback for successful and failed actions. |
| FR-022 | The system shall provide a double-check step or equivalent verification before committing user-visible changes. |
| FR-023 | The system shall present student lists in alphabetical order by localized display name. |
| FR-024 | The system shall provide a student profile/details view that surfaces student identity, photo, and recent attendance state. |
6. Non-Functional Requirements
| Requirement ID | Requirement |
|---|---|
| NFR-001 | The system shall be accessible in accordance with WCAG Level AA. |
| NFR-002 | The system shall operate as a progressive web app in mobile and desktop browsers. |
| NFR-003 | The system shall be optimized for fast interaction and low perceived latency. |
| NFR-004 | The system shall use aggressive caching for static assets and frequently reused application resources. |
| NFR-005 | The system shall support offline operation for all essential attendance workflows. |
| NFR-006 | The system shall synchronize queued changes when internet connectivity returns. |
| NFR-007 | The system shall protect stored personal data using encryption suitable for browser storage (both backend-transit and local fallback). |
| NFR-008 | The system shall use security controls that support LGPD obligations where applicable. |
| NFR-009 | The system shall limit data access by role and by need-to-know. |
| NFR-010 | The system shall remain maintainable through modular boundaries that support future feature growth. |
| NFR-011 | The system shall support concurrent use by approximately 3 to 5 active users. |
| NFR-012 | The system shall persist user actions locally until they are confirmed as synchronized or explicitly rejected. |
7. Data Requirements
| Requirement ID | Requirement |
|---|---|
| DR-001 | Student records shall include at minimum a unique identifier, display name, and photo reference. |
| DR-002 | Attendance records shall include student reference, status, actor, timestamp, and synchronization state. |
| DR-003 | Deletion records shall include the deleting user, timestamp, and justification text. |
| DR-004 | The system shall maintain an audit trail of create, update, delete, and attendance events. |
| DR-005 | The system shall keep historical records sufficient for compliance review and operational review. |
| DR-NEW-01 | User records shall include user identity, role, status, passwordHash, and lifecycle timestamps. |
| DR-NEW-02 | User audit events shall be append-only and must not include passwordHash in change payload. |
8. Sync and Conflict Requirements
| Requirement ID | Requirement |
|---|---|
| SR-001 | The system shall queue offline changes locally until they can be synchronized. |
| SR-002 | The system shall apply server-side conflict resolution rules during synchronization. |
| SR-003 | The system shall treat admin actions as authoritative over lower-privilege conflicting actions. |
| SR-004 | The system shall preserve all conflicting events in history even when one event is superseded. |
| SR-005 | The system shall surface synchronization success and failure states clearly to the user. |
9. Security and Compliance Requirements
| Requirement ID | Requirement |
|---|---|
| SCR-001 | The system shall require authentication before a user can submit protected actions. |
| SCR-002 | The system shall require re-authentication after the session TTL expires. |
| SCR-003 | The system shall support offline-aware session handling for up to the configured session period. |
| SCR-004 | The system shall minimize retention of sensitive data on the device when the session is no longer valid for action submission. |
| SCR-005 | The system shall comply with LGPD requirements wherever applicable. |
| SCR-006 | The system shall implement access logging sufficient for accountability and auditing. |
| SCR-007 | The system shall treat student removal as a sensitive administrative action. |
| SCR-NEW-01 | The system shall hash passwords using SHA-256 via window.crypto.subtle and never persist plaintext passwords. |
10. Acceptance Notes
The implementation is considered aligned with this SRS only if all of the following remain true:
- Brazilian Portuguese is the default language.
- Admin actions win conflicts.
- Offline work is preserved and later synchronized.
- Student removal requires justification.
- Photos are shown immediately in search results.
- Accessibility and LGPD are treated as first-class requirements, not optional enhancements.
11. Open Architectural Decisions
| Topic | Requirement |
|---|---|
| Hosting | Must remain cloud-deployable without vendor lock-in assumptions. |
| Auth | Must support short-lived sessions with re-authentication after expiry. |
| Storage | Must support local IndexedDB fallback appropriate for offline operation when the backend is unreachable. |
| Encryption | Must rely on browser-compatible, standards-based crypto where possible. |
| Language expansion | Must support additional locales through modular resource files. |