ADR-0040: Derived Visitor Status — is_visitor from familyMembershipStatus

Status: accepted
Date: 2026-08-31
Deciders: @barateza
Tags: [student-profile, visitor-tracking, data-model, issue-151]

Context

Issue #151 (Ampliação do cadastro da criança) originally proposed a stored is_visitor boolean on students, described as "não-membro". The domain already models church membership: familyMembershipStatus (MEMBRO | NAO_MEMBRO | DESCONHECIDO), determined manually by the admin.

The SDD-151 grilling (2026-08-31) resolved two domain facts: (1) in the real church, becoming a member is a formal church-office process that happens outside Neemias — Neemias only manages the children's ministry, so "visitante" means "the child's family is not yet a registered member"; (2) membership determination is a manual admin update that every child eventually gets.

Options considered

(a) Store is_visitor as a boolean column. Two sources of truth for the same concept — the flag can drift out of sync with familyMembershipStatus (e.g., a member child still flagged is_visitor = true).

(b) Derive it: is_visitor := familyMembershipStatus !== "MEMBRO" (both NAO_MEMBRO and DESCONHECIDO count as visitor). One source of truth; a brand-new child (default DESCONHECIDO) is automatically tracked as a visitor until the admin updates the file.

(c) Derive from NAO_MEMBRO only. Leaves unknown-status children untracked until manually classified — a data-entry gap that loses visit counts.

Decision

Adopt (b). No is_visitor column. The only new visitor-related column on students is visitor_count (denormalized counter: incremented on MARK_PRESENT while is_visitor, reset on promotion). "Promotion" = the auto-flip of familyMembershipStatus to MEMBRO after promotion_visits visits (default 3), with admin notification and manual override both ways — see SDD-151.

Consequences

• A child whose family is DESCONHECIDO is tracked as a visitor by default — no data-entry step is needed to start counting visits.
• The promotion rule is a pure familyMembershipStatus transition; nothing can represent "member but still flagged visitor".
• visitor_count resets on promotion, so a demoted family restarts their count from zero.
• The UI renders the visitor state from the membership status control, not a separate checkbox (CAD-RQ-04).