Pitru Paksha Lineage Review System

MVP Scope · PLRS-MVP-v1.0

High-Level Design · Prepared by MFactor Consultancy · Event Target: September 2026

✦ ✦ ✦

Design Mandate: Keep the spine intact, shave the branches. The returning participant journey — the entire reason the system exists — survives the cut in full.

System Purpose

For Participants

Log in via magic link → review pre-filled ancestral lineage → update if needed → confirm and submit for the Pitru Paksha ritual.

For Admin Team

Monitor submission status, view individual records, and export confirmed lineage data to CSV/Excel for the ritual priests.

For the Ritual

Accurate, verified ancestral names reach the performing priests — the entire purpose of the system — ensuring rituals are conducted correctly.

MVP Scope at a Glance

✓ In Scope (KEEP)

Magic-link passwordless login
Prior year data pre-fill
19-field lineage form
Manual draft save (database-persisted)
Field-clear deletion warning
Final review & confirm step
Atomic submission + reference number
Confirmation email (E1, E5)
Minimal admin console
CSV/Excel export for ritual team

→ Deferred (FAST-FOLLOW)

Email OTP fallback login
Auto-save every 2 minutes
Reminder emails (E3, E4)
PDF download of submission
Admin override edit
Admin MFA & role split
Full side-by-side diff screen
Change-alert emails (E6–E8)
Year-scoped data model — MUST build now (invisible)
Field-clear warning — MUST retain (safety)

Key Non-Functional Requirements

🔒

TLS + Encryption at Rest

All lineage data encrypted in transit and storage

📱

Mobile-First

Responsive, usable on smartphones globally

⏱

Single-Use Tokens

Magic links expire, stored as hashes only

📋

Audit Log

No permanent deletion; all admin actions logged

User Flows

End-to-end journeys for Participants and Administrators

✦ ✦ ✦

Participant Journey (Primary)

Payment
External

→

Receive
Magic Link Email

→

Click Link
/ Login

→

View Pre-filled
Lineage Form

→

Review &
Update Fields

→

Save Draft
(optional)

→

Final Review
Summary

→

Confirm &
Submit

→

Confirmation
Email + Ref #

Re-entry path: Participant with a saved draft can click their magic link again → land directly on their in-progress form → continue from where they left off.

Deletion warning trigger: If any field is cleared that previously held a value, a modal warning fires. Participant must explicitly acknowledge before proceeding — protects sacred ancestor data integrity.

Admin Journey

Admin Login
(Password)

→

Dashboard:
Participant List

→

Filter by Status
(Not Started / Draft / Submitted)

→

View Individual
Record Detail

→

Export CSV/Excel
Submitted Records

Authentication Flow Detail

First-time Access

1. Payment confirmed by external system

↓

2. PLRS generates magic link, emails to participant

↓

3. Participant clicks link → authenticated session

↓

4. Token marked used, cannot replay

Link Expired / Returning

1. Participant visits login page

↓

2. Enters registered email address

↓

3. "Resend Link" → new magic link emailed

↓

4. Prior draft preserved (database-persisted)

State Machine — Participant Record

NOT STARTED

→

IN PROGRESS

→

SUBMITTED

Once SUBMITTED, the record is locked. No participant edits permitted post-submission.

Screen Designs

Key participant-facing screens with Gurulight visual language

✦ ✦ ✦

Screen 1 — Login / Magic Link Entry

pitrupaksha.gurulight.com/login

GURULIGHT

HelpSupport

🪔

Pitru Paksha 2026

Ancestral Lineage Review Portal

Registered Email Address

Send My Access Link

A secure, single-use link will be sent to your email. Check your inbox and spam folder.

Access is available only to participants with confirmed payment for Pitru Paksha 2026.

Screen 2 — Lineage Form (19 Fields)

pitrupaksha.gurulight.com/lineage

GURULIGHT

Draft Saved 2:34 PM Sign out

Your Ancestral Lineage

Pre-filled from 2025 · Review and update as needed

2025 data loaded

Participant

Full Name *

Gotra *

Ritual Code

Country of Residence

Father's Lineage

Father's Name *

Father's Father's Name

Father's Mother's Name

Father's Father's Father's Name

Mother's Lineage

Mother's Name *

Mother's Father's Name

Mother's Mother's Name

Mother's Father's Father's Name

Save as Draft

Review & Confirm →

* Required fields. Your progress is saved when you click "Save as Draft".

Screen 3 — Deletion Warning Modal

pitrupaksha.gurulight.com/lineage

GURULIGHT

Your Ancestral Lineage

⚠️

Ancestor Name Removed

You have cleared the field "Father's Mother's Name" which previously contained a value. This ancestor name is used in the ritual. Please confirm this is intentional.

