340 lines
4.9 KiB
Markdown
340 lines
4.9 KiB
Markdown
# 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.
|