first commit

about/FUNCTIONAL_SPEC.md

@@ -0,0 +1,417 @@
+# Spanglish Website – Functional Specification
+
+## 1. Purpose
+
+This document defines the functional behavior of the Spanglish website and admin system.
+
+It specifies what the system must do, how users interact with it, and how core workflows operate.
+
+---
+
+## 2. User Roles
+
+### 2.1 Public User
+
+* Can browse the website
+* Can view events
+* Can book tickets
+* Can join community channels
+* Can contact organizers
+
+### 2.2 Admin
+
+* Full system access
+* Manages events
+* Manages users
+* Manages payments
+* Manages communications
+* Manages settings
+
+### 2.3 Organizer
+
+* Manages assigned events
+* Views attendees
+* Sends event emails
+* Manages check-in
+
+### 2.4 Staff
+
+* Access to check-in system
+* Limited attendee viewing
+
+### 2.5 Marketing
+
+* Access to email tools
+* Access to analytics
+* Access to media library
+
+---
+
+## 3. Public Website Features
+
+### 3.1 Homepage
+
+The homepage must display:
+
+* Hero section with next event
+* Primary call-to-action button
+* Brief description of Spanglish
+* Photo gallery
+* Community links
+* Email signup form
+* Contact information
+
+Behavior:
+
+* Automatically shows the next upcoming event
+* Updates dynamically when events change
+
+---
+
+### 3.2 Events Listing Page
+
+The events page must display:
+
+* List of upcoming events
+* List of past events
+* Basic filtering by date
+
+Each event card shows:
+
+* Title
+* Date
+* Location
+* Status
+* Booking button
+
+---
+
+### 3.3 Event Detail Page
+
+Each event page must include:
+
+* Event title
+* Description
+* Date and time
+* Location with map
+* Price
+* Available seats
+* Booking button
+* FAQ section
+* Social sharing buttons
+
+Behavior:
+
+* Booking disabled when sold out
+* Status shown when cancelled
+
+---
+
+### 3.4 Community Page
+
+The community page must include:
+
+* WhatsApp invite links
+* Instagram link
+* Participation guidelines
+* Volunteer information
+
+---
+
+### 3.5 Contact Page
+
+The contact page must include:
+
+* Contact form
+* Email address
+* Social media links
+
+Behavior:
+
+* Form submissions stored in database
+* Admin receives notification
+
+---
+
+## 4. Booking System
+
+### 4.1 Booking Flow
+
+1. User clicks "Join" on event page
+2. Booking form is displayed
+3. User enters personal details
+4. User selects payment method
+5. Payment is processed or recorded
+6. Ticket is generated
+7. Confirmation is sent
+8. User appears in admin system
+
+---
+
+### 4.2 Booking Form
+
+The booking form collects:
+
+* Full name
+* Email address
+* Phone number
+* Language preference (optional)
+* Payment method
+
+Validation:
+
+* Email format check
+* Required field validation
+* Duplicate booking prevention
+
+---
+
+### 4.3 Ticket Generation
+
+After successful booking:
+
+* Unique ticket ID is generated
+* Ticket linked to user and event
+* QR code created (optional)
+* Ticket stored in database
+
+---
+
+## 5. Payment Management
+
+### 5.1 Supported Payment Methods
+
+Initial support:
+
+* Stripe / MercadoPago
+* Bank transfer
+* Cash (manual entry)
+
+Future support:
+
+* Lightning
+* Cashu
+* Nostr payments
+
+---
+
+### 5.2 Payment Workflow
+
+* Payment initiated during booking
+* Payment status tracked
+* Manual confirmation supported
+* Refunds supported
+
+Statuses:
+
+* Pending
+* Paid
+* Refunded
+* Failed
+
+---
+
+## 6. Admin Dashboard
+
+### 6.1 Dashboard Overview
+
+The main dashboard displays:
+
+* Upcoming events
+* Ticket sales
+* Revenue summary
+* Pending payments
+* Alerts
+
+---
+
+### 6.2 Event Management Module
+
+Features:
+
+* Create event
+* Edit event
+* Publish event
+* Archive event
+* Duplicate event
+
+Event fields:
+
+* Title
+* Description
+* Date
+* Time
+* Location
+* Price
+* Capacity
+* Banner image
+* Status
+
+---
+
+### 6.3 Ticket Management Module
+
+Features:
+
+* View attendee list
+* Search attendees
+* Edit attendee info
+* Manual ticket creation
+* Cancel tickets
+* Export CSV
+* Check-in system
+
+Check-in:
+
+* Manual toggle
+* QR scanning (optional)
+* Timestamp logging
+
+---
+
+### 6.4 Payment Management Module
+
+Features:
+
+* View transactions
+* Manual payment entry
+* Refund processing
+* Revenue reports
+* Export financial data
+
+---
+
+### 6.5 Email & Messaging Module
+
+Features:
+
+* Email templates
+* Mass mailing
+* Automated reminders
+* Event notifications
+* Contact segmentation
+
+Automated emails:
+
+* Booking confirmation
+* Event reminder
+* Cancellation notice
+* Post-event follow-up
+
+---
+
+### 6.6 Community Management Module
+
+Features:
+
+* User profiles
+* Attendance history
+* Notes system
+* Tagging
+* Segmentation
+
+---
+
+### 6.7 Media Management Module
+
+Features:
+
+* Upload images
+* Organize galleries
+* Assign images to events
+* Homepage gallery management
+
+---
+
+### 6.8 Role & Permission Management
+
+Features:
+
+* Create roles
+* Assign permissions
+* Assign users to roles
+* Audit access
+
+---
+
+## 7. Reporting & Analytics
+
+The system must provide:
+
+* Event attendance reports
+* Revenue reports
+* User growth reports
+* Conversion metrics
+* Email engagement statistics
+
+---
+
+## 8. Error Handling
+
+The system must handle:
+
+* Failed payments
+* Overbooking attempts
+* Network failures
+* Invalid input
+* Unauthorized access
+
+Behavior:
+
+* Display user-friendly messages
+* Log technical errors
+* Notify admins when critical
+
+---
+
+## 9. Notifications
+
+System notifications include:
+
+* New booking alerts
+* Payment failures
+* Low capacity warnings
+* System errors
+
+Delivery channels:
+
+* Email
+* Admin dashboard alerts
+  n
+
+---
+
+## 10. Audit Logging
+
+The system must record:
+
+* Admin actions
+* Payment changes
+* Event modifications
+* User updates
+
+Logs must include:
+
+* Timestamp
+* User ID
+* Action type
+* Target record
+
+---
+
+## 11. Accessibility
+
+The public website must:
+
+* Support mobile devices
+* Provide readable fonts
+* Support screen readers
+* Maintain color contrast
+
+---
+
+## 12. Summary
+
+This functional specification defines the operational behavior of the Spanglish platform.
+
+All implemented features must comply with this document to ensure consistency, reliability, and scalability.

