4.9 KiB
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
- 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
- Build frontend
- Build backend container
- Run database migrations
- Deploy containers
- Reload Nginx
- 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.