Essiga lya Ggere

User Guide

A guide to every module of the application as shipped. It is organised by what you can do, grouped by the kind of user you are. A full Site Map with access levels is at the end.

Who's who — roles & access

Access is decided by two things: your site-wide status and your per-family membership role.

Site-wide

  • Visitor — not signed in. Sees only the public heritage portal.
  • Registered user — has an account; can be a member of one or more families.
  • Site admin (isAdmin) — manages the public site content and sees governance dashboards across all families.

Per-family membership role (you can have a different role in each family)

  • Viewer — can view the family tree and (if dues are enabled) the family's dues.
  • Contributor — can add people, but their additions are PENDING until approved.
  • Editor — can edit the tree, approve/reject contributions, extend the tree upward, confirm the founder.
  • Owner — everything an Editor can do, plus manage members/roles and configure the Trust.

Dues-specific hats (layered on top of your role)

  • Treasurer — records/voids payments and manages dues configuration.
  • Chairman / House head — can view the family's dues (a head sees the whole family, with an extra focus on their own house).

Convention: if you lack access to something, the app shows "Not found" (404) rather than "Forbidden" — this deliberately avoids revealing that a resource exists.

1. Public heritage portal

Who: anyone (no account needed) · Where: /, /news, /p/<slug>

  • / — Heritage home. The public landing page. Shows a live "By the numbers" band (generations, total members, houses, regions — counts only, no personal data), a "Where we are" places summary (aggregate residence/region counts), and the latest announcements. Which family is shown here is chosen by a site admin.
  • /news — Announcements feed. Dated notices, AGM dates, gatherings, etc. Only published announcements appear.
  • /p/<slug> — Content pages. Free-form pages (history, about, etc.) authored by site admins.

Nothing here exposes personal data — it's safe for the public.

2. Accounts & signing in

Who: everyone · Where: /signup, /login, /change-password

  • /signup — create an account (name, email, password).
  • /login — sign in.
  • /change-password — change your password. If an admin created your account with a temporary password, you're sent here automatically until you change it.

First-time setup: the very first owner must sign up normally, then be promoted from the server with npm run set-role -- <email> OWNER (see DEPLOYMENT.md).

3. Your families & the tree

Who: registered users · Where: /families, /families/new, /families/[familyId]

  • /families — the families you belong to. Each family is a single paternal tree rooted at one founder.
  • /families/new — start a new family: name it and enter the founder (the earliest-known ancestor / progenitor).
  • /families/[familyId] — the family home / tree view. Browse the tree; each person links to their profile. Dues payment status shows as coloured markers on the tree when the Trust is enabled. A member-only link row gives quick access to Trust, Members, Approvals, Birthdays, Print.

4. Building the tree — adding & editing people

Who: Contributors (add, PENDING) and Editors/Owners (add + edit + structural changes)

  • Person profile (/families/[familyId]/people/[personId]) — a person's details, with actions.
  • Add a child (/families/[familyId]/people/new) — add someone under a father. Contributor additions are PENDING; Editor/Owner additions are approved immediately.
  • Edit a person (…/people/[personId]/edit) — update names, dates, places, spouse, living status.
  • Extend the tree upward (Editor/Owner, only from the current root):
    • Add a known parent (…/add-parent) — puts a real ancestor above the current root.
    • Add unknown ancestors — insert placeholder ancestors when you know roughly how many generations are missing (or "unknown" for an approximate gap).
  • Join mid-lineage / populate backwards (…/anchor) — attach a new descendant beneath a known ancestor, auto-inserting placeholders for the unknown generations in between.
  • Flesh out a placeholder (…/fill) — turn an "Unknown ancestor" placeholder into a real person.
  • Confirm the founder — mark the verified progenitor (gold "Founder" badge) vs. a merely earliest-known ancestor.

Placeholders stand in for unknown ancestors so you can record a lineage even with gaps, then fill them in later.

5. Lineage & printing

Who: family members · Where: /families/[familyId]/lineage/[personId], /families/[familyId]/print

  • Lineage — a person's direct paternal line from the founder down. Shows only approved people.
  • Download lineage PDF — a formatted, printable direct-lineage document.
  • Print (/print) — a print-friendly rendering of the family for the browser's Print dialog.

6. Contributions & approvals

Who: Editors/Owners approve; Contributors submit · Where: /families/[familyId]/approvals

  • Contributors' new people are PENDING and tagged with who submitted them.
  • The approval queue groups pending submissions by contributor. Editors/Owners can:
    • Approve — also approves the person's still-pending ancestors (cascades up the chain).
    • Reject — removes the person and their pending descendants (cascades down).
  • Lineage and PDF/print surfaces always show approved-only data.

7. Members & roles

Who: Owners · Where: /families/[familyId]/members

  • See everyone with access to the family and their role.
  • Add members, change roles (Owner/Editor/Contributor/Viewer), remove members, and assign the treasurer flag.
  • Optionally link a member to their person node in the tree (this is what lets someone view "their own" dues statement).

8. Birthdays

Who: any family member · Where: /families/[familyId]/birthdays

  • A members-only list of upcoming birthdays — the next 30 days (with "Today" / "in N days"), then the rest of the year grouped by month.
  • Shows name and day/month only — never age or birth year. Includes living members with a recorded birth date; excludes deceased, placeholders, and pending people.

9. The Trust (dues) — for members