about/TECH_SPEC.md

@@ -0,0 +1,339 @@
+# Spanglish Website – Technical Specification
+
+## 1. Purpose
+
+This document defines the technical architecture, technology stack, and implementation guidelines for the Spanglish website and admin system.
+
+It serves as the reference for developers responsible for building, deploying, and maintaining the platform.
+
+---
+
+## 2. System Architecture
+
+### 2.1 High-Level Architecture
+
+The system follows a client-server architecture:
+
+Browser (Public/Admin)
+→ Frontend Application
+→ Backend API
+→ Database
+→ External Services
+
+External services include payment providers and email delivery systems.
+
+---
+
+### 2.2 Component Overview
+
+* Frontend: Public website and admin interface
+* Backend: REST API and business logic
+* Database: Central data storage
+* Payment Services: External processors
+* Email Service: Transactional and bulk email
+* Media Storage: Image and file storage
+
+---
+
+## 3. Technology Stack
+
+### 3.1 Frontend
+
+* Framework: Next.js (React)
+* Styling: Tailwind CSS
+* State Management: React Context / Query
+* Build Tool: Vite / Next Build
+* Image Optimization: Next Image
+
+### 3.2 Backend
+
+* Framework: FastAPI (Python)
+* API Style: REST
+* Authentication: JWT
+* ORM: SQLAlchemy
+* Validation: Pydantic
+
+### 3.3 Database
+
+* System: PostgreSQL
+* Migration Tool: Alembic
+* Backup: Automated daily backups
+
+### 3.4 Infrastructure
+
+* Hosting: VPS (Linux)
+* Reverse Proxy: Nginx
+* SSL: Let’s Encrypt
+* CDN: Optional (Cloudflare)
+* Containerization: Docker
+
+### 3.5 External Services
+
+* Payments: Stripe / MercadoPago
+* Email: Resend / Postmark / Mailgun
+* Analytics: Plausible / GA
+
+---
+
+## 4. Database Design
+
+### 4.1 Core Tables
+
+#### users
+
+* id (UUID)
+* name
+* email
+* phone
+* role
+* created_at
+* updated_at
+
+#### events
+
+* id (UUID)
+* title
+* description
+* start_datetime
+* end_datetime
+* location
+* price
+* capacity
+* status
+* banner_url
+* created_at
+
+#### tickets
+
+* id (UUID)
+* user_id
+* event_id
+* status
+* checkin_at
+* created_at
+
+#### payments
+
+* id (UUID)
+* ticket_id
+* provider
+* amount
+* currency
+* status
+* reference
+* created_at
+
+#### emails
+
+* id (UUID)
+* user_id
+* subject
+* body
+* status
+* sent_at
+
+#### media
+
+* id (UUID)
+* file_url
+* type
+* related_id
+* created_at
+
+#### audit_logs
+
+* id (UUID)
+* user_id
+* action
+* target
+* timestamp
+
+---
+
+## 5. API Design
+
+### 5.1 Authentication
+
+POST /api/auth/login
+POST /api/auth/refresh
+POST /api/auth/logout
+
+JWT tokens are used for session management.
+
+---
+
+### 5.2 Event Endpoints
+
+GET /api/events
+GET /api/events/{id}
+POST /api/events
+PUT /api/events/{id}
+DELETE /api/events/{id}
+
+---
+
+### 5.3 Ticket Endpoints
+
+POST /api/tickets
+GET /api/tickets/{id}
+GET /api/events/{id}/tickets
+PUT /api/tickets/{id}
+
+---
+
+### 5.4 Payment Endpoints
+
+POST /api/payments/initiate
+POST /api/payments/webhook
+GET /api/payments/{id}
+POST /api/payments/refund
+
+---
+
+### 5.5 User & Community Endpoints
+
+GET /api/users
+GET /api/users/{id}
+PUT /api/users/{id}
+GET /api/users/{id}/history
+
+---
+
+### 5.6 Media Endpoints
+
+POST /api/media/upload
+GET /api/media/{id}
+DELETE /api/media/{id}
+
+---
+
+## 6. Authentication & Authorization
+
+* JWT-based authentication
+* Refresh tokens
+* Role-based access control
+* Password hashing (bcrypt/argon2)
+* Optional OAuth/Nostr integration
+
+---
+
+## 7. Security
+
+### 7.1 Application Security
+
+* Input validation
+* CSRF protection
+* CORS policies
+* Rate limiting
+* SQL injection prevention
+
+### 7.2 Infrastructure Security
+
+* Firewall rules
+* Fail2ban
+* Encrypted backups
+* Secure secrets storage
+
+---
+
+## 8. Deployment
+
+### 8.1 Environment Structure
+
+* Development
+* Staging
+* Production
+
+Each environment uses separate databases and credentials.
+
+---
+
+### 8.2 Deployment Process
+
+1. Build frontend
+2. Build backend container
+3. Run database migrations
+4. Deploy containers
+5. Reload Nginx
+6. Verify health checks
+
+---
+
+### 8.3 CI/CD (Optional)
+
+* GitHub Actions
+* Automated testing
+* Automated deployment
+
+---
+
+## 9. Monitoring & Logging
+
+* Application logs
+* Error tracking
+* Performance monitoring
+* Uptime monitoring
+
+Recommended tools:
+
+* Sentry
+* Prometheus
+* Grafana
+* Uptime Kuma
+
+---
+
+## 10. Backup & Recovery
+
+* Daily database backups
+* Weekly full backups
+* Offsite storage
+* Restore testing
+
+---
+
+## 11. Performance Optimization
+
+* Database indexing
+* Query optimization
+* CDN caching
+* Image compression
+* Lazy loading
+
+---
+
+## 12. Development Guidelines
+
+* Follow PEP8 (Backend)
+* Use type hints
+* Write unit tests
+* Document endpoints
+* Use environment variables
+
+---
+
+## 13. Versioning & Updates
+
+* Semantic versioning
+* Backward-compatible APIs
+* Migration scripts
+* Change logs
+
+---
+
+## 14. Future Extensions
+
+* Mobile application
+* Membership system
+* Lightning integration
+* Cashu payments
+* Nostr identity
+* Multi-city deployment
+
+---
+
+## 15. Summary
+
+This technical specification defines the architecture and implementation standards for the Spanglish platform.
+
+All development must follow this document to ensure security, maintainability, and scalability.

