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