Church Check-In Application - Requirements Document

1. Project Overview

1.1 Purpose

A church attendance check-in system that allows visitors and members to register their attendance on service days, with administrative tools for managing member data, tracking attendance, and generating reports.

1.2 Target Users

• Primary Users: Church visitors and members checking in on service days
• Administrative Users: Church staff managing member data, attendance records, and system settings

2. User Roles & Permissions

2.1 Public Users (No Authentication Required)

• Can check in as Visitor or Member
• Can access help documentation
• Can initiate contact via SMS

2.2 Authenticated Admin Users

• Full CRUD operations on Members
• View and manage Attendance records
• Import member data from external sources
• Configure system settings
• Export attendance reports

3. Functional Requirements

3.1 Check-In Flow

3.1.1 Home Screen

• FR-001: Display configurable home screen with three layout options:
  • Layout A: Side-by-side "Visitor" and "Member" buttons
  • Layout B: Vertical layout emphasizing first-time visitors
  • Layout C: Default layout with regular attendees first, visitors second
• FR-002: Provide "Let's Connect" button linking to SMS with pre-configured message
• FR-003: Provide "Help" button accessing help documentation
• FR-004: Display version number (configurable visibility)

3.1.2 Visitor Check-In

• FR-005: Capture visitor information:
  • Full name (required)
  • Email address (required, validated)
  • Number of attendees/visitors (numeric)
  • Phone number (optional)
  • "How did you hear about us?" (dropdown/select)
  • Other information (free text)
  • "Would you like more information?" (checkbox)
  • "May we contact you?" (checkbox)
• FR-006: Validate email format
• FR-007: Create new Member record with status "Visitor"
• FR-008: Create Attendance record linked to Member
• FR-009: Redirect to thank you page on successful submission
• FR-010: Handle errors gracefully with error page

3.1.3 Member Check-In

• FR-011: Capture member information (same fields as visitor)
• FR-012: Look up existing member by email address
• FR-013: If member not found, create new Member record
• FR-014: If member found, use existing Member record
• FR-015: Create Attendance record linked to Member
• FR-016: Support "Remember Me" functionality
• FR-017: Store device hash when "Remember Me" is enabled
• FR-018: Auto-populate email on return visits when device is recognized

3.1.4 Sunday-Only Check-In

• FR-019: Display "Not Sunday" screen on non-Sunday days (configurable)
• FR-020: Prevent check-in submissions on restricted days

3.2 Administrative Features

3.2.1 Member Management

• FR-021: Display paginated list of all members
• FR-022: Search/filter members by:
  • Name (firstName, lastName)
  • Email (primaryEmail)
  • Member status
• FR-023: Sort members by any column
• FR-024: Create new member records manually
• FR-025: Edit existing member information
• FR-026: Delete member records (with confirmation)
• FR-027: View member attendance history

3.2.2 Attendance Tracking

• FR-028: Display attendance records with filters:
  • Date range
  • Member
  • Visitor count
• FR-029: Export attendance data
• FR-030: View aggregate statistics:
  • Total attendance by date
  • Visitor vs member counts
  • Attendance trends

3.2.3 Data Import

• FR-031: Support CSV file upload for member import
• FR-032: Parse and validate imported data
• FR-033: Match imported records to existing members by email
• FR-034: Display import preview with status indicators:
  • Found (existing member)
  • Not Found (new member)
  • Errors
• FR-035: Process import with option to:
  • Create new members
  • Update existing members
  • Skip duplicates
• FR-036: Trigger serverless function on S3 file upload for processing

3.2.4 Settings Management

• FR-037: Configure system-wide settings:
  • Home screen layout preference
  • Contact phone number
  • Contact SMS message template
  • Enable/disable Sunday-only restriction
  • Other configurable features
• FR-038: Store settings as key-value pairs
• FR-039: Apply settings dynamically without redeployment

3.3 Help System

• FR-040: Display help documentation with screenshots
• FR-041: Provide step-by-step check-in instructions
• FR-042: Include troubleshooting information

4. Data Models

4.1 Member

{
  id: string (UUID)
  label: string // Full name display
  firstName: string
  lastName: string
  primaryEmail: string (unique, indexed)
  memberStatus: string // "Member" | "Visitor" | other
  createdAt: timestamp
  updatedAt: timestamp
  
  // Relationships
  attendance: Attendance[] // One-to-many
  devices: MemberDevice[] // One-to-many
}

Indexes:

• Primary: id
• GSI: lastName + primaryEmail (for efficient lookup)