about/booking_fow.md

@@ -0,0 +1,368 @@
+# Spanglish Website – Booking & Payment Flow
+
+## 1. Purpose
+
+This document defines the complete booking and payment flow for Spanglish events.
+
+It ensures a fast, reliable, and user-friendly process for participants and a clear management workflow for organizers.
+
+The system supports the following payment methods:
+
+* TPago / Bancard (Credit & Debit Cards)
+* Bitcoin Lightning (BTCPay)
+* Cash at Event
+
+---
+
+## 2. Core Objectives
+
+The booking system must:
+
+* Allow users to reserve a seat in under 60 seconds
+* Minimize drop-off during payment
+* Provide clear confirmation
+* Support mobile-first usage
+* Reduce manual coordination
+* Integrate cleanly with the admin dashboard
+
+---
+
+## 3. High-Level Booking Flow
+
+1. User visits an event page
+2. User clicks "Join Event"
+3. Booking page opens
+4. User enters personal details
+5. User selects payment method
+6. Payment or reservation is processed
+7. Ticket is generated
+8. Confirmation is sent
+9. User appears in admin dashboard
+
+---
+
+## 4. Booking Page Structure
+
+The booking page is available at:
+
+/book/{event-id}
+
+It consists of a single vertical flow optimized for mobile devices.
+
+### 4.1 Event Summary Section
+
+Displayed at the top and always visible:
+
+* Event title
+* Date and time
+* Location
+* Remaining seats
+* Price
+
+This section helps users verify they selected the correct event.
+
+---
+
+### 4.2 User Information Section
+
+The booking form collects:
+
+* Full name (required)
+* Email address (required)
+* Phone / WhatsApp number (required)
+* Preferred language (optional)
+
+Validation rules:
+
+* All required fields must be filled
+* Email format validation
+* Phone number format validation
+* Duplicate booking prevention
+
+---
+
+### 4.3 Payment Selection Section
+
+Users choose one of the following payment methods using selectable cards.
+
+Each option is presented as a large, tap-friendly card with icon and description.
+
+Available options:
+
+1. TPago / Bancard
+2. Bitcoin Lightning
+3. Cash at Event
+
+Only one option may be selected.
+
+---
+
+## 5. Payment Methods
+
+### 5.1 TPago / Bancard (Credit & Debit Card)
+
+#### User Flow
+
+1. User selects "TPago / Bancard"
+2. User clicks "Pay with Card"
+3. User is redirected to Bancard checkout
+4. User completes payment
+5. User is redirected back to Spanglish
+6. Payment is verified via webhook
+7. Ticket is confirmed
+
+#### System Behavior
+
+* Payment intent is created before redirect
+* Payment reference is stored
+* Webhook validation is mandatory
+* Only verified payments mark tickets as paid
+
+Status: Paid
+
+---
+
+### 5.2 Bitcoin Lightning (BTCPay)
+
+#### User Flow
+
+1. User selects "Bitcoin Lightning"
+2. Invoice is generated
+3. QR code and invoice string are displayed
+4. User pays with Lightning wallet
+5. Payment is detected via webhook
+6. Ticket is confirmed automatically
+
+#### Display Requirements
+
+* QR code
+* Amount in sats
+* Expiry countdown
+* Copy invoice button
+
+#### System Behavior
+
+* Invoice created via BTCPay API
+* Webhook confirmation required
+* Automatic ticket confirmation
+
+Status: Paid
+
+---
+
+### 5.3 Cash at Event
+
+#### User Flow
+
+1. User selects "Cash at Event"
+2. User confirms reservation
+3. Booking is created
+4. Ticket is generated
+5. User receives confirmation
+6. User pays in cash at the event entrance
+
+#### System Behavior
+
+* Booking is stored as unpaid
+* Seat is reserved immediately
+* No automatic expiration is applied
+* Admin marks payment as received manually
+
+Status: Pending (until marked Paid by staff)
+
+---
+
+## 6. Ticket Generation
+
+After successful booking:
+
+* A unique ticket ID is generated
+* Ticket is linked to user and event
+* Ticket status is assigned
+* QR code may be generated
+* Ticket is stored permanently
+
+Ticket statuses:
+
+* Pending
+* Paid
+* Cancelled
+* Refunded
+
+---
+
+## 7. Confirmation & Notifications
+
+### 7.1 Booking Confirmation
+
+Sent immediately after booking.
+
+Channels:
+
+* Email
+* Optional WhatsApp integration
+
+Content includes:
+
+* Event details
+* Payment method
+* Ticket ID
+* Check-in instructions
+  n
+
+---
+
+### 7.2 Payment Confirmation
+
+Sent when payment is completed (Card / Lightning).
+
+Includes:
+
+* Payment receipt
+* Ticket confirmation
+* Calendar link
+
+---
+
+### 7.3 Event Reminder
+
+Sent automatically before the event.
+
+Includes:
+
+* Date and time
+* Location map
+* Payment reminder for cash users
+
+---
+
+## 8. Admin Management Flow
+
+### 8.1 Admin View
+
+Admins can view all bookings with:
+
+* Name
+* Event
+* Payment method
+* Status
+* Contact info
+* Check-in status
+
+Color coding:
+
+* Green: Paid
+* Yellow: Pending
+* Red: Cancelled
+
+---
+
+### 8.2 Manual Payment Processing
+
+For cash payments:
+
+* Admin locates ticket
+* Marks as Paid
+* Timestamp is recorded
+* Receipt may be attached
+
+---
+
+### 8.3 Refund Handling
+
+Admins may:
+
+* Mark tickets as Refunded
+* Trigger payment provider refunds
+* Send notification to user
+
+---
+
+## 9. Capacity Management
+
+* Each event has a fixed capacity
+* Seats are reserved immediately on booking
+* Overbooking is prevented
+* Sold-out events disable booking
+
+---
+
+## 10. Anti-Abuse Measures
+
+The system must implement:
+
+* Duplicate booking detection
+* Rate limiting on bookings
+* Email verification (optional)
+* Admin override tools
+
+---
+
+## 11. Error Handling
+
+The system must handle:
+
+* Failed payments
+* Interrupted redirects
+* Invoice expiration
+* Network issues
+* Invalid input
+
+Behavior:
+
+* Clear user-facing messages
+* Automatic retry options
+* Error logging
+
+---
+
+## 12. Audit Logging
+
+All booking-related actions must be logged:
+
+* Ticket creation
+* Payment updates
+* Manual status changes
+* Refunds
+* Cancellations
+
+Each log entry includes:
+
+* User ID
+* Admin ID (if applicable)
+* Timestamp
+* Action type
+  n
+
+---
+
+## 13. Security Requirements
+
+* Secure payment redirects
+* Webhook signature verification
+* Encrypted data storage
+* PCI compliance via provider
+* No sensitive card data stored
+
+---
+
+## 14. Future Extensions
+
+The booking system is designed to support:
+
+* Subscriptions
+* Membership passes
+* Promo codes
+* Group bookings
+* Lightning Address payments
+* Cashu payments
+
+---
+
+## 15. Summary
+
+This booking and payment flow is designed to be fast, reliable, and scalable.
+
+It supports local payment methods, Bitcoin Lightning, and cash while maintaining professional standards.
+
+All implementations must follow this document to ensure consistency and trust.