Removing an ancestor's name means they will not be included in the Pitru Paksha ritual performed on your behalf.

← Restore Name

Yes, Remove

Screen 4 — Final Review & Confirm

pitrupaksha.gurulight.com/review

GURULIGHT

Review Your Submission

Please review all details carefully before confirming. This cannot be changed after submission.

Participant

Full Name: Rahul Sharma

Gotra: Kashyap

Ritual Code: PP-2026-0042

Country: India

Father's Lineage

Father: Suresh Sharma

Paternal Grandfather: Ramesh Sharma

Paternal Grandmother: Savitri Devi

I confirm that the ancestral lineage details above are accurate to the best of my knowledge and I authorise Gurulight to use this information for the Pitru Paksha 2026 ritual.

← Back to Edit

Submit My Lineage ✓

Screen 5 — Submission Confirmed

pitrupaksha.gurulight.com/confirmation

GURULIGHT

🙏

Submission Received

Your ancestral lineage has been confirmed for Pitru Paksha 2026

Reference Number

PP-2026-RSH-0042

Save this for your records

A confirmation email has been sent to your registered address with your submission details. Your record is now locked.

✦ ✦ ✦

Om Pitru Devaya Namaha

Admin Console

Minimal admin interface for submission management and data export

✦ ✦ ✦

Admin Dashboard — Participant Overview

pitrupaksha.gurulight.com/admin

GURULIGHT Admin

admin@gurulight.com

Export CSV

247

Total Participants

158

Submitted

In Progress

Not Started

Filter:

All

Submitted

In Progress

Not Started

Name	Email	Country	Status	Last Activity	Ref #
Rahul Sharma	rahul@email.com	India	Submitted	Jun 20, 2026	PP-2026-RSH-0042
Priya Nair	priya@email.com	Australia	In Progress	Jun 22, 2026	—
Anand Kumar	anand@email.com	USA	Not Started	—	—
Sunita Rao	sunita@email.com	UK	Submitted	Jun 19, 2026	PP-2026-SRA-0031

Admin — Record Detail View

pitrupaksha.gurulight.com/admin/record/PP-2026-RSH-0042

← Back to list

Submitted · Jun 20, 2026 PP-2026-RSH-0042

Rahul Sharma

rahul@email.com · India · Gotra: Kashyap

Father's Lineage

Father	Suresh Sharma
Pat. Grandfather	Ramesh Sharma
Pat. Grandmother	Savitri Devi

Mother's Lineage

Mother	Meena Sharma
Mat. Grandfather	Vijay Gupta
Mat. Grandmother	Kamla Gupta

Record is locked. Submitted via participant portal. Event Year: 2026. Data will pre-fill for Pitru Paksha 2027.

System Architecture

Technical layers and component relationships for the PLRS MVP

✦ ✦ ✦

Layered Architecture

Presentation Layer — Participant & Admin Portals

Lineage Form (19 fields)

Review & Confirm

Submission Confirmation

Admin Dashboard

Participant Record View

CSV/Excel Export

↕

Application Layer — Business Logic

Auth Service (Magic Link)

Lineage Service (CRUD)

Submission Service

Email Service (E1, E5)

Export Service

Admin Auth Service

Audit Logger

↕

Data Layer

Lineage Records DB (year-scoped)

Participant Registry

Magic Link Token Store (hashed)

Admin User Store

Audit Log Store

↕

External Integrations

Payment System → Confirmed Participants Feed

Transactional Email Provider (SendGrid / SES)

Recommended Tech Stack

Frontend

Next.js (React) — SSR for performance
TailwindCSS — Gurulight design tokens
React Hook Form — lineage form validation
Mobile-first responsive layout

Backend

Node.js / Next.js API routes
PostgreSQL — year-scoped data model
Prisma ORM — type-safe queries
JWT / secure session management

Infrastructure

Vercel / Railway — managed hosting
AWS RDS or Supabase — PostgreSQL
SendGrid or AWS SES — transactional email
TLS enforced end-to-end

Security Architecture

Magic Link Token Flow

1. Generate cryptographic random token (32 bytes)

↓

2. Store SHA-256 hash only (never plaintext)

↓

3. Email raw token as URL parameter

↓

4. On click: hash → compare → mark used

↓

5. Token unusable after first use or expiry (24h)

Data Protection

All traffic over TLS 1.2+
Lineage data encrypted at rest (AES-256)
Portal access gated by payment confirmation
No participant record hard-deleted
All admin actions written to audit log
Year-scoped isolation prevents cross-event leakage
No self-registration — invite-only access

Design System