Who: family members where the Trust is enabled · Where: /families/[familyId]/trust

  • Dashboard (/trust) — the current AGM period's picture: collected total, paid/partial/unpaid counts, % paid, and per-house tables (Emituba / Enyiriri) with subtotals. House heads also see an unpaid sheet for their own house.
  • My statement — from the dashboard, open your own statement: your per-period history (rate, paid, balance, status), arrears, total balance, and a payment ledger. Members can view only their own; treasurers/heads can look up anyone via the finder.
  • Member statement page (/trust/member/[personId]) — the statement above; printable, and downloadable as a PDF.
  • Receipt (/trust/receipt/[paymentId]) — a per-payment receipt; printable and downloadable as a PDF.

The AGM cycle runs May → April. Dues are a flat rate per living beneficiary, set per period.

10. The Trust (dues) — for treasurers

Who: treasurers (record) and owners (configure) · Where: under /families/[familyId]/trust

  • Record a payment (/trust/record) — log a payment for a beneficiary: amount, date, method (Cash / MTN / Airtel / Bank), reference, who paid.
  • Quick-pay (/trust/quick-pay) — record several payments at once.
  • Void a payment — reverse a payment with a required reason (kept for the audit trail; excluded from totals).
  • Statement (/trust/statement) — the whole-family period statement (summary + per-house tables + per-house unpaid sheets); printable and PDF-downloadable.
  • Reports (/trust/reports) — analytics:
    • Expected vs collected per house (expected = living beneficiaries × rate) with Emituba/Enyiriri subtotals and progress bars.
    • Collection over time — cumulative-toward-target, monthly, and year-over-year modes.
    • Payments by method — totals by Cash/MTN/Airtel/Bank for the cycle.
    • Timing — payments-per-month and a member-participation curve (% fully paid by month).
  • Dues activity (/trust/activity) — the recent money events for this family (recorded / voided / rate & settings changes).
  • Export CSV — download the period's payments.
  • Configure the Trust (Owner, /trust/settings) — enable the Trust, set the chairman, define houses (Emituba/Enyiriri, each with a progenitor and acting head), set the rate per period, and assign treasurers.

11. Site administration — public site content (CMS)

Who: site admins · Where: /admin

  • Dashboard (/admin) — live org-wide tiles (families, total people, pending approvals across all families, Trust-enabled families) above the content-management tiles.
  • Sections (/admin/sections) — the ordered blocks of the public home page (numbers, places, announcements, lineage timeline, etc.): reorder, show/hide, and edit each section's copy.
  • Pages (/admin/pages) — create/edit/publish free-form content pages served at /p/<slug>.
  • Announcements (/admin/announcements) — post/publish dated notices shown on the portal and /news. Drafts stay private.
  • Navigation (/admin/nav) — manage the portal's nav links and their order/visibility.
  • Media (/admin/media) — uploaded assets.
  • Settings (/admin/settings) — site name, footer, app settings, and the public family shown on the portal.

After first deploy (or when a release adds a new section), run npm run seed:content to populate default portal sections, then set the public family here.

12. Site administration — governance

Who: site admins · Where: /admin/approvals, /admin/activity

  • Combined approvals (/admin/approvals) — pending submissions across all families in one queue; a site admin can approve/reject in any family.
  • Activity / audit log (/admin/activity) — a timeline of who changed what and when across dues (money), CMS content, membership/roles, and tree approvals; filterable by category. The money-accountability record for governance.

Site Map

Legend — access: P public · U any signed-in user · M family member (Viewer+) · C contributor · E editor · O owner · T treasurer · H head/chairman/viewer of dues · A site admin.

PUBLIC PORTAL
/                                   P   Heritage home (by-the-numbers, places, announcements)
/news                               P   Announcements feed
/p/[slug]                           P   Content pages

ACCOUNT
/signup                             P   Create account
/login                              P   Sign in
/change-password                    U   Change password (forced if temporary password)

FAMILIES & TREE
/families                           U   Your families
/families/new                       U   Create a family
/families/[familyId]                M   Family home / tree view
  /people/new                       C   Add a child (PENDING for contributors)
  /people/[personId]                M   Person profile
  /people/[personId]/edit           E   Edit a person
  /people/[personId]/add-parent     E   Add a known parent above the root
  /people/[personId]/anchor         C   Join mid-lineage (auto placeholders)
  /people/[personId]/fill           E   Turn a placeholder into a real person
  /lineage/[personId]               M   Direct paternal lineage (+ PDF)
  /approvals                        E   Approval queue (approve/reject cascades)
  /members                          O   Members & roles
  /birthdays                        M   Upcoming birthdays (name + day/month only)
  /print                            M   Printable family view

THE TRUST (DUES)  — under /families/[familyId]/trust
/trust                              H   Dues dashboard (period summary, houses)
/trust/record                       T   Record a payment
/trust/quick-pay                    T   Record several payments
/trust/statement                    H   Whole-family statement (+ PDF)
/trust/reports                      H   Expected-vs-collected, trends, method & timing
/trust/activity                     T   Dues money-events log
/trust/member/[personId]            M*  Member statement (own; or anyone for T/H) (+ PDF)
/trust/receipt/[paymentId]          H   Payment receipt (+ PDF)
/trust/settings                     O   Enable Trust, houses, rate, treasurers, chairman

SITE ADMIN  — under /admin
/admin                              A   CMS dashboard + org-wide tiles
/admin/sections                     A   Home-page sections
/admin/pages                        A   Content pages (/p/[slug])
/admin/announcements                A   Announcements
/admin/nav                          A   Portal navigation
/admin/media                        A   Media assets
/admin/settings                     A   Site settings + public family
/admin/approvals                    A   Combined cross-family approval queue
/admin/activity                     A   Activity / audit log (all categories)

* Member statement: a member may open their own; treasurers/heads/viewers may open anyone's in the family.

Note on downloadable PDFs (served under /api/families/[familyId]/dues/…/pdf): the receipt, member statement, and family statement each have a "Download PDF" button on their page, gated by the same access rules as the page.