about/brand.md

@@ -0,0 +1,441 @@
+# Spanglish Website – Brand & Design Guide
+
+## 1. Purpose
+
+This document defines the visual identity, branding rules, and design direction for the Spanglish website.
+
+It ensures consistent appearance across the public website, admin dashboard, emails, and marketing materials.
+
+All designers and developers must follow this guide.
+
+---
+
+## 2. Brand Identity
+
+### 2.1 Brand Personality
+
+Spanglish is:
+
+* Friendly
+* International
+* Social
+* Modern
+* Trustworthy
+* Community-driven
+* Inclusive
+
+The visual identity must reflect openness, warmth, and professionalism.
+
+---
+
+### 2.2 Brand Values
+
+* Accessibility
+* Simplicity
+* Human connection
+* Cultural exchange
+* Reliability
+* Growth
+
+These values guide all design decisions.
+
+---
+
+## 3. Visual Direction
+
+### 3.1 Overall Look
+
+The website must feel:
+
+* Clean
+* Modern
+* Light
+* Welcoming
+* Organized
+
+The design is inspired by:
+
+* Café culture
+* International meetups
+* Modern SaaS landing pages
+* Community platforms
+
+The hero section uses strong contrast, large typography, and real photography.
+
+---
+
+### 3.2 Layout Philosophy
+
+* Mobile-first
+* One-column dominant layout
+* Large sections with breathing room
+* Consistent spacing
+* Clear visual hierarchy
+
+Avoid clutter and unnecessary elements.
+
+---
+
+## 4. Color System
+
+### 4.1 Primary Colors
+
+Primary Yellow (Brand Anchor)
+
+* Hex: #FFD84D
+* Usage: CTAs, highlights, logo accents
+
+Primary Dark (Text & Contrast)
+
+* Hex: #111111
+* Usage: Headings, main text, navigation
+
+Primary White (Background)
+
+* Hex: #FFFFFF
+* Usage: Main backgrounds
+
+---
+
+### 4.2 Secondary Colors
+
+Soft Gray (Background Sections)
+
+* Hex: #F5F5F5
+
+Light Gray (Borders)
+
+* Hex: #E5E5E5
+
+Accent Blue (Links)
+
+* Hex: #2F80ED
+
+Warm Brown (Coffee Accent)
+
+* Hex: #6B4A2B
+
+---
+
+### 4.3 Color Usage Rules
+
+* Yellow is used sparingly
+* White is dominant
+* Dark is used for contrast
+* Avoid heavy gradients
+* Avoid neon colors
+* Avoid dark backgrounds on public pages
+
+Admin dashboard may use darker neutral tones.
+
+---
+
+## 5. Typography
+
+### 5.1 Primary Font
+
+Recommended:
+
+* Inter
+* Poppins
+* Montserrat
+
+Usage:
+
+* Headings: Semi-bold / Bold
+* Body: Regular
+
+---
+
+### 5.2 Body Font
+
+Recommended:
+
+* Inter
+* Roboto
+* System UI
+
+Line height: 1.5 – 1.7
+
+Avoid decorative fonts.
+
+---
+
+### 5.3 Font Hierarchy
+
+Example:
+
+H1: 48–56px
+H2: 36–40px
+H3: 24–28px
+Body: 16–18px
+Small: 14px
+
+Responsive scaling required.
+
+---
+
+## 6. Logo Usage
+
+### 6.1 Logo Style
+
+* Simple
+* Flat
+* Works in monochrome
+* Works on light backgrounds
+
+---
+
+### 6.2 Logo Placement
+
+* Top-left in navigation
+* Footer
+* Emails
+* Tickets
+* Posters
+
+Minimum clear space: Logo height x 0.5
+
+---
+
+## 7. Photography Style
+
+### 7.1 Photo Characteristics
+
+Use:
+
+* Real participants
+* Natural lighting
+* Smiling faces
+* Conversation scenes
+* Coffee and table shots
+* Multicultural groups
+
+Avoid:
+
+* Stock photos
+* Posed portraits
+* Empty rooms
+* Artificial lighting
+
+---
+
+### 7.2 Image Treatment
+
+* Slight warm tone
+* Balanced contrast
+* No heavy filters
+* Consistent cropping
+
+---
+
+## 8. Iconography
+
+### 8.1 Style
+
+* Flat
+* Rounded
+* Line-based
+* Minimal detail
+
+Recommended sets:
+
+* Heroicons
+* Lucide
+* Feather
+
+---
+
+### 8.2 Usage
+
+Icons support content.
+They must not replace text.
+
+---
+
+## 9. UI Components
+
+### 9.1 Buttons
+
+Primary Button:
+
+* Background: #FFD84D
+* Text: #111111
+* Border-radius: 10–14px
+* Padding: 12px 24px
+
+Secondary Button:
+
+* Border: 1px solid #111111
+* Background: Transparent
+
+Hover:
+
+* Slight darkening
+* Soft shadow
+
+---
+
+### 9.2 Cards
+
+* White background
+* Rounded corners (16–20px)
+* Soft shadow
+* Internal padding
+
+Used for:
+
+* Events
+* Testimonials
+* Stats
+
+---
+
+### 9.3 Forms
+
+* Large input fields
+* Clear labels
+* Rounded corners
+* Inline validation
+
+---
+
+## 10. Hero Section Design
+
+### 10.1 Structure
+
+Left Side:
+
+* Main headline
+* Subheading
+* CTA button
+* Event info
+
+Right Side:
+
+* Photo collage
+* Group images
+* Rounded corners
+
+---
+
+### 10.2 Hero Content Style
+
+Headline:
+
+* Bold
+* Clear
+* Positive
+
+Example:
+"Practice English & Spanish in Asunción"
+
+Subheadline:
+"Meet people. Learn languages. Have fun."
+
+CTA:
+"Join Next Event"
+
+---
+
+### 10.3 Background
+
+* White or very light gray
+* Yellow accents
+* Subtle shapes
+
+Avoid full-color backgrounds.
+
+---
+
+## 11. Navigation Design
+
+* Sticky top navigation
+* White background
+* Subtle shadow
+* Clear links
+
+Menu items:
+
+* Home
+* Events
+* Community
+* Contact
+* Join
+
+CTA highlighted in yellow.
+
+---
+
+## 12. Footer Design
+
+* Light gray background
+* Minimal links
+* Social icons
+* Copyright info
+
+---
+
+## 13. Admin Dashboard Style
+
+### 13.1 Visual Tone
+
+* Neutral
+* Productivity-focused
+* Low distraction
+
+### 13.2 Colors
+
+* White / Gray backgrounds
+* Blue accents
+* Minimal yellow
+
+---
+
+## 14. Email Design
+
+* White background
+* Logo header
+* Clear typography
+* Single CTA
+* Mobile-friendly
+
+---
+
+## 15. Accessibility
+
+* Minimum contrast ratio 4.5:1
+* Large tap targets
+* Keyboard navigation
+* Alt text for images
+
+---
+
+## 16. Consistency Rules
+
+* Reuse components
+* Follow spacing system
+* Use defined colors only
+* No custom fonts without approval
+* No random color usage
+
+---
+
+## 17. Future Branding Extensions
+
+* City-specific color accents
+* Event themes
+* Seasonal variations
+* Partner branding
+
+All extensions must respect core identity.
+
+---
+
+## 18. Summary
+
+This brand and design guide defines how Spanglish should look and feel.
+
+It ensures a consistent, modern, and welcoming experience across all touchpoints.
+
+All visual implementations must comply with this document.

