Skip to content

prd.md

Latest commit

 

History

History
399 lines (284 loc) · 18 KB

prd.md

File metadata and controls

399 lines (284 loc) · 18 KB

Product Requirements Document (PRD)

Domus — Digital Administration for Kristus Raja Barong Tongkok Catholic Parish

MVP Version

Document Version: 1.0.13 Status: In Progress Last Updated: 12 April 2026

1. Background

Kristus Raja Barong Tongkok Parish currently manages all administration manually — from recording parishioner attendance at organizational events to parish bookkeeping using ledger books and paper. This results in data that is difficult to access, prone to loss or damage, and inefficient to manage in the long run.

Domus is a parish administration digitalization solution built as a Progressive Web App (PWA) — lightweight, easy to access, and usable by all parishioners without significant technical barriers.

2. Product Goals

  • Make it easier for parishioners to independently register for parish organizations.
  • Make it easier for parishioners to independently record their attendance at organizational events.
  • Provide the parish treasurer with a structured and documented financial recording tool.
  • Provide the pastor and executive board with transparent and easy-to-understand financial reports.
  • Provide a centralized liturgical calendar reference to support parish planning and ministry scheduling.

2.1 Success Metrics (KPIs)

To measure the success of the Domus MVP implementation, the following indicators are established:

  • Digital Adoption: >70% of active parishioners registered digitally within the first 90 days.
  • Reporting Efficiency: 100% of monthly financial reports generated through the system (replacing manual ledger books).
  • Attendance Accuracy: >90% of event attendance records captured via digital methods (QR/GPS).
  • Cost Sustainability: Total infrastructure operating costs (Neon, Cloudflare, Google API) below $25/month.
  • Performance: First page load time < 2 seconds on standard mobile 4G connection.

3. MVP Scope

The Domus MVP covers five main features:

  1. Registration & Enrollment Management — parishioners can register for organizations independently, and admins can manage enrollment data.
  2. Parishioner Self-Attendance — parishioners can record their own attendance at organizational activities.
  3. Parish Financial Recording — treasurers can record parish income and expenses.
  4. Financial Reports — pastors and the executive board can access financial reports digitally.
  5. Ordo (Liturgical Calendar) — a centralized reference for daily liturgical celebrations, readings, and song suggestions, seeded from lagumisa.web.id and manageable by admins.

4. Users & Roles

A single user can have more than one role simultaneously. The default role for all new users is Parishioner.

4.1 Global Roles

UserRole Description
Super Admin (super-admin) System management: user management, transaction categories, and joinId rotation. No access to parish features.
Parish Admin (parish-admin) Creates and manages parish-level organizations and public events (e.g., mass, retreats). Manages ordo entries.
Treasurer (treasurer) Records transactions, manages categories, and locks/unlocks financial periods.
Pastor (pastor) Views financial reports (read-only access).
Executive Board (executive-board) Daily administrators with access to financial reports.
Parishioner (parishioner) Default role for all users; allowed to RSVP and perform self-attendance at events. Can view the ordo.

4.2 Scoped Roles (per Organization)

UserRole Description
Owner (owner) Full access and control over the organization.
Admin (admin) Manages events, attendance, and organization members. Can approve or reject new enrollment registrations.
Member (member) Can RSVP and perform attendance at organization events.

Note: Roles are not inherited automatically. All assignments are explicit — an admin of a parent organization does not automatically become an admin of sub-organizations.

5. Organization Structure

5.1 Territorial Organizations

Territorial organizations are based on geographic areas. Each level is optional — not all levels are required to exist.

graph TD
    W[Region] --> S[Station]
    W --> L[BEC]
    S --> L
    L2[BEC] --> |standalone| L2
Loading

Valid examples:

  • Region → Station → BEC
  • Region → BEC (without Station)
  • Station → BEC (without Region)
  • BEC (standalone)

5.2 Categorical Organizations

Activity-based or community organizations with a maximum nested structure of 3 levels. Each categorical organization can have units (committees/divisions) displayed during enrollment registration.

graph TD
    DPP --> P[Board 2024-2027]
    DPP --> PN[Christmas Committee 2026]
    P --> SK[Spiritual Committee]
    P --> SH[Public Relations Committee]
    PN --> SKons[Consumption Committee]
    PN --> SD[Decoration Committee]

    OMK --> OMK_SK[Spiritual Committee]
    OMK --> OMK_SL[Research Committee]
    OMK --> OMK_SH[Public Relations Committee]

    LM[Legion of Mary]
Loading

5.3 Parishioner Enrollment

  • Parishioners are optionally registered in a specific BEC (Basic Ecclesial Community) according to their domicile.
  • Parishioners are free to join one or more categorical organizations.
  • A parishioner can be enrolled in multiple organizations simultaneously with different positions.
  • Parishioner data can be entered manually by an admin without needing a Domus account — to accommodate elderly parishioners or those without devices.

6. Feature Details

6.1 Registration & Enrollment Management

Self-Registration Flow

User Story: As a parishioner, I want to register for an organization via a simple link so that I don't have to go through a complicated bureaucratic procedure.