4.2 Attendance

{
  id: string (UUID)
  date: timestamp (ISO 8601)
  visitors: number // Count of people checking in
  Phone: string (optional)
  MoreInformation: boolean
  ContactThem: boolean
  Hear: string // How they heard about the church
  OtherInput: string (optional)
  createdAt: timestamp
  updatedAt: timestamp
  
  // Foreign Keys
  memberAttendanceId: string
  attendanceMemberId: string
  // Relationship
  member: Member // Many-to-one
}

4.3 MemberDevice

{
  id: string (UUID)
  deviceUUID: string (hashed) // MD5 hash of email + salt
  createdAt: timestamp
  updatedAt: timestamp
  
  // Foreign Keys
  memberDevicesId: string
  memberDeviceMemberId: string
  // Relationship
  member: Member // Many-to-one
}

4.4 ChurchSettings

{
  id: string (UUID)
  key: string // Setting identifier
  value: string // Setting value (JSON serializable)
  createdAt: timestamp
  updatedAt: timestamp
}

Common Settings:

• homeScreen: "A" | "B" | "C"
• contact_num: Phone number
• contact_msg: SMS message template
• features.sundayOnly: boolean

4.5 ErrorLog

{
  id: string (UUID)
  input: JSON // Request that caused error
  error: JSON // Error details
  createdAt: timestamp
  updatedAt: timestamp
}

5. Technical Requirements

5.1 Frontend Technology Stack

Current (for Migration)

• Vue 3 with TypeScript
• Vite build tool
• Vue Router for navigation
• Pinia for state management
• PrimeVue UI component library
• Composables: @vueuse/core

Proposed (for Rewrite)

• SvelteKit with TypeScript
• Svelte stores for state management
• SvelteKit routing (built-in)
• shadcn-svelte or similar UI library
• Vite (included with SvelteKit)

5.2 Backend Requirements

Current: AWS Amplify

• AWS AppSync (GraphQL API)
• Amazon Cognito (Authentication)
• Amazon DynamoDB (Database)
• Amazon S3 (File Storage)
• AWS Lambda (Serverless Functions)

Proposed: Vercel + Supabase

• Supabase PostgreSQL (Database)
• Supabase Auth (Authentication)
• Supabase Storage (File Storage)
• Vercel Serverless Functions (API Routes)
• Supabase Realtime (optional, for live updates)

5.3 API Requirements

5.3.1 Public API Endpoints (No Auth)

• POST /api/checkin/visitor - Create visitor attendance
• POST /api/checkin/member - Create member attendance
• GET /api/device/:hash - Check if device is remembered
• GET /api/settings/public - Get public settings

5.3.2 Admin API Endpoints (Authenticated)

• GET /api/members - List members (paginated, filterable)
• POST /api/members - Create member
• PUT /api/members/:id - Update member
• DELETE /api/members/:id - Delete member
• GET /api/members/:id - Get member details
• GET /api/attendance - List attendance (filtered)
• POST /api/import/members - Upload member import file
• GET /api/import/status/:id - Check import status
• GET /api/settings - Get all settings
• PUT /api/settings - Update settings
• POST /api/export/attendance - Generate attendance export

5.4 Serverless Functions

Function 1: Member Import Processor

• Trigger: File upload to storage bucket
• Purpose: Process CSV import files
• Operations:
  • Parse CSV data
  • Validate entries
  • Match to existing members
  • Create/update database records
  • Generate status report

Function 2: Data Export

• Trigger: Manual API call
• Purpose: Generate attendance reports
• Operations:
  • Query attendance data with filters
  • Format as CSV/Excel
  • Upload to storage
  • Return download link

5.5 Database Schema (PostgreSQL)

