Product Requirements Document
Neemias
1. Purpose
Neemias is an attendance application for small teams and school-like environments that need fast, reliable presence tracking for 3 to 5 concurrent users. The product is designed as a progressive web app that works in mobile and desktop browsers, can operate offline, and syncs changes when connectivity returns.
This document is the product-level source of truth. It defines the problem, the intended users, the product boundaries, and the business rules that must not be violated by implementation choices.
2. Product Vision
The product must make attendance tracking extremely simple for non-technical users while remaining safe, auditable, and easy to extend.
The system must:
- Default to Brazilian Portuguese for all users.
- Allow additional languages to be added later without redesigning the application.
- Remain modular so future features such as reports, workflows, and student management can be added cleanly.
- Support offline usage without losing user actions.
- Prioritize accessibility and immediate visual feedback.
- Enforce least privilege and LGPD requirements.
3. Problem Statement
Current attendance workflows are often slow, error-prone, and difficult for non-technical users. The product must reduce friction at the point of attendance capture, while also protecting personal data and preserving a reliable history of changes.
4. Target Users
| Role | Primary Need | Typical Access |
|---|---|---|
| Admin (ADMIN) | Manage students, attendance, reports, users, and settings | Full operational access |
| Chamador (CHAMADOR) | Mark present and absent quickly | Attendance only |
| Relatórios (RELATORIOS) | Review attendance reports | Reports only |
| Cadastro (CADASTRO) | Add students and maintain student records | Student creation, classes, nuclei |
| Responsável (RESPONSAVEL) | View own children's records | Read-only own students |
| Voluntário (VOLUNTARIO) | Support classroom activities | Limited student read, session view |
| Coordenação Kids (COORDENACAO_KIDS) | Manage kids ministry operations | Reports, student read, sessions |
| Administrativo Kids (ADMINISTRATIVO_KIDS) | Administrative support for kids ministry | Reports, student read |
5. Product Goals
| Goal | Description |
|---|---|
| Fast attendance capture | A user should be able to identify a student and record attendance with minimal steps. |
| Immediate recognition | Student photos must appear immediately during search to support visual identification. |
| Offline continuity | Users must continue working when the internet is unavailable. |
| Reliable sync | Changes made offline must sync safely when connectivity returns. |
| Simplicity | The interface must be easy for users with little software experience. |
| Accessibility | The experience must satisfy WCAG Level AA. |
| Compliance | The product must comply with LGPD wherever applicable. |
| Extensibility | The architecture must support future features without major redesign. |
6. Scope
In scope
- Attendance marking for present and absent states.
- Student creation and maintenance.
- Student directory browsing with alphabetical ordering and a profile/details view.
- Report access for authorized users (13 report types: attendance rate, audits, class engagement, risk dropout, sociodemographic, trends, etc.).
- Search with immediate photo visibility.
- Offline operation and later synchronization via SQLite/WASM local database.
- Audit history for student and attendance actions.
- Role-based access control with 8 system roles and 25 granular permissions.
- Dynamic custom role creation and management (CRUD API).
- Localization architecture with Brazilian Portuguese default.
- Deletion justification for admin-only student removal.
- Visual feedback for successful and failed actions.
- Admin-only user lifecycle management (create, update, reset password, deactivate).
- Import and export of student and class data.
- Public event registration for students and guardians.
- Student self-onboarding via invite links.
- Live capacity dashboard for class occupancy.
- TV/display overlay for notifications and announcements.
- Plugin system for extensible modules (nuclei, volunteers).
Out of scope for now
- Mobile app store distribution.
- Native applications.
- Complex enterprise identity integrations unless explicitly added later.
- Formal regulatory traceability matrix.
- Multi-organization tenancy unless introduced later.
7. Core Users and Permissions
| Action | CHAMADOR | RELATORIOS | CADASTRO | RESPONSAVEL | VOLUNTARIO | COORDENACAO_KIDS | ADMINISTRATIVO_KIDS | ADMIN |
|---|---|---|---|---|---|---|---|---|
| Mark attendance | Yes | No | No | No | No | No | No | Yes |
| View reports | No | Yes | No | No | No | Yes (consolidated) | Yes (consolidated) | Yes |
| Add students | No | No | Yes | No | No | No | No | Yes |
| Edit students | No | No | No | No | No | No | No | Yes |
| Delete students | No | No | No | No | No | No | No | Yes, with justification |
| View users | No | No | No | No | No | No | No | Yes |
| Create users | No | No | No | No | No | No | No | Yes |
| Edit users | No | No | No | No | No | No | No | Yes |
| Reset user password | No | No | No | No | No | No | No | Yes |
| Deactivate users | No | No | No | No | No | No | No | Yes, with safeguards |
| Search students | Yes | Yes | Yes | No | Yes (basic) | Yes (full) | Yes (full) | Yes |
| View student photo | Yes | Yes | Yes | No | Yes | Yes | Yes | Yes |
| View own students | No | No | No | Yes | No | No | No | Yes |
| Manage classes/nuclei | No | No | Yes | No | No | No | No | Yes |
| Manage volunteers | No | No | No | No | No | No | No | Yes |
| Import/export data | No | No | No | No | No | No | No | Yes |
| Manage settings | No | No | No | No | No | No | No | Yes |
| Create/edit sessions | No | No | Yes | No | Yes (view) | No | No | Yes |
8. Business Rules
- Admin actions supersede any conflicting lower-privilege actions.
- Student removal is admin-only and requires a justification text field.
- Student history and attendance history must be retained for audit purposes.
- The product must support least privilege wherever applicable.
- Any change to user-visible data must be double-checked before being committed.
- The product must remain usable offline and preserve unsynced work until sync can occur.
- Search results must surface student photos immediately to support identification.
- Student browsing should be predictable, with alphabetical ordering and a visible profile/details view for stakeholder review.
- User deactivation is soft only and never physically deletes user history.
- Self-deactivation is blocked.
- Deactivation of the last active Admin user is blocked.
- User management actions must always produce immutable audit events.
9. Architectural Decisions
All architectural decisions are documented as Architecture Decision Records in docs/architecture/adr/. Key topics include hosting strategy, authentication, encryption, database storage, and internationalization.
See ADR index for the full list.
10. Success Criteria
- A new user can understand the app purpose and roles from the documentation alone.
- Attendance can be recorded with minimal steps and clear feedback.
- Users can keep working when offline and sync later without losing actions.
- Admin-only deletion behavior is obvious and enforceable.
- The product remains small, modular, and contributor-friendly.