eventsphere/srs.md

Use this as the production architecture upgrade prompt in Trae.ai:

Upgrade the existing EventSphere starter implementation into a production-grade, multi-tenant SaaS architecture.

Strictly preserve the current UI/UX design system, layout, colors, typography, spacing, cards, sidebar, dashboard structure, and enterprise minimal look. Do not redesign the product.

ARCHITECTURE TARGET

Frontend:
- Next.js 14 App Router
- TypeScript
- Tailwind CSS
- Server/client component separation
- Central API client
- Route guards
- Role-aware navigation
- Form validation
- Loading, empty, and error states
- Pagination, filtering, search, export

Backend:
- NestJS
- PostgreSQL
- Prisma ORM
- Redis
- BullMQ queues
- JWT access/refresh authentication
- RBAC permissions
- Multi-tenant isolation
- Swagger/OpenAPI
- Global validation pipe
- Global exception filter
- Structured logging
- Audit logs
- Rate limiting
- Webhook security

Infrastructure:
- Docker Compose for local and production
- Traefik reverse proxy
- Let’s Encrypt TLS
- PostgreSQL persistent volume
- Redis persistent volume
- API worker service
- Health checks
- Backup jobs
- Environment templates
- Production README

CORE SERVICES TO BUILD

1. Authentication Service
- Login
- Refresh token
- Logout
- Password reset
- User invitation
- Tenant-aware users
- Role assignment

2. Tenant Service
- Tenant creation
- Tenant settings
- Branding configuration
- Domain/slug support
- Feature flags

3. Event Service
- Event CRUD
- Event landing page configuration
- Ticket types
- Registration rules
- Approval workflow settings
- Event publishing status

4. Attendee Service
- Attendee profile
- Invitee import
- RSVP tracking
- Registration status
- Tags and segmentation
- Attendance history

5. Registration Service
- Public registration
- Dynamic form submission
- Duplicate detection
- Approval queue
- Confirmation workflow
- Ticket assignment

6. QR Code / Check-in Service
- Secure QR generation
- Unique ticket token
- QR validation endpoint
- Live check-in
- Duplicate scan prevention
- Check-in logs

7. Communication Service
- Email templates
- SMS templates
- WhatsApp templates
- Africa’s Talking integration
- SMTP/SendGrid-ready abstraction
- Automated confirmation
- Reminder scheduling
- Delivery logs

8. Payment Service
- Paystack payment initialization
- Paystack webhook verification
- Payment status update
- Paid ticket registration
- Transaction history
- Refund-ready structure

9. CRM Pipeline Service
- Lead creation from registrations
- Deal stages
- Pipeline board
- Activity notes
- Source attribution
- Opportunity value
- Conversion reporting

10. Workflow Engine
- Trigger: registration created
- Trigger: registration approved
- Trigger: payment successful
- Trigger: event reminder due
- Actions:
  - send email
  - send SMS
  - send WhatsApp
  - generate QR
  - update CRM stage
  - notify admin

11. Calendar Routing Forms
- Routing form builder
- Availability slots
- Meeting booking
- Internal calendar view
- Automated booking confirmation

12. Reporting Service
- Dashboard metrics
- Registration trend
- RSVP trend
- Source conversion
- Payment revenue
- Check-in analytics
- CRM conversion report
- Export CSV/XLSX

DATABASE REQUIREMENTS

Use Prisma and create a clean schema for:

- Tenant
- User
- Role
- Permission
- UserRole
- Event
- EventPage
- TicketType
- Invitee
- Attendee
- Registration
- RSVP
- Form
- FormField
- FormSubmission
- QRCode
- CheckIn
- CommunicationTemplate
- CommunicationLog
- Payment
- PaystackWebhookEvent
- CRMLead
- CRMDeal
- CRMActivity
- Workflow
- WorkflowTrigger
- WorkflowAction
- CalendarRoutingForm
- CalendarSlot
- Booking
- AuditLog
- IntegrationSetting

Every tenant-owned table must include:
- tenantId
- createdAt
- updatedAt

SECURITY REQUIREMENTS

Implement:
- Tenant isolation guard
- Permission guard
- JWT auth guard
- Refresh token rotation
- Password hashing with bcrypt
- Input validation DTOs
- Request rate limiting
- Webhook signature verification
- Audit logging for sensitive actions
- Secure environment handling
- No secrets committed

API REQUIREMENTS

Create REST APIs under:

/api/v1/auth
/api/v1/tenants
/api/v1/events
/api/v1/attendees
/api/v1/invitees
/api/v1/rsvps
/api/v1/registrations
/api/v1/check-ins
/api/v1/qr-codes
/api/v1/forms
/api/v1/workflows
/api/v1/communications
/api/v1/payments
/api/v1/crm
/api/v1/calendar
/api/v1/reports
/api/v1/settings
/api/v1/integrations

FRONTEND REQUIREMENTS

Fully connect all existing pages to the backend:

Admin pages:
- Dashboard
- Events
- Event Details
- Attendees
- Invitees
- RSVPs
- Registrations
- Live Check-in
- QR Codes
- Forms & Workflows
- Calendar
- Communications
- Email Campaigns
- WhatsApp Campaigns
- Payments
- CRM Pipeline
- Contacts / Leads
- Reports
- Settings
- Integrations

Public pages:
- Event landing page
- Event details page
- Registration page
- Ticket selection page
- Payment page
- Confirmation page
- E-ticket page
- Live event page

UI BEHAVIOR REQUIREMENTS

For every page:
- Use existing AdminShell/PublicShell layout
- Use existing Card/Button visual style
- Add loading states
- Add empty states
- Add error states
- Add create/edit/view modals where needed
- Add search/filter/export where relevant
- Preserve IBM/Cisco/Dell-style clean enterprise minimalism

QUEUE/JOBS REQUIREMENTS

Use BullMQ workers for:
- Email sending
- SMS sending
- WhatsApp sending
- QR generation
- Reminder scheduling
- Payment webhook processing
- Workflow actions
- Report generation

DEPLOYMENT REQUIREMENTS

Create:

- docker-compose.yml
- docker-compose.prod.yml
- Dockerfile for web
- Dockerfile for api
- Dockerfile for worker
- Traefik config
- .env.example
- .env.production.example
- database migration scripts
- seed script
- backup script
- restore script
- production README

Recommended domains:
- app.eventsphere.local or app.yourdomain.com
- api.eventsphere.local or api.yourdomain.com

QUALITY REQUIREMENTS

Before finishing:
- Run TypeScript checks
- Run lint
- Run build
- Confirm all routes compile
- Confirm all APIs return valid responses
- Confirm frontend pages do not use hardcoded mock data except seed/demo mode
- Confirm no TODO placeholders remain
- Confirm Docker compose boots successfully

FINAL DELIVERY

Deliver the final production-ready repository with:

- Complete source code
- Prisma schema
- API modules
- frontend pages
- worker queues
- integrations
- deployment files
- documentation
- seed data

This must be a real production SaaS platform, not a demo.