# 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:

1. System creates unclaimed account
2. Confirmation email includes "Claim Account" link
3. User sets password or links Google
4. 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
* Email
* 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
* email
* 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.