about/email_spec.md

@@ -0,0 +1,299 @@
+# Spanglish Website – Email System Specification
+
+## 1. Purpose
+
+This document defines all email communications sent by the Spanglish platform.
+
+The goal is to provide clear, reliable communication without unnecessary automation or spam.
+
+All emails must support event management, trust, and community growth.
+
+---
+
+## 2. Core Principles
+
+* Bookings are only confirmed after payment
+* No automatic reminders based on cron jobs
+* No automatic cash reminders
+* Follow-up emails are sent manually
+* Event-specific communication must be possible
+* Emails must be intentional and relevant
+
+---
+
+## 3. Booking Confirmation Policy
+
+### 3.1 Payment Requirement
+
+A booking is considered "Confirmed" only when:
+
+* Card payment is verified, or
+* Lightning payment is verified, or
+* Cash payment is marked as received by staff
+
+Unpaid cash reservations are not considered confirmed.
+
+---
+
+### 3.2 Confirmation Email
+
+Sent only after payment is confirmed.
+
+Trigger:
+
+* Payment webhook (Card / Lightning)
+* Manual admin confirmation (Cash)
+
+Purpose:
+
+* Official confirmation
+* Proof of participation
+
+---
+
+## 4. Supported Email Types
+
+### 4.1 Booking Confirmation (Automatic)
+
+Sent when payment is confirmed.
+
+Trigger:
+
+* Payment verification
+* Manual confirmation
+
+Subject Example:
+Your Spanglish ticket is confirmed 🎉
+
+Content includes:
+
+* Event name
+* Date and time
+* Location and map
+* Payment method
+* Ticket ID
+* Contact info
+
+---
+
+### 4.2 Payment Receipt (Automatic)
+
+Sent for Card and Lightning payments.
+
+Trigger:
+
+* Payment provider webhook
+
+Purpose:
+
+* Financial confirmation
+* Transparency
+
+Content includes:
+
+* Amount
+* Method
+* Reference ID
+
+---
+
+### 4.3 Event Update / Custom Message (Manual)
+
+Sent manually by admin per event.
+
+Trigger:
+
+* Admin action
+
+Purpose:
+
+* Inform attendees about changes
+* Share important information
+* Handle exceptional situations
+
+Examples:
+
+* Location change
+* Time change
+* Special instructions
+* Delays
+* Guest speakers
+
+Admin must be able to:
+
+* Write custom subject
+* Write custom body
+* Select target event
+* Preview before sending
+
+---
+
+### 4.4 Post-Event Follow-Up (Manual)
+
+Sent manually after the event.
+
+Trigger:
+
+* Admin action
+
+Purpose:
+
+* Thank attendees
+* Share photos
+* Promote next event
+* Build loyalty
+
+This email is never automated.
+
+---
+
+## 5. Disabled / Unsupported Emails
+
+The system must NOT send:
+
+* Automatic cash payment reminders
+* Automated event reminders
+* Cron-based scheduled emails
+* Repeated promotional spam
+
+All non-critical communication is manual.
+
+---
+
+## 6. Admin Email Interface
+
+### 6.1 Email Center
+
+The admin dashboard must include an Email Center with:
+
+* List of past emails
+* Draft editor
+* Template library
+* Recipient selector
+* Preview mode
+* Send confirmation
+
+---
+
+### 6.2 Recipient Selection
+
+Admins must be able to target:
+
+* All attendees of an event
+* Only confirmed attendees
+* Only unpaid attendees
+* Custom subsets
+
+Selection must be explicit before sending.
+
+---
+
+## 7. Templates
+
+### 7.1 Default Templates
+
+System-provided templates:
+
+* Booking confirmation
+* Payment receipt
+* Event update
+* Follow-up
+
+Templates are editable.
+
+---
+
+### 7.2 Custom Templates
+
+Admins may create custom templates per event.
+
+Templates support:
+
+* Variables (name, event, date)
+* Preview rendering
+* Versioning
+
+---
+
+## 8. Sending Logic
+
+### 8.1 Manual Sending
+
+Most emails are sent manually from the admin panel.
+
+The system must require:
+
+* Explicit confirmation
+* Recipient preview
+* Final approval
+
+---
+
+### 8.2 Automatic Sending
+
+Only the following emails may be automatic:
+
+* Booking confirmation (after payment)
+* Payment receipt
+
+No other automatic emails are allowed.
+
+---
+
+## 9. Logging & Auditing
+
+All email activity must be logged:
+
+* Sender (admin)
+* Recipients
+* Subject
+* Timestamp
+* Event reference
+* Delivery status
+
+Logs are visible to admins.
+
+---
+
+## 10. Deliverability Requirements
+
+* Use verified sender domain
+* DKIM and SPF enabled
+* Bounce handling
+* Unsubscribe support
+
+---
+
+## 11. Design Rules
+
+All emails must follow brand guidelines:
+
+* White background
+* Logo header
+* Clean typography
+* Mobile-friendly layout
+* One main CTA
+* No clutter
+
+---
+
+## 12. Future Extensions
+
+Possible future additions:
+
+* WhatsApp integration
+* SMS notifications
+* Smart segmentation
+* Automated campaigns (opt-in only)
+
+All future automation requires explicit approval.
+
+---
+
+## 13. Summary
+
+The Spanglish email system prioritizes clarity, trust, and human control.
+
+Only critical confirmations are automated.
+
+All community and relationship communication remains manual and intentional.