Visual language sourced from gurulight.com/program/pitru-paksha-2025

✦ ✦ ✦

Palette source: Every color below is taken directly from the Pitru Paksha 2025 program page. The blacks (#000000, #020101, #282528, #2D2D2D) are deliberately excluded per brand direction — the darkest tone in use is slate #294C60.

Brand & Accent Colors

Slate (primary)

#294C60

Slate Gray

#3A4652

Sand / Tan

#DBA372

Coral

#D9534F

Alert Red

#E80000

Tan Deep (text)

#B27A3C

Neutral Ramp (from the page)

Body Text

#3F444B

Gray 555

#555555

Muted

#6B6B6B

Muted Slate

#69727D

Border

#EEEEEE

Fill

#F2F2F2

Page BG

#F5F5F5

Subtle

#F7F7F7

Card / White

#FFFFFF

Color Roles

Slate #294C60

Primary actions, headings, navigation, "Submitted" status. Replaces black as the dark anchor.

Tan #DBA372

The single warm accent — logo, section markers, highlights, ornaments, reference numbers, "In Progress" status.

Coral / Red

Reserved for the destructive path — deletion warnings, critical alerts. Used sparingly to keep weight.

Typography

Georgia — Display & Headings

Editorial authority · Used for page titles, logo, confirmation screen

Sans-Serif — UI & Body

System sans-serif stack (Inter preferred) · Used for labels, body copy, buttons, navigation

Monospace — Reference Numbers

Used only for reference numbers and technical identifiers

Component Library

Buttons

Primary — Submit / Confirm (slate)

Secondary — Edit / Back (tan)

Ghost — Save Draft / Cancel

Destructive — Remove Ancestor

Status Badges

● Submitted — Record locked, priest receives data

● In Progress — Draft saved, not yet submitted

● Not Started — Magic link sent, no action taken

● Pre-filled — Data loaded from prior year

● Incomplete — Required fields missing

Design Principles

Sacred Data Respect

Ancestor names are treated with reverence. The UI makes deletion deliberate and acknowledged — never accidental.

Global Accessibility

Participants span India, Australia, UK, USA. Mobile-first, low-bandwidth tolerant, plain language, no jargon.

Quiet Devotion

Slate and sand on clean gray-white, Georgia serif, subtle ornamental dividers. Calm and reverent, never a generic SaaS tool.

Data Model

Year-scoped schema — built future-aware from day one

✦ ✦ ✦

Non-negotiable architectural decision: All lineage records must be scoped by event_year from the start. This is invisible to users in 2026 but prevents a painful rebuild for Pitru Paksha 2027. (BRS Q6 — confirmed "yes, reused".)

Core Entities

participants

id	UUID · PK
email	VARCHAR · UNIQUE · NOT NULL
full_name	VARCHAR
payment_confirmed	BOOLEAN · NOT NULL
payment_year	INTEGER · NOT NULL
created_at	TIMESTAMP

magic_link_tokens

id	UUID · PK
participant_id	FK → participants
token_hash	VARCHAR · SHA-256 only
used	BOOLEAN · default FALSE
expires_at	TIMESTAMP · 24h TTL
created_at	TIMESTAMP

lineage_records

id	UUID · PK
participant_id	FK → participants
event_year	INTEGER · NOT NULL · KEY FIELD
status	ENUM(not_started, draft, submitted)
reference_number	VARCHAR · UNIQUE (on submit)
submitted_at	TIMESTAMP · nullable
prefilled_from_year	INTEGER · nullable

lineage_fields

id	UUID · PK
record_id	FK → lineage_records
field_key	VARCHAR (e.g. "father_name")
field_value	TEXT · encrypted at rest
tier	VARCHAR (participant/father/mother)
updated_at	TIMESTAMP

The 19 Lineage Fields

Participant (4 fields)

Full Name *
Gotra *
Ritual Code
Country of Residence

Father's Side (8 fields)

Father's Name *
Father's Father's Name
Father's Mother's Name
Father's Father's Father
Father's Father's Mother
Father's Mother's Father
Father's Mother's Mother
Father's Gotra

Mother's Side (7 fields)

Mother's Name *
Mother's Father's Name
Mother's Mother's Name
Mother's Father's Father
Mother's Father's Mother
Mother's Mother's Father
Mother's Gotra

* Required. All other fields optional but strongly encouraged. Plain-language help text shown for each field. Exact field list to be confirmed with Gurulight before build (Q7: Ritual Code — free text vs fixed list).

Audit Log

audit_log

Every admin action (record view, export, status change, login) appends an immutable row: actor_id · action_type · target_id · timestamp · ip_address. Participant field-clear acknowledgements also logged. No record in this table is ever deleted.