# GeetaShyam.guru Satsang Parivar Management Platform ## Comprehensive Feature-Gap & Architecture Review This document provides a comprehensive feature inventory, architectural gap analysis, usability audit, security review, and prioritization roadmap for the GeetaShyam Satsang Parivar Management Platform. --- ## 1. Executive Summary The GeetaShyam Parivar Management Platform is a completely non-commercial, spiritual parivar coordination portal. Over five sequential development phases, we have successfully established the secure core: geographic scoping boundaries, TypeScript strictness, target-scope server actions, timezone-aware scheduling generation, guest & member attendance check-ins, and flexible target announcements. However, before the platform is deployed in production for active parivar use, key operational gaps must be resolved. These include PWA installation/offline caching boundaries, CSV profile import engines, automated data-quality indicators, and structured role-specific dashboards. This document identifies all current code coordinates, compares the original vision with the current implementation, and maps out the recommendations for Guruji and Yogesh. --- ## 2. Current Platform Map The application is structured as a Next.js App Router project: * **`/src/lib/models/`**: Core Mongoose database schemas ([Member](file:///src/lib/models/Member.ts), [Satsang](file:///src/lib/models/Satsang.ts), [SatsangCenter](file:///src/lib/models/SatsangCenter.ts), [User](file:///src/lib/models/User.ts), [Announcement](file:///src/lib/models/Announcement.ts), [Attendance](file:///src/lib/models/Attendance.ts), [AuditLog](file:///src/lib/models/AuditLog.ts)). * **`/src/lib/actions/`**: Server-side mutation boundaries protecting mutations. * **`/src/app/(admin)/`**: Administrator-facing layout views with navigation layouts. * **`/src/scripts/`**: Development test runner files ([test-auth.ts](file:///src/scripts/test-auth.ts), [seed.ts](file:///src/scripts/seed.ts)). --- ## 3. Feature Inventory Here is the classification of all functional areas based on the actual codebase: | Feature Area | Classification | Description / Status | | :--- | :--- | :--- | | **Geographic Hierarchy Setup** | **COMPLETE** | Countries, States, Cities, and Areas schemas and selectors implemented. | | **User Role & Assignment** | **COMPLETE** | Separation of platform Users from CRM Members. Scoped role assignments check timelines. | | **Member CRM Directory** | **COMPLETE** | Mobile-normalized registration, custom Human-friendly Member IDs, transfers, and history logs. | | **Family / Parivar Groups** | **COMPLETE** | Common `familyId` UUID groupings with bi-directional reciprocal relatives links. | | **Satsang Center Scheduling** | **COMPLETE** | Center location mapping, weekly recurring schedule generator, and occurrence generator. | | **Attendance Check-in Checklist** | **COMPLETE** | Present/Absent semantics, check-in timestamps, original marker preservation. | | **Offline Synchronization** | **COMPLETE** | Client-side IndexedDB transaction queue with authorization re-checks. | | **Announcements Feed** | **COMPLETE** | Target selection, publish/expiry schedules, and cascading delivery. | | **Organizational Directory** | **COMPLETE** | Recursive leadership hierarchical trees with masked login emails and CRM mobiles. | | **Nearest Satsang Finder** | **COMPLETE** | Geospatial distance calculation and timezone-aware calendar groupings. | | **System Configuration** | **COMPLETE** | Multi-setting variables configurations (windows, radius). | | **Audit Logs Dashboard** | **COMPLETE** | Actor action tracking with changed fields diff logs. | | **Rewards & Recognition** | **PARTIAL** | Core `appreciations: string[]` exists on Member model, but no coordinator-facing UI is built. | | **Inactivity Reports** | **PARTIAL** | Not Attended Recently & Never Attended reports built; other aggregations missing. | | **Role-Specific Dashboards** | **PARTIAL** | Dashboard queries are scoped, but the widgets remain identical for all roles. | | **Member Portal Access** | **MISSING** | CRM members cannot log in; system is restricted to administrators and incharges. | | **CSV Import Engine** | **MISSING** | No mechanism exists to upload existing member spreadsheets. | | **CSV/Excel Export Controls** | **MISSING** | No option exists to download directories or attendance reports. | | **PWA Manifest & Caching** | **MISSING** | Offline manifest file, service worker caching shell, and installation prompts are missing. | | **Volunteer Seva Allocation** | **MISSING** | Volunteer slot allocation and setup assignments are not implemented. | | **External Notifications** | **DEFERRED** | Push, WhatsApp, and SMS delivery are deferred. | | **Prayer / Daan Systems** | **DO NOT BUILD** | Commercial and donation systems are explicitly excluded. | --- ## 4. Feature Audits ### 4.1. Organization Review * **Existing:** Roles (`SUPER_ADMIN`, `CITY_HEAD`, `AREA_INCHARGE`) are separated from CRM members. Geographic scopes are checked at Server Action boundaries. Timelines (`validFrom`/`validTo`) are checked dynamically. * **Gap:** If a City Head is reassigned, center incharges in that city remain unchanged unless updated manually. There is no central screen for Super Admins to view an overview of all active assignments in one grid. * **Recommendation:** Keep current granular controls. Add a read-only "Assignments Grid" in the User management module. ### 4.2. CRM Review * **Existing:** Supports strict mobile normalization, custom human-friendly IDs, transfer logs, profile edit audit logs, search, pagination, and multi-field filtering. * **Gap:** No warning or validation indicators for missing optional fields (e.g., missing photo, missing emergency contact). Emergency contact field is missing from the database schema. * **Recommendation:** Add an optional `emergencyContact` string field to [Member.ts](file:///src/lib/models/Member.ts). Expose a "Data Completeness Score" on the profile page. ### 4.3. Family / Parivar Review * **Existing:** Bi-directional reciprocal relatives links and common `familyId` UUIDs are managed inside `members.ts`. * **Gap:** No dedicated "Family View". Viewing a household requires clicking into individual relative profile cards. * **Recommendation:** Create a lightweight family page or card panel `/members/family/[familyId]` grouping members in the same household, enabling one-click check-ins for the entire family. ### 4.4. Satsang Management Review * **Existing:** Regular schedules generate future occurrences up to `satsangOccurrenceGenerationDays`. Custom timezone snapshotting handles DST or zone adjustments. * **Gap:** Generating occurrences is run on-demand or by admins. No background scheduler task runs to auto-generate next month's events. * **Recommendation:** Build a Next.js cron runner or background scheduler trigger to auto-generate occurrences daily. ### 4.5. Attendance Review * **Existing:** Enforces early check-in and back-entry limits. Guest check-in records names and phone numbers. Offline synchronization processes transactions. * **Gap:** No indicator on the attendance checklist showing if a member is a "First-time attendee" or has "Missed 3 consecutive weeks" (risk of drift). * **Recommendation:** Add visual badges (e.g., `New`, `At Risk`) on the check-in checklist to prompt coordinators to offer support. ### 4.6. Guest Journey Review * **Existing:** Guests can register on-the-fly during check-in with name and mobile number. * **Gap:** Guest records are saved inside the `Attendance` document. There is no automated workflow to convert a regular guest into a full Member profile without manual re-entry, creating a risk of duplicates. * **Recommendation:** Provide a "Convert Guest to Member" action button on the attendance report. It should pre-fill the Member registration form with the guest's check-in history. ### 4.7. Announcement Review * **Existing:** Multi-target feed queries match city, area, center, and role selectors. Cascading logic checks nested relationships. * **Gap:** No push notifications or desktop alerts for Urgent announcements. Users must manually reload the dashboard to see notices. * **Recommendation:** Implement Web Push API triggers for Urgent announcements. ### 4.8. Directory Review * **Existing:** Renders dynamic geostructural tree. Omits account login email addresses and CRM personal phones. Shows center contacts. * **Gap:** Clicking a center in the tree does not redirect to the Center details page. * **Recommendation:** Add links to the Directory tree nodes redirecting users to the Center details page `/satsangs/centers/[id]`. ### 4.9. Nearest Satsang Review * **Existing:** Uses MongoDB `$nearSphere` search against `2dsphere` geographic coordinates. Groupings group events into Today, Tomorrow, This Week, and Later. * **Gap:** `$nearSphere` is appropriate for thousands of centers. Scaling past 10,000 centers requires a geospatial index shard key. * **Recommendation:** Keep current `$nearSphere` logic. It is highly optimized and sufficient for the current scale. ### 4.10. Rewards / Recognition Review * **Existing:** `appreciations: string[]` exists on the Member model schema. * **Gap:** No UI exists to manage or display appreciations. * **Recommendation:** To prevent competitive gamification, rename "Rewards" to **Seva Appreciation**. Allow City Heads and Super Admins to append appreciations (e.g., "Served at Indore Central Clean-up") displayed on Member profiles. ### 4.11. Seva / Volunteer Review * **Existing:** Roles are strictly administrative (`CITY_HEAD`, `AREA_INCHARGE`). * **Gap:** No option to schedule generic volunteers (members without admin credentials) for tasks like Audio Setup or Welcome Seva. * **Recommendation:** Add a `SevaAssignment` schema linking a Member to a Satsang occurrence for a specific role. ### 4.12. Member Status & Engagement Review * **Existing:** `status: 'Visitor' | 'Regular Attendee' | 'Member' | 'Inactive'` handles states. * **Gap:** Status changes must be edited manually. * **Recommendation:** Automated status promotion: Promote `Visitor` to `Regular Attendee` after 3 check-ins. Suggest transitioning to `Inactive` if no attendance is logged for `attendanceInactiveThresholdDays`. ### 4.13. Reporting Review * **Existing:** Never Attended and Not Attended Recently reports exist. * **Gap:** No graphical statistics or overall trends charts (e.g. attendance percentage month-over-month). * **Recommendation:** Integrate clean, layout-responsive SVG bar charts showing attendance trends. ### 4.14. Dashboard Review * **Existing:** Scoped metric counters are displayed. * **Gap:** Identical widgets are rendered for all roles. * **Recommendation:** Customize dashboards: * **Super Admin:** Focuses on audit logs and system settings. * **City Head:** Focuses on center metrics and inactive reports. * **Area Incharge:** Focuses on check-in checklists and upcoming schedules. --- ## 5. Permission Matrix A simplified, non-technical overview of user capabilities: | Functional Action | Super Admin | City Head | Area Incharge | Member (Future Portal) | | :--- | :---: | :---: | :---: | :---: | | **Manage System Settings** | **Manage** | Denied | Denied | Denied | | **Configure Geographies** | **Manage** | Denied | Denied | Denied | | **Create Satsang Centers** | **Manage** | Denied | Denied | Denied | | **Assign Leaders** | **Manage** | Scoped | Denied | Denied | | **Create Schedules** | **Manage** | Scoped | Scoped | Denied | | **Edit/Cancel Occurrence** | **Manage** | Scoped | Scoped | Denied | | **Register Member** | **Create** | Scoped | Scoped | Denied | | **Transfer Member** | **Manage** | Scoped | Denied | Denied | | **Mark Attendance** | **Manage** | Scoped | Scoped | Denied | | **Back-Entry Attendance** | **Override** | Denied | Restricted | Denied | | **Publish Announcements** | Global | Scoped | Scoped | Denied | | **Export Member CSV** | **Export** | Scoped | Denied | Denied | | **Import Member CSV** | **Import** | Denied | Denied | Denied | | **View Own Profile** | **View** | **View** | **View** | **View** | *`Scoped`: Restricted strictly to their assigned City or Area boundaries.* --- ## 6. Technical Review ### 6.1. Search Review * **Existing:** Text indexes exist on `Member.name` and search checks exist on `SatsangCenter.name`. * **Gap:** Searching requires navigating to specific directories. There is no global search bar to quickly locate profiles. * **Recommendation:** Implement a global command palette search bar on the top navigation shell for Super Admins. ### 6.2. Import / Export Review * **Existing:** Mongoose import scripts are used for seeding, but no dynamic import/export exists. * **Gap:** CRITICAL. No tool exists for importing member spreadsheets. * **Recommendation:** Build a secure CSV Import Action supporting mapping validations, duplicate detection, and import audits. ### 6.3. PWA Readiness Audit * **Existing:** Offline synchronization queues transactions using IndexedDB. * **Gap:** CRITICAL. Missing `manifest.json`, service worker registrations, cache-headers configurations, and install banners. * **Recommendation:** Install next-pwa, set up the web manifest, and implement service worker shell caching. ### 6.4. Mobile Usability Audit * **Existing:** Sidebar navigation collapses, and directory listings stack. * **Gap:** Attendance checklists have small tap targets, which makes fast tap interactions error-prone on small screens. * **Recommendation:** Increase tap target sizes for attendance checkboxes to at least `48px` to prevent mis-taps. ### 6.5. Accessibility (a11y) Review * **Existing:** Uses clean HTML markup. * **Gap:** Form selectors lack explicit aria attributes, and dialog overlays lack keyboard focus traps. * **Recommendation:** Implement screen-reader labels and check overlay focus traps. ### 6.6. Data Privacy & Security Audit * **Existing:** Middleware validates sessions, and target boundaries verify permissions. * **Gap:** Audit logs track changed fields, but the values are not hashed or encrypted. * **Recommendation:** Enforce database encryption at rest and add rate-limiting to API endpoints. --- ## 7. Feature Prioritization ### 7.1. MUST HAVE BEFORE REAL USE 1. **CSV Profile Import Engine:** Allows administrators to upload member spreadsheets. 2. **PWA Shell & Installability:** Enables offline service workers and install prompts. 3. **Data Export Controls:** Allows authorized leaders to download CSV reports. 4. **Enhanced Mobile Tap Targets:** Optimizes attendance screens for mobile use. ### 7.2. SHOULD HAVE SOON 1. **First-Time Attendee Badges:** Identifies new visitors on checklists. 2. **Guest Conversion Action:** Streamlines converting guests to member profiles. 3. **Seva Assignment Records:** Schedules volunteers for setup tasks. 4. **Custom Role-Specific Dashboards:** Tailors views for different roles. ### 7.3. NICE TO HAVE 1. **Appreciation logs:** Displays seva acknowledgments on profiles. 2. **Command Palette Search:** Quick search bar in the navigation header. 3. **Auto-Inactivity Suggestions:** Flags drifting members automatically. ### 7.4. FUTURE 1. **Push notifications:** Alerts for urgent announcements. 2. **Member portal logs:** Secure login access for members. --- ## 8. Recommended Phase 6 ### Scope: Production Hardening, Import Engines, & PWA Readiness Phase 6 should focus on completing the gaps required for real-world deployment, avoiding new feature bloat: 1. **Spreadsheet Import/Export Engine:** * CSV upload interface with structural validations. * Scoped CSV exports for City Heads and Super Admins. 2. **Complete PWA implementation:** * Manifest assets, offline cache strategies, and install prompts. 3. **Usability Hardening:** * Mobile tap target improvements. * Badges on attendance lists for first-time attendees. 4. **Volunteer Seva Allocation:** * Basic volunteer assignment slots for Satsang events. --- ## 9. Open Decisions for Yogesh / Guruji 1. **Rewards vs. Seva Appreciation:** * *Option A:* Build point-based volunteer counts (Not recommended). * *Option B:* (Recommended) Keep it simple and focused on appreciation notes. 2. **Member Login Portal Timeline:** * Do we allow members to log in to view schedules in Phase 6, or keep the platform coordinator-only? 3. **Export Policy Scope:** * Should Area Incharges be allowed to export data, or restrict CSV downloads to City Heads and Super Admins to protect privacy?