Acceptance Criteria:

  • The joinId link must be valid and not expired.
  • The registration form captures required data (Full Name, ID Card Photo, Position).
  • Enrollment status is automatically set to pending until approved by an admin.
  • The user receives a notification after the registration is successfully submitted.
flowchart TD
    A[Parishioner visits /join/[joinId]] --> B{Already logged in?}
    B -- No --> C[Redirect to login page]
    C --> D[Sign in via Google OAuth]
    D --> E{Email registered?}
    E -- No --> F[Create new account\nstatus: pending]
    E -- Yes --> G[Continue]
    F --> G
    B -- Yes --> G
    G --> H[Show organization info\n& units]
    H --> I[Parishioner fills form]
    I --> J[Click Register]
    J --> K[Data saved\nstatus: pending]
Loading

Invitation Link (joinId)

  • Each organization has a unique joinId in the form of a Nano ID.
  • joinId is rotated periodically via a cron job for security reasons — old links are automatically invalidated after rotation.
  • Organizations with joinId set to null do not accept new enrollment registrations.
  • Rotation is performed simultaneously for all organizations actively accepting enrollments.

Verification Process by Admin

Organization Admins (territorial and categorical) can approve or reject registrations:

Action Impact
Approve Enrollment status → active. If account is still pending → changed to approved. ID card photo permanently deleted from Google Drive. Notification sent via in-app and email.
Reject Capture email & name data for notification first. ID card photo permanently deleted from Google Drive (privacy priority). Account status → rejected. Parishioner data and enrollment records deleted. Notification sent via email.
  • Both Territorial and Categorical Organization Admins can directly input new parishioner data without going through the self-registration flow.
  • Manually entered data does not require an approval process.
  • Admins can search for existing parishioners by name or email to prevent duplicate records during manual entry.

6.2 Parishioner Self-Attendance

Event Flow

User Story: As a parishioner, I want to record my attendance independently so that the attendance process on-site becomes faster and more efficient.

Acceptance Criteria:

  • QR Code: The system validates the eventId and records Present status immediately.
  • GPS: The system verifies the location within the defined radius before allowing attendance.
  • Fallback: If GPS fails, the system allows a manual submission that requires admin approval.
  1. Organization Admin creates an event (name, time, location, optional GPS coordinates).
  2. If the RSVP feature is enabled, parishioners can RSVP before the event takes place.
  3. On the day of the event, parishioners record their attendance using one of the methods below.

Event Types

Type Created By Participants
Private Event Organization Admin Members of the relevant organization
Public Event Parish Admin All parishioners (mass, retreat, etc.)

Attendance Methods

flowchart TD
    A[User checks in] --> B{Method}

    B --> C[Scan QR Code]
    C --> C1[Validate eventId]
    C1 --> C2[Attendance recorded: present]

    B --> D[Self-check via GPS]
    D --> D1{GPS valid?}
    D1 -- Yes --> D2[Attendance recorded: present]
    D1 -- No --> D3[Submit manual request]
    D3 --> D4{Admin reviews}
    D4 -- Approve --> D5[Status: present]
    D4 -- Reject --> D6[Status: absent]

    B --> E[Manual by Admin]
    E --> E1[Attendance recorded: present\nno additional approval]
Loading
Method Description
Scan QR Code Admin provides a QR Code at the event location. Parishioner scans it using their phone camera. Immediately recorded as present.
Self-check via GPS Parishioner taps the check-in button on their phone and the system verifies the location via GPS within the defined radius.
Manual by Admin Organization Admin inputs attendance on behalf of a parishioner. No additional approval required.

Note: GPS attendance that fails verification can be submitted manually by the parishioner and requires Admin approval. If approved, status becomes present; if rejected, status becomes absent.

RSVP

  • RSVP is optional per event — enabled by the admin when creating the event.
  • Parishioners who did not RSVP can still check in.
  • RSVP Status: Attending, Not Attending, Maybe.

6.3 Parish Financial Recording

User Story: As a treasurer, I want to record transactions and lock financial periods so that the generated reports are accurate and cannot be altered arbitrarily.

Acceptance Criteria:

  • Recorded transactions must have a valid category, amount, and date.

  • Locked periods cannot be deleted or modified by anyone.

  • Transaction proof (photo) is stored securely and can be reviewed through the system.

  • Only the Treasurer can record transactions.

  • Transaction types: Income and Expense.

  • Each transaction is categorized using categories manageable by the super-admin and Treasurer.

  • Each transaction can include proof of transaction (receipt photo) stored in Google Drive — optional.

  • Transactions are grouped into monthly periods (January–December).

  • The Treasurer can lock a completed period to prevent modifications, and can unlock it again if needed.

6.4 Financial Reports

  • Accessible by the Pastor and Executive Board.
  • The Treasurer can also access reports as part of financial management.
  • Report period: Annual (January–December).
  • Reports support drill-down — from annual summary → per month → per transaction detail.

6.5 Ordo (Liturgical Calendar)

User Story: As a parish admin, I want a centralized liturgical calendar so that I can reference daily celebrations, readings, and song suggestions when planning parish events and ministry schedules.