about/overview.md

@@ -0,0 +1,264 @@
+# Spanglish Website – Overview
+
+## 1. Purpose
+
+The Spanglish website is the official digital platform for organizing, promoting, and managing Spanglish language exchange events in Asunción, Paraguay.
+
+Its primary purpose is to:
+
+* Promote monthly language exchange events
+* Convert visitors into attendees
+* Centralize event operations
+* Reduce manual work for organizers
+* Build and retain a long-term community
+* Support future expansion
+
+The website is designed to be the main reference point for all Spanglish activities.
+
+---
+
+## 2. Product Vision
+
+Spanglish aims to be the leading language exchange community in Paraguay and later in other cities.
+
+The website should:
+
+* Feel welcoming and modern
+* Be easy to use for first-time visitors
+* Be powerful for internal management
+* Scale with community growth
+
+Long-term, the system should support multiple cities, memberships, and learning resources without major redesign.
+
+---
+
+## 3. Target Users
+
+### 3.1 Public Users (Participants)
+
+* Spanish speakers learning English
+* English speakers learning Spanish
+* Students and professionals
+* Expats and travelers
+* Newcomers discovering Spanglish
+* Returning community members
+
+### 3.2 Internal Users (Staff)
+
+* Admin (Owner)
+* Organizers
+* Check-in staff
+* Marketing staff
+* Support staff
+
+---
+
+## 4. Core Goals
+
+The website is built around the following core goals:
+
+1. Increase event attendance
+2. Improve operational efficiency
+3. Reduce manual coordination
+4. Improve communication
+5. Build community loyalty
+6. Enable data-driven decisions
+
+All features must directly or indirectly support these goals.
+
+---
+
+## 5. System Scope
+
+The system consists of two main components:
+
+1. Public Website
+2. Admin Dashboard
+
+Both components are connected through a shared backend and database.
+
+### 5.1 Public Website
+
+The public website is responsible for:
+
+* Presenting Spanglish
+* Displaying events
+* Handling bookings
+* Promoting community channels
+* Collecting contact information
+
+### 5.2 Admin Dashboard
+
+The admin dashboard is responsible for:
+
+* Managing events
+* Managing attendees
+* Managing payments
+* Sending communications
+* Managing media
+* Monitoring performance
+
+---
+
+## 6. Core Principles
+
+All development and design decisions must follow these principles:
+
+### 6.1 Simplicity
+
+* Avoid unnecessary complexity
+* Prioritize ease of use
+* Minimize user friction
+
+### 6.2 Reliability
+
+* Stable operation
+* Clear error handling
+* Data integrity
+
+### 6.3 Performance
+
+* Fast loading pages
+* Responsive UI
+* Optimized assets
+
+### 6.4 Maintainability
+
+* Clean code structure
+* Clear documentation
+* Modular design
+
+### 6.5 Scalability
+
+* Support growing user base
+* Support additional locations
+* Support new business models
+
+---
+
+## 7. Brand and Experience
+
+### 7.1 Brand Personality
+
+Spanglish is:
+
+* Friendly
+* International
+* Social
+* Organized
+* Trustworthy
+* Community-driven
+
+The website should reflect these values in design and tone.
+
+### 7.2 User Experience Goals
+
+Visitors should feel:
+
+* Welcome
+* Comfortable
+* Confident
+* Motivated to join
+
+Admins should feel:
+
+* In control
+* Efficient
+* Informed
+* Supported
+
+---
+
+## 8. Community Strategy
+
+The website supports community building by:
+
+* Promoting WhatsApp and social groups
+* Collecting email addresses
+* Tracking attendance history
+* Supporting loyalty programs
+* Enabling direct communication
+
+The platform is designed to strengthen long-term relationships, not only facilitate one-time events.
+
+---
+
+## 9. Business Model
+
+The primary revenue source is event ticket sales.
+
+Secondary and future revenue sources may include:
+
+* Membership subscriptions
+* Partner sponsorships
+* Premium events
+* Workshops
+* Digital learning materials
+
+The system must be flexible enough to support these models.
+
+---
+
+## 10. Data Strategy
+
+The system collects and manages:
+
+* User profiles
+* Event data
+* Ticket records
+* Payment records
+* Communication logs
+* Media assets
+
+All data must be handled securely and responsibly.
+
+---
+
+## 11. Growth Vision
+
+Future expansion includes:
+
+* Multiple cities
+* Multi-language support
+* Mobile app
+* Learning platform
+* Certification system
+* Nostr and Lightning integration
+
+The initial architecture must allow these extensions without major rewrites.
+
+---
+
+## 12. Success Metrics
+
+The project will be evaluated using:
+
+* Event attendance growth
+* Conversion rate
+* Repeat participation rate
+* Revenue per event
+* Community size
+* Operational efficiency
+
+These metrics guide future improvements.
+
+---
+
+## 13. Constraints
+
+The system must:
+
+* Run on existing VPS infrastructure
+* Be maintainable by a small team
+* Minimize operational overhead
+* Avoid unnecessary dependencies
+
+---
+
+## 14. Summary
+
+The Spanglish website is a professional event management and community platform designed to support sustainable growth.
+
+It combines a simple, welcoming public interface with a powerful internal management system.
+
+All development must prioritize usability, reliability, and long-term scalability.

