6.3 KiB
Spanglish Website – User Accounts & Dashboard Specification
1. Purpose
This document defines the complete user account system, authentication methods, identity management, and user dashboard features for the Spanglish platform.
It ensures that all bookings are linked to user accounts while keeping the booking process frictionless.
The system supports both casual users and long-term community members.
2. Core Principles
- Every booking is linked to a user account
- Account creation must not block booking
- Authentication must be flexible
- Email is the primary identifier
- Users own their data and history
- Financial transparency is mandatory
- Administrative users can manage and resolve conflicts
3. User Account Model
3.1 Progressive Accounts
Spanglish uses a progressive account system.
Users are created automatically during booking using their email address.
These accounts are initially marked as unclaimed and can be activated later.
This allows first-time users to book without registration.
3.2 User States
Each user account has one of the following states:
- Unclaimed: Created during booking, no login configured
- Claimed: User has activated login
- Suspended: Disabled by admin
3.3 User Identity Fields
Each user record contains:
- id (UUID)
- name
- email (unique)
- phone
- password_hash (nullable)
- google_id (nullable)
- is_claimed (boolean)
- ruc_number (nullable)
- created_at
- updated_at
Email is the primary identity key.
4. Authentication Methods
4.1 Password Authentication
Users may optionally set a password.
Passwords are never required for booking.
Requirements:
- Minimum 10 characters
- Argon2 hashing
- Reset via email
4.2 Google Login (OAuth)
Users may authenticate using Google.
Behavior:
- Email is verified by Google
- Existing accounts are matched by email
- Google ID is linked on first login
4.3 Email Code / Magic Link
Users may log in using one-time codes or magic links.
Behavior:
- Code expires in 10 minutes
- One-time use only
- Sent to registered email
5. Account Claiming Flow
When a user books without logging in:
- System creates unclaimed account
- Confirmation email includes "Claim Account" link
- User sets password or links Google
- Account becomes claimed
This process is optional but encouraged.
6. Booking to User Linking
During booking:
- Email is mandatory
- System searches for existing user
- If found, booking is linked
- If not found, new user is created
All tickets are linked to user_id.
No orphan records are allowed.
7. Multiple Ticket Management
7.1 Single User, Multiple Events
Users may book unlimited events.
Each booking creates a separate ticket record.
7.2 Group Bookings
Users may purchase multiple tickets per booking.
Behavior:
- One user_id owns all tickets
- Guest names are optional
- Tickets may be reassigned later
8. RUC & Invoice Management
8.1 RUC Collection
During booking, users may optionally provide:
- Paraguayan RUC number
- Legal name (optional)
This data is stored in the user profile and booking record.
8.2 Invoice Generation
When a booking is marked as Paid:
- System generates a fiscal invoice
- Invoice includes RUC data
- Invoice is stored as PDF
- Invoice is linked to payment record
Invoices are immutable after generation.
8.3 Invoice Access
From the dashboard, users may:
- View invoices
- Download PDF invoices
- Access invoice history
Only confirmed and paid bookings generate invoices.
9. User Dashboard
9.1 Access
Dashboard URL:
/dashboard
Authentication required.
9.2 Dashboard Sections
9.2.1 Welcome Panel
Displays:
- User name
- Account status
- Membership duration
9.2.2 Next Event Panel
Displays:
- Upcoming event
- Date and time
- Location
- Payment status
Actions:
- View ticket
- Open map
- Add to calendar
9.2.3 My Tickets
Displays all tickets:
- Event name
- Date
- Payment method
- Status
- Invoice link (if available)
Tickets link to detail view.
9.2.4 Payments & Invoices
Displays:
- Payment history
- Pending approvals
- Downloadable invoices
- Payment references
9.2.5 Community Access
Displays:
- WhatsApp group link
- Instagram link
- Website link
Links are managed by admin.
9.2.6 Profile Settings
Users may edit:
- Name
- Phone
- Preferred language
- RUC number
Email changes require verification.
9.2.7 Security Settings
Users may:
- Set or change password
- Link / unlink Google account
- View active sessions
- Logout all sessions
9.2.8 Support Panel
Includes:
- Contact links
- FAQ
- Support form
10. Ticket Detail View
Each ticket page includes:
- Ticket ID
- QR code (optional)
- Event details
- Payment status
- Invoice download
- Check-in status
11. Admin User Management
Admins may:
- View all users
- Edit profiles
- Reset authentication
- Merge duplicate accounts
- Suspend users
- Edit RUC data
All actions are logged.
12. Data Protection & Privacy
- GDPR-style data rights
- Data export on request
- Account deletion support
- Secure storage
- Encrypted credentials
13. Notifications
Users receive system notifications for:
- Booking confirmation
- Payment approval
- Invoice generation
- Account security changes
Notifications are delivered via email.
14. Database Tables (Core)
users
- id
- name
- phone
- password_hash
- google_id
- is_claimed
- ruc_number
- created_at
tickets
- id
- user_id
- event_id
- status
- created_at
payments
- id
- ticket_id
- status
- amount
- reference
invoices
- id
- payment_id
- pdf_url
- ruc_number
- created_at
15. Security Requirements
- Argon2 password hashing
- OAuth verification
- Rate-limited login
- Brute-force protection
- Secure cookies
- HTTPS enforced
16. Future Extensions
Planned enhancements:
- Loyalty tiers
- Membership subscriptions
- Family accounts
- Corporate accounts
- Tax reporting exports
- Mobile app support
17. Summary
The Spanglish user system provides frictionless onboarding, strong identity management, and full financial transparency.
It supports both casual participants and professional users who require invoices and account history.
All implementations must follow this specification.