Acceptance Criteria:

  • Ordo data is seeded automatically from lagumisa.web.id via the sync pipeline.
  • Parish admins can add, edit, or soft-delete ordo entries manually.
  • Each entry shows: date, celebration name, rank, liturgical color, readings, and song suggestions.
  • Entries can be linked to events to associate a mass or parish activity with its liturgical context.
  • All parishioners can view the ordo (read-only).

Data Source

Ordo data is scraped from lagumisa.web.id/saranps.php via packages/sync. The scraper runs on demand or via cron and upserts into the ordo table. Admin manual entries take source: 'manual' and are never overwritten by the scraper.

Celebration Ranks

Rank Description
solemnity Hari Raya — highest rank
feast Pesta
memorial Peringatan Wajib
commemoration Peringatan Fakultatif
feria Hari Biasa

Liturgical Colors

purple, white, red, green, rose, black

Multiple Masses per Day

Some celebrations have multiple masses (e.g., Christmas: Midnight, Dawn, Day). Each mass is stored as a separate ordo record with the same date but a different massLabel.

7. Authentication & Access

  • The system uses Google OAuth as the sole authentication method.
  • Passwordless — users do not need to create or remember a password.
  • Only users with approved account status can access the application.
  • Users with pending status are directed to the Awaiting Approval page.
  • Users with rejected status are directed to the Access Denied page.

8. Assumptions & Dependencies

8.1 Assumptions

  • Parishioners have an Android or iOS smartphone with a modern browser that supports PWA.
  • Internet connection is available at event locations (at minimum for the attendance process).
  • Parishioners have an active Google account for the authentication process.
  • Organization admins have basic skills to operate a web-based application.
  • Elderly parishioners or those without devices will be assisted by admins through manual input.

8.2 Dependencies

Dependency Description
Google OAuth Authentication is fully dependent on Google's services. If Google OAuth is down, users cannot log in.
Google Drive Storage for verification documents, transaction receipts, and general attachments.
Cloudflare R2 Storage for public media assets.
Vercel Application hosting platform.
Neon PostgreSQL Primary application database.
Cloudflare Workers Cron job for joinId rotation.
lagumisa.web.id External source for ordo seeding. Read-only scraping — no API key required.

8.3 Technical Risks

  • GPS Accuracy: In remote station areas, GPS signals may be unstable, potentially increasing the admin's workload for approving manual attendance submissions.
  • Third-Party Dependency: Full reliance on Google OAuth and Google Drive means if those services go down, login and verification functions will halt.
  • JoinId Rotation: Periodic link changes may confuse parishioners if old links are still being shared; clear error messages and a flow for requesting a new link are required.
  • lagumisa.web.id Structure Changes: The ordo scraper depends on the HTML structure of lagumisa.web.id. If the site changes its markup, the scraper will break and require maintenance. Manual entry remains available as a fallback.

9. Platform

  • Progressive Web App (PWA)
  • Mobile-first design, responsive across all screen sizes.
  • Installable on Android and iOS devices via browser.

10. Third-Party Integrations

Service Usage
Google OAuth User authentication
Google Drive Private file storage: ID card photos (verification), transaction receipts, event attachments, org documents, SK documents. Accessed via Google Drive Viewer URL.
Cloudflare R2 Public asset storage: org logos, org covers, user profile photos (custom uploads). Served via direct public URL.
Cloudflare Workers Cron job for joinId rotation
lagumisa.web.id Ordo data source — liturgical calendar scraping

10.1 Storage Responsibility

File Type Storage Rationale
Org logos, org covers Cloudflare R2 Public, web-renderable — needs direct URL access
User profile photos (custom) Cloudflare R2 Public, web-renderable — needs direct URL access
ID card photos Google Drive Sensitive PII — permanently deleted after verification
Transaction receipts Google Drive Financial document — private, audit trail. Stored directly on transactions.receiptPhoto
Event attachments (photos, docs) Google Drive Multiple files per event — managed via attachments table (referenceType: 'Event')
Org documents (AD/ART, notulen) Google Drive Multiple files per org — managed via attachments table (referenceType: 'Organization')
SK documents & term files Google Drive Multiple files per term — managed via attachments table (referenceType: 'Term')

Note: users.image defaults to the Google OAuth profile photo URL. Custom uploads are stored in Cloudflare R2.

Note: Transaction receipt photos (transactions.receiptPhoto) remain as a dedicated field — not part of the general attachment system — to keep financial queries simple and audit trails clean.

11. Out of MVP Scope

The following features are not included in the MVP and will be considered in future iterations:

  • Sacrament data management (baptism, marriage, death)
  • Parish inventory management
  • Online donation feature
  • Multi-parish support
  • Push notifications
  • Financial report export (PDF/Excel)
  • Liturgical ministry scheduling (linked to ordo — post-MVP)

11.1 Non-Goals

To maintain the project timeline, the following are explicitly not goals of the MVP:

  • Bulk Data Import: No feature for importing parishioner or financial data via CSV/Excel; data is entered through the application UI.
  • Offline Sync: The application requires an active internet connection for most functions (Attendance, Registration); no offline database synchronization.

This document is a living document and may be updated as discussions and product requirements evolve.