-- Members table
CREATE TABLE members (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  label TEXT NOT NULL,
  first_name TEXT NOT NULL,
  last_name TEXT NOT NULL,
  primary_email TEXT UNIQUE NOT NULL,
  member_status TEXT NOT NULL,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE INDEX idx_members_email ON members(primary_email);
CREATE INDEX idx_members_name ON members(last_name, first_name);
-- Attendance table
CREATE TABLE attendance (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  date TIMESTAMPTZ NOT NULL,
  visitors INTEGER NOT NULL,
  phone TEXT,
  more_information BOOLEAN DEFAULT FALSE,
  contact_them BOOLEAN DEFAULT FALSE,
  hear TEXT,
  other_input TEXT,
  member_id UUID REFERENCES members(id) ON DELETE CASCADE,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW()
);
CREATE INDEX idx_attendance_date ON attendance(date DESC);
CREATE INDEX idx_attendance_member ON attendance(member_id);
-- Member Devices table
CREATE TABLE member_devices (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  device_uuid TEXT UNIQUE NOT NULL,
  member_id UUID REFERENCES members(id) ON DELETE CASCADE,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW()
);
CREATE INDEX idx_member_devices_uuid ON member_devices(device_uuid);
-- Church Settings table
CREATE TABLE church_settings (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  key TEXT UNIQUE NOT NULL,
  value TEXT NOT NULL,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW()
);
-- Error Logs table
CREATE TABLE error_logs (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  input JSONB,
  error JSONB,
  created_at TIMESTAMPTZ DEFAULT NOW()
);
-- Enable Row Level Security
ALTER TABLE members ENABLE ROW LEVEL SECURITY;
ALTER TABLE attendance ENABLE ROW LEVEL SECURITY;
ALTER TABLE member_devices ENABLE ROW LEVEL SECURITY;
ALTER TABLE church_settings ENABLE ROW LEVEL SECURITY;
ALTER TABLE error_logs ENABLE ROW LEVEL SECURITY;
-- Policies for public access (read-only settings)
CREATE POLICY "Public settings are viewable by everyone"
  ON church_settings FOR SELECT
  USING (key LIKE 'public_%');
-- Policies for authenticated admin users
CREATE POLICY "Admins have full access to members"
  ON members FOR ALL
  USING (auth.role() = 'authenticated');
-- Anonymous users can insert attendance
CREATE POLICY "Anyone can create attendance"
  ON attendance FOR INSERT
  WITH CHECK (true);

5.6 Authentication & Authorization

Admin Access

• Authentication Method: Email/Password via Supabase Auth
• Roles: Admin role for full system access
• Protected Routes:
  • /admin/* - All admin pages
  • Admin API endpoints

Public Access

• No authentication required for check-in flows
• Rate limiting on public endpoints to prevent abuse

6. Non-Functional Requirements

6.1 Performance

• NFR-001: Page load time < 2 seconds
• NFR-002: Check-in form submission < 1 second
• NFR-003: Admin list views load < 3 seconds (with pagination)
• NFR-004: Support 100 concurrent users during service times

6.2 Security

• NFR-005: All API communication over HTTPS
• NFR-006: Implement CSRF protection
• NFR-007: Sanitize all user inputs
• NFR-008: Hash device identifiers (MD5 with salt)
• NFR-009: Implement rate limiting on public endpoints
• NFR-010: Admin routes require authentication
• NFR-011: Encrypt sensitive data at rest

6.3 Reliability

• NFR-012: 99.9% uptime during service hours (Sunday mornings)
• NFR-013: Graceful error handling with user-friendly messages
• NFR-014: Automatic error logging for troubleshooting
• NFR-015: Database backups daily

6.4 Usability

• NFR-016: Mobile-responsive design (primary use case)
• NFR-017: Large touch targets for mobile (min 44x44px)
• NFR-018: Accessible (WCAG 2.1 AA compliance)
• NFR-019: Clear visual feedback on form submission
• NFR-020: Help documentation easily accessible

6.5 Maintainability

• NFR-021: Code documented with inline comments
• NFR-022: TypeScript for type safety
• NFR-023: Consistent code formatting (Prettier/ESLint)
• NFR-024: Component-based architecture
• NFR-025: Environment-based configuration

6.6 Scalability

• NFR-026: Database designed to handle 10,000+ member records
• NFR-027: Attendance records for 5+ years
• NFR-028: Serverless functions auto-scale with demand

7. UI/UX Requirements

7.1 Mobile-First Design

• UI-001: Optimize for mobile devices (primary use case: tablets at check-in kiosks)
• UI-002: Support touch interactions with large tap targets (minimum 44x44px)
• UI-003: Responsive layout adapting to phone, tablet, and desktop screens

7.2 Check-In Screens

• UI-004: Home screen with clear visual hierarchy
• UI-005: Custom button styling with gradient and shadow effects
• UI-006: "Welcome" badge for first-time visitors (optional based on layout)
• UI-007: Fixed footer with "Let's Connect" and "Help" buttons

7.3 Form Design

• UI-008: Clear form labels and input fields
• UI-009: Visual validation feedback (red for errors, green for success)
• UI-010: Progress indicator during form submission
• UI-011: Prevent accidental form resubmission

7.4 Admin Interface

• UI-012: Data tables with sorting, filtering, and pagination
• UI-013: PrimeVue components for consistent UI
• UI-014: Sidebar navigation for admin sections
• UI-015: Dashboard with key metrics and statistics

7.5 Branding

• UI-016: Display church logo/branding
• UI-017: Configurable color scheme
• UI-018: Consistent typography throughout

8. User Flows

8.1 First-Time Visitor Flow

1. User arrives at home screen
2. Selects "Visitor" button
3. Completes check-in form:
   • Enters full name
   • Enters email address
   • Enters number of attendees
   • Optionally enters phone number
   • Selects how they heard about the church
   • Optionally checks "would like more information"
   • Optionally checks "may we contact you"
4. Submits form
5. System creates Member record (status: "Visitor")
6. System creates Attendance record
7. Redirected to "Thank You" page
8. Can return to home or access help

8.2 Returning Member Flow

1. User arrives at home screen
2. Selects "Member" or "Regular Attendee" button
3. Completes check-in form
4. System looks up member by email
5. If found: Links attendance to existing member
6. If not found: Creates new member record
7. Optionally checks "Remember Me"
8. If "Remember Me": System stores device hash
9. Redirected to "Thank You" page

8.3 Remembered Device Flow

1. User arrives at home screen on remembered device
2. Selects "Member" button
3. Email is pre-populated based on device hash
4. User confirms/edits information
5. Completes remaining form fields
6. Submits and redirects to "Thank You" page

8.4 Admin Member Management Flow

1. Admin logs in
2. Navigates to Members page
3. Views paginated list of members
4. Can search/filter by name, email, or status
5. Can sort by any column
6. Clicks on member to view details
7. Can edit member information
8. Can view member's attendance history
9. Can delete member (with confirmation)

8.5 Admin Import Flow

1. Admin logs in
2. Navigates to Import page
3. Uploads CSV file
4. System parses and validates data
5. Displays preview with status indicators
6. Admin reviews and confirms import
7. System processes records
8. Shows success/error summary
9. Can download error report if issues occurred

9. Migration/Implementation Paths

9.1 Option A: Migrate to Vercel + Supabase (Keep Vue)

Phase 1: Backend Setup (Days 1-3)

1. Create Supabase project
2. Set up PostgreSQL database schema
3. Configure Row Level Security policies
4. Migrate DynamoDB data to PostgreSQL
5. Set up Supabase Auth for admin users
6. Configure Supabase Storage buckets

Phase 2: API Migration (Days 4-7)

1. Replace GraphQL queries with Supabase client calls
2. Update authentication logic (Cognito → Supabase Auth)
3. Rewrite serverless functions as Vercel API routes
4. Update file upload logic for Supabase Storage
5. Test all API endpoints

Phase 3: Frontend Updates (Days 8-10)

1. Replace aws-amplify with @supabase/supabase-js
2. Update environment variables
3. Update API calls in Vue components
4. Update authentication flows
5. Update file upload components
6. Test all user flows

Phase 4: Deployment & Testing (Days 11-14)

1. Set up Vercel project
2. Configure environment variables
3. Deploy to staging environment
4. Perform thorough testing
5. Fix any issues
6. Deploy to production
7. Monitor and verify

Estimated Total: 2-3 weeks

9.2 Option B: Rewrite with SvelteKit + Vercel + Supabase

Phase 1: Backend Setup (Days 1-3)

• Same as Option A

Phase 2: Project Setup (Days 4-5)

1. Initialize SvelteKit project
2. Set up TypeScript
3. Configure Supabase client
4. Set up routing structure
5. Install UI component library
6. Configure build tools

Phase 3: Public Screens (Days 6-12)

1. Create home screen with layout variants
2. Build visitor check-in form
3. Build member check-in form
4. Create thank you page
5. Create help page
6. Create error page
7. Implement "Remember Me" functionality
8. Style with Tailwind/component library

Phase 4: Admin Interface (Days 13-22)

1. Set up authentication
2. Create admin layout
3. Build Members list page
4. Build Member detail/edit page
5. Build Attendance tracking page
6. Build Import page
7. Build Settings page
8. Build Export functionality
9. Style and test all admin features

Phase 5: API Routes & Functions (Days 23-25)

1. Create public API endpoints
2. Create admin API endpoints
3. Implement serverless functions
4. Add rate limiting and security

Phase 6: Testing & Deployment (Days 26-30)

1. Write unit tests
2. Perform integration testing
3. Test on multiple devices
4. Fix bugs
5. Deploy to staging
6. User acceptance testing
7. Deploy to production

Estimated Total: 4-6 weeks

10. Success Criteria

10.1 Functional Success

• ✅ All 42 functional requirements met
• ✅ Public check-in flow works without authentication
• ✅ Admin features work with proper authentication
• ✅ Data import/export functions correctly
• ✅ "Remember Me" device recognition works
• ✅ All configurable settings apply correctly

10.2 Technical Success

• ✅ Database properly structured with relationships
• ✅ API endpoints respond within performance targets
• ✅ Authentication and authorization work correctly
• ✅ File uploads process successfully
• ✅ Error handling works gracefully

10.3 Performance Success

• ✅ Page loads < 2 seconds
• ✅ Form submissions < 1 second
• ✅ Handles 100 concurrent users
• ✅ Admin queries with pagination perform well

10.4 User Experience Success

• ✅ Mobile interface is intuitive and easy to use
• ✅ Check-in process takes < 1 minute for visitors
• ✅ Check-in process takes < 30 seconds for returning members
• ✅ Admin interface is efficient and easy to navigate
• ✅ Help documentation is clear and accessible

10.5 Business Success

• ✅ Reduce check-in time by 50% compared to manual process
• ✅ Capture accurate attendance data for reporting
• ✅ Increase visitor engagement through follow-up capabilities
• ✅ Reduce administrative overhead for managing member data
• ✅ Enable data-driven decision making with attendance analytics

11. Out of Scope (Future Enhancements)

The following features are not included in the initial implementation but could be considered for future releases:

11.1 Advanced Features

• Real-time attendance dashboard for leadership
• Email/SMS notifications to visitors and members
• Integration with church management software (Planning Center, ChMS)
• Multi-site support for churches with multiple campuses
• Child check-in with printed security labels
• QR code check-in for faster member check-in
• Automated follow-up workflows

11.2 Analytics & Reporting

• Attendance trend analysis with charts
• First-time visitor retention tracking
• Geographic mapping of attendees
• Custom report builder
• Predictive attendance forecasting

11.3 Mobile Apps

• Native iOS/Android apps for check-in
• Offline mode for network interruptions
• Push notifications

12. Assumptions & Dependencies

12.1 Assumptions

• Primary users will use tablets provided at check-in kiosks
• Internet connectivity will be available at all times
• Admin users have basic computer literacy
• Church has existing member data that can be exported to CSV
• Email addresses are unique identifiers for members
• Check-in primarily happens on Sunday mornings

12.2 Dependencies

• Supabase account and project
• Vercel account for deployment
• Domain name for production deployment
• SSL certificate (included with Vercel)
• CSV export capability from current member management system
• Admin user accounts created in Supabase Auth

12.3 External Services

• Supabase (database, auth, storage)
• Vercel (hosting, serverless functions)
• Email service for notifications (future)
• SMS gateway for contact button (native device SMS)

13. Risks & Mitigation

13.1 Technical Risks

13.2 User Adoption Risks

13.3 Business Risks

14. Maintenance & Support

14.1 Ongoing Maintenance

• Database Backups: Daily automated backups via Supabase
• Security Updates: Monitor dependencies, update monthly
• Performance Monitoring: Use Vercel Analytics + Supabase metrics
• Error Tracking: Review error logs weekly
• User Support: Help documentation + admin contact email

14.2 Support Channels

• In-app help documentation
• Admin email support
• Optional: Paid support contract for custom changes

14.3 SLA Targets

• Uptime: 99.9% (excluding planned maintenance)
• Support Response: Within 24 hours for critical issues
• Bug Fixes: Critical bugs within 48 hours, minor within 2 weeks
• Feature Requests: Reviewed quarterly

15. Appendix

15.1 Glossary

• Check-In: The process of recording attendance
• Member: Person with an existing record in the system
• Visitor: First-time or occasional attendee
• Device Hash: MD5 hash used for "Remember Me" functionality
• RLS: Row Level Security (PostgreSQL security feature)
• GSI: Global Secondary Index (DynamoDB concept, maps to PostgreSQL index)

15.2 References

• Supabase Documentation
• SvelteKit Documentation
• Vue 3 Documentation
• Vercel Documentation
• PostgreSQL Documentation

15.3 Document History

16. Approval

This requirements document should be reviewed and approved by:

• Church Leadership (Project Sponsor)
• Technical Lead
• Key Stakeholders (Admin Users)
• Development Team

Sign-off indicates agreement that these requirements accurately represent the needs of the church check-in system and serve as the basis for either migration or rewrite.

End of Requirements Document