first commit

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.