about/payment_options.md

@@ -0,0 +1,366 @@
+# Spanglish Website – Payment Options Management
+
+## 1. Purpose
+
+This document defines how payment methods are configured, displayed, and managed in the Spanglish platform.
+
+It introduces a centralized Payment Options system that can be configured globally and overridden per event.
+
+The goal is to provide flexibility, transparency, and administrative control over all payment flows.
+
+---
+
+## 2. Core Principles
+
+* Payment options are centrally managed in the admin panel
+* Each event can override default payment settings
+* Most non-instant payments require manual admin approval
+* Only approved payments trigger confirmation emails
+* Users must clearly understand how to pay
+* The system must support future payment methods
+
+---
+
+## 3. Payment Options Admin Tab
+
+### 3.1 Location
+
+The admin dashboard must include a dedicated tab:
+
+/Admin → Payment Options
+
+This section controls global payment settings.
+
+---
+
+### 3.2 Global Payment Configuration
+
+Admins can configure default payment options used for all events unless overridden.
+
+Global settings include:
+
+* TPago default link
+* Bank transfer details
+* Bitcoin/Lightning configuration (LNbits)
+* Cash policy
+* Enabled / disabled status per method
+
+---
+
+### 3.3 Event-Level Overrides
+
+Each event includes a "Payment Settings" section.
+
+Admins may override:
+
+* TPago link
+* Bank account details
+* Enabled payment methods
+* Custom instructions
+
+If no override is set, global defaults apply.
+
+---
+
+## 4. Supported Payment Methods
+
+---
+
+## 4.1 Paraguayan Bank Transfer
+
+### Description
+
+Allows users to pay via local bank transfer.
+
+Payment details are displayed to the user.
+
+### Displayed Information
+
+* Bank name
+* Account holder
+* Account number
+* Alias
+* Phone number
+* Additional notes (optional)
+
+### User Flow
+
+1. User selects "Bank Transfer"
+2. Bank details are displayed
+3. User makes the transfer externally
+4. User clicks "I Have Paid"
+5. Booking status becomes "Pending Approval"
+6. Admin verifies payment
+7. Admin marks payment as Paid
+8. Confirmation email is sent
+
+### System Behavior
+
+* No automatic confirmation
+* No booking confirmation until approved
+* Payment proof upload (optional future feature)
+
+Status Flow:
+Pending → Paid → Confirmed
+
+---
+
+## 4.2 International Cards (TPago Link)
+
+### Description
+
+International card payments are handled via a TPago payment link.
+
+Example:
+[https://www.tpago.com.py/links?alias=PXEOI9](https://www.tpago.com.py/links?alias=PXEOI9)...
+
+### Displayed Information
+
+* Payment provider name
+* External payment link
+* Instructions
+
+### User Flow
+
+1. User selects "International Card"
+2. TPago link opens in new tab
+3. User completes payment
+4. User returns to booking page
+5. User clicks "I Have Paid"
+6. Booking status becomes "Pending Approval"
+7. Admin verifies payment
+8. Admin marks payment as Paid
+9. Confirmation email is sent
+
+### System Behavior
+
+* Payment verification is manual
+* No automatic webhook integration
+* External link must be configurable
+
+Status Flow:
+Pending → Paid → Confirmed
+
+---
+
+## 4.3 Bitcoin / Lightning (LNbits)
+
+### Description
+
+Lightning payments are handled via LNbits integration.
+
+This method supports instant confirmation.
+
+### User Flow
+
+1. User selects "Bitcoin / Lightning"
+2. Invoice is generated
+3. QR code is displayed
+4. User pays
+5. Payment is detected automatically
+6. Ticket is confirmed
+7. Confirmation email is sent
+
+### System Behavior
+
+* Fully automated
+* Webhook-based confirmation
+* No admin intervention required
+
+Status Flow:
+Paid → Confirmed
+
+---
+
+## 4.4 Cash at the Door
+
+### Description
+
+Users pay in cash when arriving at the event.
+
+### User Flow
+
+1. User selects "Cash at the Door"
+2. Booking is created
+3. Status is set to Pending
+4. User attends event
+5. Staff receives payment
+6. Admin marks as Paid
+7. Confirmation is sent
+
+### System Behavior
+
+* No automatic confirmation
+* Manual approval required
+* Visible in admin dashboard
+
+Status Flow:
+Pending → Paid → Confirmed
+
+---
+
+## 5. Booking Page Presentation
+
+Payment methods are displayed as selectable cards.
+
+Each card includes:
+
+* Icon
+* Title
+* Short description
+* Processing speed (Instant / Manual)
+
+Example:
+
+[ Bank Transfer ]  (Manual)
+[ International Card ] (Manual)
+[ Bitcoin / Lightning ] (Instant)
+[ Cash at Door ] (Manual)
+
+Selected card expands with instructions.
+
+---
+
+## 6. "I Have Paid" Confirmation Button
+
+For manual payment methods, the booking page must display:
+
+Button: "I Have Paid"
+
+### Behavior
+
+* Marks booking as "Pending Approval"
+* Stores timestamp
+* Notifies admin
+* Disables duplicate clicks
+
+No confirmation email is sent at this stage.
+
+---
+
+## 7. Admin Payment Verification Panel
+
+### 7.1 Payment Review Queue
+
+Admins have access to:
+
+/Admin → Payments → Pending Approval
+
+This list shows:
+
+* User name
+* Event
+* Payment method
+* Amount
+* Date
+* Reference (if provided)
+
+---
+
+### 7.2 Approval Actions
+
+For each pending payment:
+
+* Approve (mark as Paid)
+* Reject (mark as Failed)
+* Add internal note
+
+Approval triggers:
+
+* Ticket confirmation
+* Confirmation email
+* Audit log entry
+
+---
+
+## 8. Payment Status Model
+
+All bookings follow this status lifecycle:
+
+Created → Pending → Paid → Confirmed
+↓
+Failed / Cancelled
+
+Only "Confirmed" bookings are considered valid attendees.
+
+---
+
+## 9. Data Storage
+
+Each payment record stores:
+
+* Payment ID
+* Booking ID
+* Method
+* Amount
+* Currency
+* Reference
+* Status
+* Admin approver
+* Approval timestamp
+* Notes
+
+---
+
+## 10. Extensibility for Future Methods
+
+The payment system must be modular.
+
+New payment methods can be added by defining:
+
+* Name
+* Type (Instant / Manual)
+* Configuration schema
+* UI template
+* Validation rules
+
+Examples:
+
+* PayPal
+* PIX
+* Cashu
+* Local wallets
+* QR bank payments
+
+No core refactor should be required.
+
+---
+
+## 11. Security Requirements
+
+* Secure storage of payment data
+* Access control on payment approval
+* Audit logging
+* Protection against duplicate approvals
+* No storage of sensitive card data
+
+---
+
+## 12. Reporting
+
+The admin dashboard must provide:
+
+* Revenue per payment method
+* Pending approvals
+* Failed payments
+* Approval turnaround time
+
+---
+
+## 13. User Experience Rules
+
+* Instructions must be clear
+* Links must open correctly
+* Manual steps must be visible
+* No misleading "confirmed" messages
+* Payment state always visible
+
+---
+
+## 14. Summary
+
+This payment options system centralizes configuration and control while supporting both instant and manual payment methods.
+
+It enables local Paraguayan payments, international cards, Bitcoin Lightning, and cash handling within one unified workflow.
+
+All implementations must follow this specification to ensure reliability and scalability.

about/ruc_format.md

@@ -0,0 +1,203 @@
+RUC Form Integration
+1. Overview
+
+This document defines the implementation of a RUC (Registro Único del Contribuyente) input form for the application.
+
+The goal is to:
+
+Collect valid Paraguayan RUC numbers
+
+Reduce user input errors
+
+Improve user experience
+
+Ensure basic legal and invoicing compliance
+
+The RUC field will be used for:
+
+Invoicing
+
+Payments
+
+Registrations
+
+Business verification
+
+Tax-related records
+
+2. RUC Format Specification
+
+A valid RUC has the following structure:
+
+6 to 8 digits + "-" + 1 check digit
+
+
+Examples:
+
+4521876-5
+80012345-6
+12345678-9
+
+
+Rules:
+
+Only numbers and one hyphen
+
+The hyphen is always before the last digit
+
+No spaces or letters allowed
+
+Maximum length: 10 characters (including "-")
+
+3. User Interface Requirements
+3.1 Input Field
+
+The RUC input field must:
+
+Accept only numeric input
+
+Auto-insert the hyphen
+
+Show placeholder example
+
+Display validation errors
+
+Example UI:
+
+[ RUC: 12345678-9 ]
+
+
+Attributes:
+
+Required field (when invoicing enabled)
+
+Mobile-friendly
+
+Copy-paste safe
+
+Accessible (label + aria support)
+
+3.2 Placeholder Text
+
+Default placeholder:
+
+12345678-9
+
+
+Optional localized versions:
+
+Spanish:
+
+Ej: 12345678-9
+
+
+English:
+
+Example: 12345678-9
+
+4. Client-Side Validation
+4.1 Format Validation
+
+The frontend must verify:
+
+Pattern: /^[0-9]{6,8}-[0-9]{1}$/
+
+Exactly one hyphen
+
+Correct digit count
+
+Invalid examples:
+
+1234-5
+123456789
+ABC123-4
+
+4.2 Check Digit Validation
+
+The verification digit must be validated using modulo 11.
+
+Purpose:
+
+Detect mistyped RUC numbers
+
+Prevent fake entries
+
+Improve data quality
+
+Validation occurs:
+
+On input blur
+
+On form submit
+
+Before backend submission
+
+4.3 Auto-Formatting
+
+The system must:
+
+Remove non-numeric characters
+
+Automatically insert "-"
+
+Limit input to 9 digits
+
+Behavior:
+
+User types:
+
+45218765
+
+
+System shows:
+
+4521876-5
+
+
+This improves usability and reduces errors.
+
+5. Error Handling
+5.1 Error Messages
+
+When validation fails, show:
+
+Format error:
+
+Formato inválido. Ej: 12345678-9
+
+
+Check digit error:
+
+RUC inválido. Verifique el número.
+
+
+Empty field:
+
+Este campo es obligatorio.
+
+
+Messages should be:
+
+Clear
+
+Short
+
+Non-technical
+
+Localized
+
+5.2 Visual Feedback
+
+Invalid input must:
+
+Highlight input in red
+
+Show error text below field
+
+Disable submit if blocking
+
+Valid input must:
+
+Show neutral or success state
+
+Remove error messages

about/user_dashboard.md

@@ -0,0 +1,430 @@
+# 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.