Conference Expo Portal v2.0 Specification

Version: 1.2.0
Date: 13 November 2025
Status: Approved

Introduction

This specification defines the plan for developing Conference Expo Portal v2.0, a comprehensive upgrade to Nimlok's existing conference and exhibition management system. The new portal aims to address current limitations while introducing modern features, improved user experience, and a more maintainable architecture.

The specification is structured to provide a clear understanding of both the business and technical aspects of the project, from current state analysis through to implementation planning.

Why Kick Digital?

Kick Digital is uniquely positioned to deliver Conference Expo Portal v2.0. As the original developers of the v1 portal, we bring:

• Deep knowledge of the Conference Expo product, business processes, and domain
• Established working relationships with Nimlok and key stakeholders
• First-hand experience with the strengths and limitations of the current system
• Proven ability to deliver robust, scalable solutions for the events industry

Our understanding of your business context, combined with our technical expertise and commitment to quality, means we can deliver a solution that not only meets the brief but also anticipates future needs.

Document Structure

1. Summary

   • Project overview
   • Key objectives and improvements
   • Expected outcomes
   • High-level timeline and costs

2. Architecture

   • System architecture overview
   • Technology stack
   • Infrastructure and hosting
   • Security considerations
   • Data models and relationships
   • API design principles

3. User Experience

   • User personas and roles
   • User journey maps
   • UI/UX guidelines
   • Accessibility considerations
   • Mobile responsiveness

4. Functional Requirements

   • User management and access control
   • Event management
   • Stand configuration
   • Artwork approval workflow
   • Messaging system
   • Other core features

5. Non-Functional Requirements

   • Performance requirements
   • Scalability
   • Security
   • Reliability
   • Maintainability
   • Compliance

6. Implementation

   • Development methodology
   • Testing strategy
   • Deployment pipeline
   • Continuous integration/delivery
   • Quality assurance

7. Delivery

   • Timeline and milestones
   • Resource requirements
   • Cost breakdown
   • Risk assessment
   • Success metrics

8. Appendices

   • API Documentation
   • Database Schema
   • UI Mockups

9. Changelog

   • Document version history
   • Revision tracking

How to Use This Document

This specification is designed to be read sequentially, with each section building upon the previous one. However, readers can also navigate directly to sections of particular interest using the links above.

The main specification sections (1-7) provide a comprehensive overview of the project, while the appendices contain detailed technical documentation and supporting materials.

Document Status

This is a living document that will be updated throughout the project lifecycle. Version 1.0.0 represents the complete specification with all functional requirements and finalized architecture, ready for client review and approval.

For detailed version history and changes, see the Changelog.

Summary

Overview

Conference Expo Portal v2.0 represents a significant upgrade to Nimlok's existing exhibition management platform. The current system's rigid package configuration has limited the Conference Expo team's ability to quickly set up and modify event packages, while also restricting organisers' ability to customise their exhibition offerings. This new version aims to transform the platform into a highly configurable, flexible system that enables the Conference Expo team to efficiently create tailored experiences for organisers, while making it easier for sponsors to manage their exhibition presence.

Current Situation

The existing Conference Expo Portal, developed in 2017, has successfully served conference organisers managing events with 5-75 exhibiting sponsors. While the platform has proven its value over the past eight years, it has established itself as a valuable tool for:

• Streamlining stand configuration processes
• Managing artwork approvals
• Processing payments
• Integrating with Nimlok's broader ecosystem

However, the platform's current limitations have become increasingly apparent to users:

• Rigid package configuration requiring significant effort to work around, limiting the Conference Expo team's ability to efficiently set up and modify event packages
• Complex process for creating new stand options and upgrades, making it difficult for the team to respond to organisers' specific requirements
• Limited flexibility in customising the sponsor experience, restricting organisers' ability to differentiate their events
• Cumbersome artwork submission and approval workflow, creating friction for sponsors
• Difficult to adapt to different event requirements, forcing the Conference Expo team to work within rigid constraints
• Technology stack and architecture from 2017, limiting the ability to implement modern features and integrations

Key Objectives

The v2.0 upgrade focuses on three primary objectives:

1. Enhanced User Experience

   • Modern, intuitive interface
   • Improved mobile responsiveness
   • More flexible workflows
   • Flexible package configuration for the Conference Expo team
   • Simplified upgrade selection process for sponsors
   • Intuitive artwork submission and feedback system

2. Operational Improvements

   • Reduced manual intervention
   • Improved automation
   • Enhanced reporting capabilities
   • Better error handling and recovery
   • Rapid package creation and modification for the Conference Expo team
   • Automated artwork requirement generation
   • Simpler artwork and proof approval workflows

3. Future-Proofing

   • Scalable infrastructure
   • Modular design
   • Enhanced API capabilities
   • Improved security
   • Flexible package management system
   • Configurable approval workflows
   • Extensible upgrade options

Expected Outcomes

The new portal will deliver significant benefits to all stakeholders:

For Conference Expo Team

• Reduced administrative overhead
• Improved package management
• Enhanced reporting and analytics
• Better communication tools
• Ability to quickly create and modify stand packages
• Flexible configuration of upgrade options
• Customisable approval workflows
• Automated artwork requirement generation

For Organisers

• Simplified event setup process
• More customisation options for their events
• Better visibility of sponsor activities
• Enhanced communication tools
• Clear upgrade options and pricing for their sponsors
• Automated artwork requirement generation
• Real-time feedback on submissions

For Sponsors

• Simplified stand configuration
• Streamlined artwork submission
• Improved payment experience
• Better visibility of order status
• Clear upgrade options and pricing
• Automated artwork requirement generation
• Real-time feedback on submissions
• Self-service package customisation

For Nimlok

• Increased operational efficiency
• Reduced support overhead
• Enhanced data insights
• Improved system maintainability
• Faster package creation and modification
• Reduced development effort for new features
• Better scalability for different stand options
• Improved customer satisfaction through flexibility

For Kick Digital (Developer)

• Ability to support Nimlok more effectively
• Use of modern, up-to-date tools and frameworks
• Faster and more reliable development cycles
• Easier system maintenance and extensibility
• Improved automated testing and code quality
• Reduced technical debt and legacy constraints
• Enhanced ability to deliver new features rapidly

Investment Summary

The project represents a strategic investment in Nimlok's digital infrastructure, with benefits including:

• Increased customer satisfaction through improved flexibility
• Reduced operational costs through automation
• Enhanced competitive advantage through rapid customisation
• Improved scalability for future growth
• Reduced development effort for new features
• Faster time-to-market for new stand options

Detailed cost breakdowns and resource requirements are provided in the Project Planning section.

Timeline

The project will be executed in three distinct technical phases:

1. Phase 1: Backend and API Development

   • Core architecture implementation
   • Database design and migration
   • API development
   • Business logic implementation
   • Package management system
   • Approval workflow engine
   • Integration with Nimlok's artwork platform
   • Initial testing and validation

2. Phase 2: Frontend Development

   • Nuxt project setup and configuration
   • API client development
   • TypeScript type definitions
   • Application layout and design
   • Core feature development, e.g:
     • User management
     • Stand configuration
     • Artwork review and approval process
   • Dashboard and reporting functionality
   • Testing and refinement

3. Phase 3: Launch

   • System integration testing
   • Performance optimisation
   • Security auditing
   • User acceptance testing
   • Documentation
   • Training materials
   • Production deployment
   • Customer onboarding

Detailed timelines and milestones are provided in the Project Planning section.

Next Steps

1. Client review and approval of specification
2. Finalisation of project scope and priorities
3. Resource allocation and team formation
4. Development kickoff

For detailed information about any aspect of this specification, please refer to the relevant sections in this document.

Technical Architecture

Overview

The Conference Expo Portal v2.0 will be built as a modern web application using a monolithic backend architecture with a separate frontend application. This approach provides a good balance between development efficiency and scalability for our current needs. The system consists of:

• A NestJS-based backend API that handles all business logic, data processing, and external service integrations
• A Nuxt.js frontend application that provides the user interface
• Managed services for database, caching, and file storage

This document outlines the technical architecture, technology choices, and infrastructure design.

System Architecture

The system will be built on DigitalOcean's infrastructure, comprising:

• Frontend: Nuxt.js application
• Backend: NestJS API
• Database: Managed PostgreSQL
• Cache/Queue: Managed Valkey
• Storage: DigitalOcean Spaces
• Load Balancing: DigitalOcean Load Balancer

Technology Stack

Frontend

• Framework: Nuxt.js 4.x

  • Vue.js 3.x
  • TypeScript
  • Tailwind CSS 4.x
  • Composition API

• Key Features

  • Server-side rendering
  • Type safety with auto-generated TypeScript SDK (Orval)
  • Component-based architecture
  • Responsive design
  • State management
  • Form handling
  • File upload management, including chunking of large (1 GB+) files
  • Type-safe API client with full IntelliSense

Backend

• Framework: NestJS 11.x

  • Node.js 22.x LTS
  • TypeScript
  • REST API architecture
  • OAuth 2.0 authentication
  • TypeORM
  • Swagger/OpenAPI auto-generation

• Key Features

  • Business logic implementation
  • Data validation with class-validator
  • Authentication with Passport
  • File processing
  • Background jobs with Bull
  • External service integration
  • Automatic API documentation generation

Database

• Technology: DigitalOcean Managed PostgreSQL
  • High availability
  • Automated backups
  • Query optimisation
  • Database migrations with TypeORM
  • JSON/JSONB support for flexible data structures
  • Full-text search capabilities

Infrastructure

• Hosting: DigitalOcean

  • App Platform for frontend
  • Droplets for backend
  • Managed services
  • Load balancer
  • CDN integration

• Deployment

  • Automated CI/CD
  • Zero-downtime deployments
  • Environment-based configuration
  • Health monitoring

Security Architecture

Authentication

• OAuth 2.0 via Passport.js
  • Password grant for first-party Nuxt.js application
  • Authorization code grant for third-party API clients
  • Client credentials grant for server-to-server integrations
• Token-based authentication
  • JWT tokens for stateless authentication
  • Short-lived access tokens (15 minutes) for API requests
  • Long-lived refresh tokens (30 days) for session persistence
  • Refresh tokens stored in HttpOnly cookies (XSS protection)
  • Access tokens used in Authorization headers
• Stateless API design
  • No server-side session storage
  • Token validation on each request
  • Token introspection for permission checks
• Token management
  • Automatic token refresh via Nuxt middleware
  • Token revocation on logout
  • Immediate invalidation when account status changes
• Role-based access control
  • User roles: administrator, organiser, sponsor
  • Permission scopes for third-party applications
  • Granular API endpoint protection using NestJS Guards
• Security measures
  • Rate limiting on authentication endpoints using @nestjs/throttler
  • Progressive delays after failed login attempts
  • Temporary account lockout after excessive failures
  • Audit logging of all authentication events

Data Protection

• SSL/TLS encryption
• Database encryption
• File encryption
• Secure headers
• DDoS protection

Integration Points

External Services

• Stripe

  • Payment processing using hosted Checkout

• Nimlogix API

  • Stand design integration
  • Artwork requirements
  • Artwork review and approval/rejection

Development Approach

Code Organisation

• Domain-driven design within monolithic structure
  • Clear separation of business domains (events, stands, artwork, payments)
  • Domain-specific models, services, and controllers
  • Shared infrastructure and utilities
• Type definitions
• API client generation
  • Swagger/OpenAPI documentation auto-generated by NestJS
  • TypeScript SDK auto-generated for frontend using Orval
  • Type-safe API calls with full IntelliSense support
  • Automatic synchronization between backend and frontend types
• Automated testing

Deployment Strategy

• Continuous integration
• Automated testing
• Environment-based deployments
  • Development environment for active development
  • Staging environment for pre-production testing
  • Production environment with zero-downtime deployments
• Environment-specific configuration
• Monitoring and logging

Performance Considerations

• Caching strategy
• Database optimisation
• CDN integration
• Load balancing
• Background job processing

Monitoring and Observability

• Application monitoring
• Error tracking
• Performance metrics
• Database monitoring
• Alert management

Future-Proofing

• Domain-driven design implementation
  • Business domains (events, stands, artwork, payments) as separate modules within the monolithic application
  • Clear boundaries between domains using interfaces and service classes
  • Domain-specific models and repositories
  • Shared infrastructure for cross-domain concerns
  • Preparation for potential future service extraction
• API versioning
  • Versioned API routes (e.g., /api/v1/stands, /api/v2/stands)
  • Backward compatibility for existing clients
  • Deprecation strategy for old versions
• Extensible architecture
  • Service interfaces for external integrations
  • Event-driven architecture for domain communication
  • Plugin system for extending functionality
• Scalable infrastructure
  • Horizontal scaling of application servers
  • Database read replicas
  • Caching strategy
• Maintainable codebase
  • Comprehensive documentation
  • Automated testing
  • Code quality tools
  • Regular dependency updates

For detailed API specifications, see the API Documentation. For database schema details, refer to the Database Schema.

User Experience

User Personas and Roles

1. Sponsors

Sponsors are the end-customers who will be exhibiting at conferences. They use the portal to customise their stand and manage their artwork.

Key Characteristics:

• May have varying levels of technical expertise
• Need clear guidance on artwork requirements
• Require easy access to their stand configuration
• Need to track the status of their artwork submissions
• May need to communicate with organisers

Primary Goals:

• Upload and manage artwork for their stand
• Customise their stand configuration
• Track the status of their submissions
• Communicate with organisers
• Access event information

2. Organisers

Organisers are Nimlok's direct customers who host conferences. They manage the event setup and support sponsors.

Key Characteristics:

• Familiar with conference management
• Need to manage multiple sponsors
• Require oversight of stand configurations
• Need to communicate with both sponsors and Nimlok
• May need to generate reports

Primary Goals:

• Set up and manage events
• Invite and manage sponsors
• Assign and review stand configurations
• Monitor artwork submissions
• Generate reports
• Communicate with sponsors and Nimlok

3. Admins

Admins are Nimlok team members who provide support and manage the platform. They have full system access and can perform actions on behalf of any user type.

Key Characteristics:

• Technical expertise
• Need to manage multiple events
• Require comprehensive system access
• Need to provide support to organisers
• Must ensure system compliance
• Can act on behalf of sponsors and organisers
• Have access to all user interfaces and features

Primary Goals:

• Create and manage events
• Invite and manage organisers
• Monitor system usage
• Provide technical support
• Ensure compliance
• Generate system reports
• Support users by performing actions on their behalf
• Troubleshoot and resolve user issues directly

User Journey Maps

Sponsor Journey

1. Onboarding

   • Receive invitation from organiser
   • Create account
   • View welcome tutorial
   • Access assigned stand configuration

2. Stand Customisation

   • Review assigned stand
   • Customise stand elements
   • Upload artwork
   • Submit for approval

3. Artwork Management

   • Upload artwork files
   • Track submission status
   • Receive feedback
   • Make revisions
   • Receive final approval

4. Communication

   • Contact organisers
   • Receive notifications
   • Access event updates
   • View approval status

Organiser Journey

1. Event Setup

   • Create event
   • Configure stand options
   • Set artwork requirements
   • Define approval workflows

2. Sponsor Management

   • Invite sponsors
   • Assign stand configurations
   • Monitor sponsor progress
   • Review submissions

3. Approval Process

   • Review artwork submissions
   • Provide feedback
   • Approve/reject submissions
   • Track approval status

4. Reporting

   • Generate event reports
   • Monitor progress
   • Track submissions
   • Export data

Admin Journey

1. Platform Management

   • Create new events
   • Invite organisers
   • Configure system settings
   • Monitor usage
   • Access and modify any user's data
   • Perform actions as any user type

2. Support

   • Respond to organiser queries
   • Resolve technical issues
   • Provide guidance
   • Escalate issues
   • Act on behalf of users to resolve problems
   • Demonstrate features to users

3. Compliance

   • Monitor system security
   • Review user access
   • Ensure data protection
   • Maintain audit logs
   • Review user actions
   • Manage user permissions

UI/UX Guidelines

Design Principles

• Clear and intuitive navigation
• Consistent interface across all user types
• Progressive disclosure of complex features
• Responsive design for all devices
• Accessible to all users

Interface Elements

• Dashboard views tailored to each user type
• Clear status indicators
• Intuitive file upload interface
• Streamlined approval workflows
• Comprehensive search and filtering

Accessibility Considerations

• WCAG 2.1 AA compliance
• Keyboard navigation
• Screen reader compatibility
• High contrast options
• Clear error messages
• Alternative text for images

Mobile Responsiveness

• Optimised for all screen sizes
• Touch-friendly interfaces
• Responsive image handling
• Mobile-optimised forms
• Efficient mobile navigation

User Interface Components

Common Elements

• Header with user role and navigation
• Sidebar with role-specific menu
• Main content area
• Status notifications
• Action buttons
• Search functionality

Role-Specific Features

Sponsor Interface

• Stand configuration viewer
• Artwork upload interface
• Submission status tracker
• Communication centre
• Event information display

Organiser Interface

• Event management dashboard
• Sponsor management tools
• Approval workflow interface
• Reporting tools
• Communication centre

Admin Interface

• System management dashboard
• User management tools
• Event oversight
• Support ticket system
• System monitoring
• User impersonation capabilities
• Full access to all user interfaces
• Audit log viewer
• Permission management tools

Communication Guidelines

Notifications

• Email notifications for important updates
• In-app notifications for real-time updates
• Status change alerts
• Deadline reminders
• Approval notifications

Messaging

• In-app messaging system
• Role-based communication channels
• File sharing capabilities
• Message templates
• Communication history

Error Handling

User Feedback

• Clear error messages
• Helpful recovery suggestions
• Contextual help
• Support contact options
• Progress indicators

System Messages

• Consistent message styling
• Actionable feedback
• Clear next steps
• Technical details when appropriate
• User-friendly language

Success Metrics

User Satisfaction

• Task completion rates
• Time to complete key actions
• Error rates
• Support ticket volume
• User feedback scores

System Performance

• Page load times
• Upload success rates
• System uptime
• Response times
• Mobile performance

Future Considerations

User Experience Improvements

• Enhanced mobile experience
• Advanced reporting tools
• Improved communication features
• Additional customisation options
• Integration capabilities

Accessibility Enhancements

• Additional language support
• Enhanced screen reader compatibility
• Improved keyboard navigation
• Extended colour contrast options
• Additional assistive technologies

For detailed UI mockups and wireframes, see the UI Mockups appendix.

Functional Requirements

Functional Requirements

This section details the functional requirements for the Conference Expo Portal v2.0, broken down by major feature areas. Each requirement area is documented in its own file for clarity and maintainability.

API and Integration

• API Design
  • RESTful API endpoints
  • Authentication and authorization
  • Error handling and validation
  • Rate limiting and security
  • Nimlogix API integration
  • Webhook management

User Management

• User Authentication

  • Email/password authentication
  • Session management
  • Password reset and recovery
  • Security and session handling

• User Management

  • User roles and permissions
  • Account creation and invitations
  • User profiles
  • Access control
  • User preferences

Event Management

• Event Management
  • Event creation and configuration
  • Organiser management
  • Sponsor management and invitations
  • Event settings and preferences
  • Event status and lifecycle
  • Sponsor progress dashboards

Stand and Artwork

• Stand Configuration

  • Stand package management
  • Stand customisation
  • Configuration approval workflow
  • Pricing and calculations

• Artwork Management

  • Artwork upload and validation
  • Artwork review process
  • Proof approval workflow
  • Version control
  • Nimlogix integration

Payments

• Payment Processing

  • Stripe Checkout integration
  • VAT calculation
  • Balance payments
  • Payment tracking and receipts

• Additional Fees

  • Admin fee management
  • Fee tracking and reporting
  • Balance calculations

Communication

• Communication and Notifications
  • Messaging system
  • Message routing
  • In-app notifications
  • Email notifications
  • WebSocket real-time updates
  • User notification preferences

System Administration

• System Administration

  • Default settings management
  • VAT rule configuration
  • Deadline configuration
  • Event-specific overrides
  • Admin-only access

• FAQ Management

  • Central FAQ library
  • Event-specific FAQ overrides
  • Category management
  • FAQ inheritance

Each requirement file follows a consistent structure:

• User Stories
• Functional Requirements
• Key Entities
• Edge Cases

For detailed technical specifications, see the Architecture document.

API Design Requirements

User Scenarios & Testing

User Story 1 - Basic API Authentication (Priority: P1)

The Conference Expo frontend application and internal services need to authenticate with the API using email/password credentials, receive tokens for session management, and make authenticated requests to protected endpoints.

Why this priority: Core functionality - without basic authentication, no API access is possible. This is the foundation for all other API interactions. This covers user login and server-to-server authentication for the platform's own clients.

Independent Test: Can be fully tested by implementing authentication endpoints, attempting login with valid/invalid credentials, receiving tokens, and using those tokens to access a protected test endpoint. Delivers immediate value by enabling secure API access for the platform.

Acceptance Scenarios:

1. Given a user with valid email and password credentials, When they POST to the authentication endpoint, Then they receive a response containing access token, refresh token, token type, and expiration details
2. Given an authenticated user with an expired access token but valid refresh token, When they POST to the token refresh endpoint, Then they receive a new access token without re-authenticating
3. Given an authenticated user, When they include their access token in the Authorization header of a protected endpoint request, Then the API validates the token and processes the request
4. Given a user with invalid credentials, When they attempt to authenticate, Then they receive a 401 Unauthorized response with a clear error message that doesn't reveal which credential was incorrect
5. Given an authenticated user, When they POST to the logout endpoint with their tokens, Then their refresh token is revoked and they receive a 200 success response
6. Given a user who has forgotten their password, When they POST to the password reset endpoint, Then they receive a time-limited reset link via email to update their password

---

User Story 2 - API Error Handling and Validation (Priority: P1)

API consumers need clear, consistent error responses when requests fail due to validation errors, authentication issues, authorization problems, or server errors so they can handle failures gracefully and provide appropriate feedback to end users.

Why this priority: Critical for developer experience and application stability. Poor error handling leads to confusion, increased support burden, and applications that cannot fail gracefully.

Independent Test: Can be fully tested by sending various invalid requests (malformed data, missing required fields, wrong types, unauthorized access attempts) and verifying response structure, status codes, and error messages follow consistent patterns.

Acceptance Scenarios:

1. Given a developer sends a request with missing required fields, When the API validates the request, Then it returns a 400 Bad Request with detailed validation errors listing each missing field
2. Given a developer sends a request with invalid data types, When the API validates the request, Then it returns a 400 Bad Request with clear error messages indicating expected vs provided types
3. Given an unauthenticated user attempts to access a protected endpoint, When the API checks authentication, Then it returns a 401 Unauthorized with a message indicating authentication is required
4. Given an authenticated user attempts to access a resource they don't have permission for, When the API checks authorization, Then it returns a 403 Forbidden with a message indicating insufficient permissions
5. Given a developer requests a resource that doesn't exist, When the API attempts to retrieve it, Then it returns a 404 Not Found with a clear message
6. Given a server error occurs during request processing, When the API encounters the error, Then it returns a 500 Internal Server Error with a safe error message and logs detailed error information for debugging
7. Given a developer sends a request that violates rate limits, When the API checks rate limits, Then it returns a 429 Too Many Requests with retry-after information

---

User Story 3 - Passwordless Authentication (Priority: P2)

Users need an alternative authentication method that doesn't require remembering passwords, using email-based verification codes to access the platform securely via the API.

Why this priority: Enhances security and user experience by providing a modern alternative to passwords, but email/password authentication is sufficient for launch. This is a valuable enhancement for improving user experience.

Independent Test: Can be fully tested by implementing passwordless authentication endpoint, requesting verification code, receiving email, submitting code, and receiving authentication tokens.

Acceptance Scenarios:

1. Given a user choosing passwordless authentication, When they POST their email address to the passwordless authentication endpoint, Then they receive a time-limited verification code via email
2. Given a user with a valid verification code, When they POST the code to the verification endpoint, Then they receive authentication tokens and can access the platform
3. Given a user with an expired verification code, When they attempt to use it, Then the API returns a 401 Unauthorized with a message indicating the code has expired
4. Given a user requesting too many verification codes, When rate limits are exceeded, Then the API returns a 429 Too Many Requests response

---

User Story 4 - Third-Party OAuth Authorization Flow (Priority: P3)

Third-party application developers need to integrate with the Conference Expo API through an OAuth-style authorization flow where users grant specific permissions to their application, enabling secure delegated access without sharing credentials.

Why this priority: Important for future ecosystem growth and integrations, but not needed for platform launch. The platform serves its core purpose without external third-party integrations. This enables future extensibility.

Independent Test: Can be fully tested by implementing OAuth endpoints, creating a test third-party client registration, walking through authorization flow with user consent screen, receiving scoped tokens, and verifying scope-based access control on protected endpoints.

Acceptance Scenarios:

1. Given a third-party application is registered with the platform, When they initiate the OAuth flow with requested scopes, Then the user is presented with a consent screen showing the application details and requested permissions
2. Given a user reviews a third-party authorization request, When they approve the requested scopes, Then the application receives an authorization code it can exchange for access tokens
3. Given a third-party application has an authorization code, When they POST to the token exchange endpoint, Then they receive access and refresh tokens limited to the approved scopes
4. Given a third-party application with limited scopes, When they attempt to access an endpoint outside their approved scopes, Then the API returns a 403 Forbidden with scope violation details
5. Given a user wants to revoke third-party access, When they revoke authorization, Then the third-party's refresh token is immediately invalidated and existing access tokens expire within 15 minutes
6. Given a third-party application attempts to access a 2FA-protected scope, When the API validates the request, Then it requires valid 2FA verification before granting access

---

User Story 5 - API Documentation and Discovery (Priority: P2)

Developers integrating with the API need comprehensive, accurate, and interactive documentation that describes available endpoints, request/response schemas, authentication requirements, and allows them to test requests directly from the documentation.

Why this priority: Critical for developer adoption and reducing integration time, but the API can technically function without external documentation. The auto-generated Swagger documentation from NestJS provides this capability.

Independent Test: Can be fully tested by implementing NestJS decorators and DTOs that generate Swagger documentation, accessing the Swagger UI endpoint, verifying all endpoints are documented with correct schemas, and successfully executing test requests through the Swagger interface.

Acceptance Scenarios:

1. Given a developer accesses the API documentation endpoint, When they view the Swagger UI, Then they see a complete list of all available endpoints organized by resource type
2. Given a developer views an endpoint in the documentation, When they examine its details, Then they see request parameters, request body schema, response schemas for each status code, authentication requirements, and required scopes
3. Given a developer wants to test an endpoint, When they use the "Try it out" feature in Swagger UI with their authentication token, Then they can execute real API requests and see actual responses
4. Given a developer views a data model in the documentation, When they examine its schema, Then they see all properties with types, descriptions, validation rules, and whether fields are required or optional
5. Given the API schemas change, When the backend code is updated with new types, Then the Swagger documentation automatically reflects the updated schemas without manual documentation updates

---

User Story 6 - Rate Limiting and API Quotas (Priority: P3)

API consumers need transparent rate limiting that prevents abuse while providing clear feedback about limits, current usage, and when limits reset so they can implement appropriate retry logic and stay within usage boundaries.

Why this priority: Important for system stability and preventing abuse, but not essential for initial functionality. Can be added after core API operations are stable.

Independent Test: Can be fully tested by configuring rate limits, making repeated requests to trigger limits, verifying 429 responses include rate limit headers, waiting for reset period, and confirming access is restored.

Acceptance Scenarios:

1. Given an API consumer makes requests, When they receive responses, Then each response includes headers indicating rate limit total, remaining requests, and reset time
2. Given an API consumer exceeds their rate limit, When they make another request, Then they receive a 429 Too Many Requests response with a Retry-After header indicating when they can retry
3. Given different rate limits for different endpoint types, When consumers access various endpoints, Then authentication endpoints have stricter rate limits than general data endpoints
4. Given different rate limits for authenticated vs unauthenticated requests, When consumers make requests, Then authenticated users have higher rate limits than unauthenticated access
5. Given a rate limit reset time has passed, When a previously rate-limited consumer makes a new request, Then their rate limit counter is reset and the request is processed normally

---

Edge Cases

• Concurrent token refresh: Multiple clients refresh the same token simultaneously - only first refresh succeeds, others receive 401 requiring re-authentication
• Token tampering: Client modifies token contents - API validates signature and rejects with 401 Unauthorized
• Malformed JSON: Request body contains invalid JSON - API returns 400 Bad Request with parsing error details
• Missing Content-Type header: Request omits Content-Type for endpoints expecting JSON - API returns 415 Unsupported Media Type
• Extremely large payloads: Request exceeds maximum payload size - API returns 413 Payload Too Large before processing
• Unsupported HTTP methods: Client uses wrong HTTP method for endpoint - API returns 405 Method Not Allowed with Allow header listing supported methods
• API version deprecation: Client accesses deprecated API version - API returns 410 Gone with migration guidance
• Expired password reset tokens: Client attempts to use expired password reset token - API returns 400 Bad Request indicating token is expired
• Invalid 2FA codes: Client provides wrong 2FA verification code - API returns 401 Unauthorized with remaining attempts (if applicable)
• Scope escalation attempts: Third-party app requests token refresh with expanded scopes - API rejects and requires new authorization flow
• Stale Swagger cache: Documentation shows outdated schemas - API serves Swagger spec with appropriate cache headers for freshness

Requirements

Functional Requirements

Authentication & Authorization (P1 - Launch)

• FR-001: API MUST provide an authentication endpoint that accepts email and password credentials and returns access token, refresh token, token type (Bearer), and expiration timestamp
• FR-003: API MUST provide a token refresh endpoint that accepts a valid refresh token and returns a new access token without requiring re-authentication
• FR-004: API MUST provide a logout endpoint that revokes the provided refresh token
• FR-005: API MUST validate access tokens on all protected endpoints by verifying signature, expiration, and user status
• FR-006: API MUST include authentication requirements in all endpoint documentation indicating whether authentication is required, optional, or not needed
• FR-007: API MUST provide a password reset initiation endpoint that sends a time-limited reset token via email
• FR-008: API MUST provide a password reset completion endpoint that validates the reset token and updates the user's password

Passwordless Authentication (P2)

• FR-002: API MUST provide a passwordless authentication endpoint that initiates email verification and returns authentication tokens upon successful verification code validation

Third-Party OAuth & Advanced Security (P3)

• FR-009: API MUST provide OAuth authorization endpoints for third-party applications including authorization initiation, user consent, code exchange, and token refresh
• FR-010: API MUST enforce scope-based access control on all endpoints, rejecting requests that exceed granted scopes with appropriate error responses
• FR-011: API MUST provide endpoints for 2FA setup (authenticator app enrollment) and 2FA verification code validation
• FR-012: API MUST challenge requests to 2FA-protected scopes with 2FA verification requirements

Error Handling & Validation

• FR-013: API MUST return HTTP status code 400 Bad Request for validation errors with response body containing structured error details listing each validation failure
• FR-014: API MUST return HTTP status code 401 Unauthorized when authentication is required but not provided or invalid
• FR-015: API MUST return HTTP status code 403 Forbidden when authenticated user lacks required permissions or scopes
• FR-016: API MUST return HTTP status code 404 Not Found when requested resource doesn't exist
• FR-017: API MUST return HTTP status code 429 Too Many Requests when rate limits are exceeded
• FR-018: API MUST return HTTP status code 500 Internal Server Error for unhandled server errors while logging detailed error information securely
• FR-019: API MUST return HTTP status code 503 Service Unavailable when system is under maintenance or temporarily unavailable
• FR-020: API MUST validate all request input data including required fields, data types, format constraints, and business rules before processing
• FR-021: API MUST return validation error responses in consistent structure with field name, validation rule violated, and user-friendly error message
• FR-022: API MUST sanitize error messages in production to prevent leaking sensitive system information while providing sufficient detail for debugging
• FR-023: API MUST include correlation IDs in error responses to enable error tracking and debugging across distributed systems

Request/Response Standards

• FR-024: API MUST accept and return JSON-formatted data with Content-Type application/json
• FR-025: API MUST use standard HTTP methods consistently: GET for retrieval, POST for creation, PUT for full updates, PATCH for partial updates, DELETE for removal
• FR-026: API MUST return appropriate success status codes: 200 OK for successful retrieval/update, 201 Created for successful creation with Location header, 204 No Content for successful deletion
• FR-027: API MUST support pagination for list endpoints with query parameters for page number/cursor and page size
• FR-028: API MUST include pagination metadata in list responses showing total count, current page, total pages, and links to next/previous pages
• FR-029: API MUST support filtering on list endpoints using query parameters that map to resource attributes
• FR-030: API MUST support sorting on list endpoints with query parameters specifying sort field and direction (ascending/descending)
• FR-031: API MUST accept date/time values in ISO 8601 format and return date/time values in ISO 8601 format with timezone information
• FR-032: API MUST use consistent field naming conventions in JSON responses (camelCase recommended for JavaScript/TypeScript ecosystem)
• FR-033: API MUST include appropriate cache control headers for responses to optimize client-side caching behavior

Documentation

• FR-034: API MUST generate OpenAPI/Swagger specification automatically from NestJS type definitions and decorators
• FR-035: API MUST serve interactive Swagger UI documentation at a dedicated endpoint accessible to developers
• FR-036: API MUST document all endpoints with descriptions, parameters, request bodies, response schemas, status codes, and examples
• FR-037: API MUST document authentication requirements for each endpoint including required scopes and 2FA requirements
• FR-038: API MUST document all data models with property types, descriptions, validation rules, and required/optional indicators
• FR-039: API MUST include example requests and responses in documentation for common use cases
• FR-040: API MUST allow testing endpoints directly from Swagger UI with authentication token input

Rate Limiting & Performance

• FR-041: API MUST implement configurable rate limiting on authentication endpoints to prevent brute force attacks
• FR-042: API MUST implement rate limiting on all public endpoints to prevent abuse
• FR-043: API MUST include rate limit information in response headers: limit total, remaining requests, and reset timestamp
• FR-044: API MUST return 429 Too Many Requests with Retry-After header when rate limits are exceeded
• FR-045: API MUST apply different rate limits for authenticated vs unauthenticated requests, with authenticated users receiving higher limits
• FR-046: API MUST apply stricter rate limits to sensitive endpoints (authentication, password reset) compared to general data endpoints

Security

• FR-047: API MUST require HTTPS for all endpoints in production environments
• FR-048: API MUST validate Content-Type headers and reject requests with incorrect or missing Content-Type using 415 Unsupported Media Type
• FR-049: API MUST enforce maximum request payload size limits and reject oversized requests with 413 Payload Too Large
• FR-050: API MUST implement CORS (Cross-Origin Resource Sharing) with configurable allowed origins for frontend applications
• FR-051: API MUST include security headers in all responses (X-Content-Type-Options, X-Frame-Options, X-XSS-Protection)
• FR-052: API MUST log all authentication events, authorization failures, and rate limit violations for security auditing
• FR-053: API MUST validate and sanitize all user input to prevent injection attacks
• FR-054: API MUST implement request timeouts to prevent resource exhaustion from long-running requests

Key Entities

• API Endpoint: Represents a specific API operation. Attributes include HTTP method, URL path, authentication requirement, required scopes, rate limit configuration, request schema, response schemas for each status code, and documentation text. Relationship to resource types and permission scopes.

• API Response: Represents the structure of API responses. Attributes include HTTP status code, response body schema, headers (content-type, rate limits, cache control), and correlation ID for error tracking. Consistent structure across all endpoints.

• Validation Error: Represents a structured validation failure. Attributes include field name, validation rule violated (required, type, format, range), error message, and constraint details. Used in 400 Bad Request responses.

• Rate Limit: Represents usage quotas for API consumers. Attributes include endpoint or endpoint group, limit total (requests per time window), time window duration, current usage count, reset timestamp, and consumer identifier (user, IP address, or API client). Relationship to authenticated users and third-party API clients.

• API Documentation Schema: Represents the OpenAPI/Swagger specification. Attributes include API version, base URL, available endpoints with full specifications, data model schemas, authentication schemes, and example requests/responses. Auto-generated from NestJS decorators and types.

Success Criteria

Measurable Outcomes

• SC-001: Developers can authenticate with the API and receive valid tokens in under 2 seconds using any of the supported authentication methods
• SC-002: API returns appropriate HTTP status codes (4xx for client errors, 5xx for server errors) with structured error responses for 100% of error conditions
• SC-003: API documentation (Swagger UI) automatically reflects all endpoints and schemas without manual updates when backend types change
• SC-004: API handles validation errors consistently, returning detailed field-level errors that enable frontend applications to display targeted error messages to users
• SC-005: Rate limiting prevents brute force attacks by limiting authentication endpoint requests while providing clear feedback to legitimate users about limits and reset times
• SC-006: Third-party developers can complete OAuth integration and make successful scoped API requests following documentation alone, without requiring additional support
• SC-007: API responds to authenticated requests within 500 milliseconds under normal load (excluding external integrations and database queries)
• SC-008: API maintains 99.9% uptime for all endpoints (excluding planned maintenance windows)
• SC-009: Developers report that API error messages provide sufficient information to resolve issues without examining server logs (measured through developer surveys or support ticket reduction)
• SC-010: Zero authentication token compromise incidents due to proper HTTPS enforcement, secure token generation, and HttpOnly cookie usage

User Authentication

User Scenarios & Testing

User Story 1 - Basic Email/Password Authentication (Priority: P1)

Users need to log into the Conference Expo Portal using their email and password to access their dashboard and manage events, stands, or artwork. The system must verify their identity and provide secure access with persistent sessions across page navigation.

Why this priority: This is the foundation of the entire authentication system. Without basic login/logout, no other features can function. This represents the minimum viable authentication that delivers immediate value.

Independent Test: Can be fully tested by creating a user account, logging in with valid credentials, accessing protected pages, and logging out. Delivers immediate value by enabling secure access to the platform.

Acceptance Scenarios:

1. Given a user with valid email and password credentials, When they submit their authentication details, Then they gain access to their appropriate dashboard based on their role (organiser, sponsor, or administrator) and receive authentication tokens
2. Given an authenticated user with an active session, When they navigate between pages within the platform, Then they remain authenticated without re-entering credentials through automatic token refresh
3. Given a user with invalid credentials, When they attempt to authenticate, Then they receive clear feedback indicating the authentication failed without revealing which specific credential was incorrect
4. Given an authenticated user, When they explicitly log out, Then their session tokens are revoked and they cannot access protected resources without re-authenticating
5. Given a user who has been inactive, When their access token expires (15 minutes), Then the system automatically obtains a new access token using their refresh token without requiring re-authentication
6. Given a user whose refresh token has expired (30 days), When they attempt to access protected resources, Then they are prompted to re-authenticate
7. Given an unauthenticated user navigating directly to a protected URL, When the system checks their authentication status, Then they are redirected to login and returned to their intended destination after successful authentication

---

User Story 2 - Password Reset and Security (Priority: P1)

Users who forget their password need a secure way to reset it via email, and the system must protect against brute force attacks while maintaining security across all user sessions.

Why this priority: Critical for user autonomy and security. Without password reset, users cannot recover access to their accounts. Without brute force protection, the system is vulnerable to attacks. Both are essential for a production-ready authentication system.

Independent Test: Can be fully tested by initiating password reset, receiving and using the reset link, setting a new password, and verifying old sessions are invalidated. Security can be tested by attempting multiple failed logins and verifying rate limiting.

Acceptance Scenarios:

1. Given a user who has forgotten their password, When they initiate password reset, Then they receive a one-time use reset link via email valid for 1 hour
2. Given a user with a valid password reset link, When they set a new password meeting complexity requirements (8+ characters, uppercase, lowercase, number), Then all their existing sessions are invalidated and they must log in again on all devices
3. Given a user attempting multiple failed logins, When the system detects excessive authentication attempts, Then configurable rate limiting is applied to prevent brute force attacks
4. Given a user with an expired or already-used password reset link, When they attempt to use it, Then the link is invalid and they must request a new reset link
5. Given a user whose account is deactivated or whose role changes, When the system processes this change, Then all refresh tokens are immediately revoked (preventing new access tokens) and existing access tokens remain valid up to 15 minutes until natural expiration

---

User Story 3 - Multi-Device and "Remember Me" Support (Priority: P2)

Users need to access the platform from multiple devices simultaneously (desktop, tablet, mobile) and have the option to stay logged in across browser sessions with "remember me" functionality.

Why this priority: Important for user convenience and real-world usage patterns, but the system can function without it initially. Users can still authenticate on single devices. This enhances the experience but isn't blocking.

Independent Test: Can be fully tested by logging in on multiple devices simultaneously, verifying independent sessions, using "remember me" option, closing/reopening browser, and verifying persistent authentication.

Acceptance Scenarios:

1. Given a user authenticated on multiple devices, When they perform actions on one device, Then their authentication remains valid on all devices unless explicitly logged out or their account is deactivated
2. Given a user attempting to authenticate while already having an active session, When they log in, Then they receive a new set of tokens without affecting existing sessions on other devices
3. Given a user who enabled "remember me" during login, When they close and reopen their browser, Then they remain authenticated without re-entering credentials (persistent cookie with configurable duration)
4. Given a user who disabled "remember me" during login, When they close and reopen their browser, Then they must re-authenticate (session cookie deleted on browser close)
5. Given a user who updates their password, When the system processes the credential change, Then all existing refresh tokens are revoked requiring re-authentication on all devices

---

User Story 4 - Passwordless Authentication (Priority: P2)

Users need an alternative authentication method that doesn't require remembering passwords, using email-based verification codes or links to access the platform securely.

Why this priority: Enhances security and user experience by providing a modern alternative to passwords, but email/password authentication is sufficient for MVP. This is a valuable enhancement but not essential for initial launch.

Independent Test: Can be fully tested independently by requesting passwordless login, receiving verification code via email, submitting code, and gaining access to the platform without ever using a password.

Acceptance Scenarios:

1. Given a user choosing passwordless authentication, When they enter their email address, Then they receive a time-limited verification code or link via email
2. Given a user with a valid verification code, When they submit it, Then they are authenticated and receive access tokens, gaining access to their dashboard
3. Given a user with an expired verification code, When they attempt to use it, Then authentication fails and they must request a new code
4. Given a user authenticating via passwordless method, When they later access a scope requiring 2FA (different from primary auth), Then they receive a separate 2FA verification challenge

---

User Story 5 - Third-Party OAuth Authorization (Priority: P3)

External third-party applications need to integrate with the Conference Expo API through OAuth-style authorization where users grant specific permissions (scopes) to these external applications for delegated access.

Why this priority: Important for future ecosystem growth and external integrations, but not needed for platform launch. The system serves its primary purpose without third-party integrations. This enables future extensibility. Note: P1 covers authentication for the platform's own frontend/backend - this story is specifically for external third-party app integration with user consent screens.

Independent Test: Can be fully tested independently by registering a third-party application, initiating OAuth flow, approving scopes, receiving tokens, making API requests within scope, and attempting out-of-scope requests.

Acceptance Scenarios:

1. Given a third-party application seeking access to the API, When a user reviews the authorization request, Then they see the requested permission scopes and application details on a consent screen
2. Given a user approving third-party authorization, When they grant permission, Then the application receives access credentials limited to only the approved scopes (e.g., events:read, stands:write)
3. Given a third-party application with limited scopes, When it attempts to access an API endpoint outside its approved scopes, Then the request is denied with a clear scope violation error
4. Given a user who wants to revoke third-party access, When they revoke authorization, Then the authorization is immediately removed from database, refresh tokens cannot obtain new access tokens, and existing access tokens remain valid up to 15 minutes until natural expiration
5. Given a third-party application with valid tokens, When they make API requests within their approved scopes, Then the requests are processed successfully with appropriate access control

---

User Story 6 - Two-Factor Authentication (2FA) for Sensitive Scopes (Priority: P3)

Users and third-party applications need additional security verification when accessing sensitive operations through scope-based 2FA using authenticator apps (TOTP) or email verification codes.

Why this priority: Enhances security for sensitive operations, but basic authentication is sufficient for initial platform usage. This is a valuable security enhancement for production but can be added after core authentication is stable.

Independent Test: Can be fully tested independently by setting up authenticator app, configuring 2FA, accessing 2FA-protected scope, providing TOTP code, and verifying access is granted only with valid 2FA verification.

Acceptance Scenarios:

1. Given a user setting up 2FA, When they configure an authenticator app, Then they receive a secret key and can generate time-based one-time passwords (TOTP) for subsequent challenges
2. Given a user without an authenticator app configured, When 2FA is required for a scope, Then they receive a time-limited verification code via email as a fallback method
3. Given a user or third-party application attempting to access a scope requiring 2FA, When they make the request, Then they must provide valid 2FA verification (authenticator code or email code) before access is granted
4. Given a user with invalid or expired 2FA codes, When they attempt verification, Then the system applies rate limiting to prevent brute force attacks on verification codes
5. Given a user who loses access to their authenticator device, When they need to access 2FA-protected scopes, Then they can use email-based verification codes to regain access and reconfigure their authenticator
6. Given a scope's 2FA requirement is changed in configuration, When the change takes effect, Then existing tokens remain valid until expiration but new requests enforce the updated 2FA requirement

---

Edge Cases

• Multiple device access: Users can authenticate on multiple devices simultaneously, with sessions remaining independent and valid across all devices
• Account status changes: When a user's account is deactivated or role changes, all refresh tokens are immediately revoked (preventing new access tokens), but existing access tokens remain valid up to 15 minutes until natural expiration
• Existing active session: Users attempting to authenticate while already having an active session will receive a new set of tokens without affecting existing sessions on other devices
• Repeated failed authentication: System applies configurable rate limiting on authentication attempts to protect against brute force attacks
• Credential updates: When a user updates their authentication credentials (password change or password reset), all existing refresh tokens are revoked requiring re-authentication on all devices
• Expired password reset link: When a user attempts to use a password reset link after 1 hour expiration or after it's already been used, the link is invalid and user must request a new reset link
• Direct URL access: Unauthenticated users navigating directly to protected URLs are redirected to authentication, then returned to their intended destination after successful login
• Passwordless vs 2FA codes (P2/P3): Email-based passwordless login (primary auth) and email-based 2FA (secondary auth) are separate features - a user could authenticate via passwordless email code, then later trigger 2FA email code when accessing sensitive scope

P3 Edge Cases (Third-Party OAuth & 2FA)

• Third-party revocation: When a user revokes authorization for a third-party application, the authorization is immediately removed from database (preventing new tokens), refresh tokens cannot be used to obtain new access tokens, but existing access tokens remain valid up to 15 minutes until natural expiration (standard stateless JWT behavior)
• 2FA requirement changes: When a scope's 2FA requirement is changed in configuration, existing tokens for that scope remain valid until expiration but new requests to that scope enforce the updated 2FA requirement
• 2FA method unavailable: When a user without an authenticator app configured attempts to access a 2FA-required scope, the system automatically sends an email verification code as fallback
• Lost authenticator device: Users who lose access to their authenticator app can use email-based verification codes to access 2FA-protected scopes and reconfigure their authenticator
• Invalid 2FA codes: System applies rate limiting to 2FA verification attempts to prevent brute force attacks on verification codes

Requirements

Functional Requirements

Core Authentication (P1)

• FR-001: System MUST verify user identity before granting access to any protected resources
• FR-002: System MUST support email/password authentication as primary authentication method
• FR-003: System MUST enforce minimum password complexity of 8 characters including at least one uppercase letter, one lowercase letter, and one number
• FR-004: System MUST maintain user sessions that persist across page navigation within the platform
• FR-005: System MUST terminate sessions when users explicitly log out
• FR-006: System MUST automatically expire access tokens after 15 minutes and refresh tokens after 30 days
• FR-007: System MUST distinguish between different user types (organisers, sponsors, administrators) and route them appropriately after authentication
• FR-008: System MUST prevent access to protected resources for unauthenticated users
• FR-009: System MUST display clear, user-friendly error messages when authentication fails without revealing sensitive security information
• FR-010: System MUST handle the transition from unauthenticated to authenticated state smoothly, redirecting users to their intended destination after successful authentication
• FR-011: System MUST provide clear visual indication of authentication status throughout the user interface
• FR-012: System MUST maintain authentication tokens securely so that tokens cannot be hijacked or forged (HTTPS only, HttpOnly cookies for refresh tokens, secure token generation)

Password Reset and Security (P1)

• FR-013: System MUST provide password reset mechanism that sends time-limited reset link (valid 1 hour) via email
• FR-014: Password reset links MUST be one-time use only
• FR-015: Upon successful password reset, all existing refresh tokens MUST be revoked requiring users to re-authenticate on all devices
• FR-016: System MUST protect against brute force attacks through configurable rate limiting on authentication endpoints
• FR-017: System MUST immediately revoke all refresh tokens when a user's account is deactivated or their role changes (preventing new access tokens). Existing access tokens remain valid until natural expiration (max 15 minutes)
• FR-018: System MUST log all authentication events (successful logins, failed attempts, logouts) for security auditing

Multi-Device Support (P2)

• FR-019: System MUST allow concurrent sessions from the same user account across multiple devices
• FR-020: System MUST allow users to have multiple active sessions on different devices simultaneously
• FR-021: System MUST provide optional "remember me" functionality that controls refresh token cookie persistence. When enabled, refresh token stored as persistent cookie (duration configurable). When disabled, refresh token stored as session cookie (deleted when browser closes)
• FR-022: When a user updates their authentication credentials, all existing refresh tokens MUST be revoked requiring re-authentication on all devices

Passwordless Authentication (P2)

• FR-023: System MUST support passwordless authentication via email-based verification as alternative primary authentication method
• FR-024: For passwordless authentication, system MUST send time-limited verification codes or links to the user's registered email address
• FR-025: Email-based passwordless codes MUST be separate from email-based 2FA codes (primary vs secondary authentication)

Single Sign-On (P2)

• FR-026: System MUST support single sign-on, allowing users to access all conference events they have permission for with one authentication

Third-Party OAuth (P3 - External App Integration)

Note: These requirements are for external third-party applications integrating with the platform (with user consent screens). P1 covers authentication for the platform's own frontend/backend clients.

• FR-027: System MUST support granular permission scopes for third-party applications based on resource types and actions (e.g., events:read, stands:write, artwork:read)
• FR-028: System MUST present requested scopes to users for approval before authorizing third-party applications
• FR-029: System MUST enforce scope-based access control on all API endpoints, denying requests that exceed granted scopes
• FR-030: Third-party application tokens MUST be limited to only the scopes explicitly approved by the user
• FR-031: System MUST revoke third-party application authorization when user revokes access, preventing issuance of new tokens. Existing access tokens remain valid until natural expiration (max 15 minutes), existing refresh tokens become invalid immediately

Two-Factor Authentication (P3)

• FR-032: System MUST allow users to set up authenticator apps using TOTP (Time-based One-Time Password) standard for secondary authentication (2FA) verification
• FR-033: System MUST support email-based verification codes as a fallback secondary authentication (2FA) method when users have not configured an authenticator app
• FR-034: Certain permission scopes MUST be configured to require 2FA verification (secondary authentication) before access is granted
• FR-035: Which scopes require 2FA MUST be configurable without code changes
• FR-036: System MUST challenge users with 2FA verification when accessing endpoints protected by 2FA-required scopes
• FR-037: System MUST deny access to 2FA-protected scopes when valid 2FA verification is not provided
• FR-038: System MUST apply rate limiting to 2FA verification attempts to prevent brute force attacks on verification codes

Non-Functional Requirements

• NFR-001: System MUST support up to 500 concurrent authenticated users without performance degradation
• NFR-002: Authentication requests MUST complete within 2 seconds under normal load conditions
• NFR-003: Token refresh operations MUST complete within 500 milliseconds
• NFR-004: System MUST maintain authentication service availability of 99.9% (excluding planned maintenance)
• NFR-005: Rate limiting thresholds for authentication endpoints MUST be configurable without code changes
• NFR-006: "Remember me" persistent cookie duration MUST be configurable without code changes

Key Entities

• User: Represents an individual with access to the platform. Attributes include identity information (email, name), role type (organiser, sponsor, administrator), account status (active, deactivated), and credential information. Relationships to events, organisations, and authentication history.

• Session: Represents metadata tracking for an active authenticated period. Used for audit logging and "active sessions" UI, NOT for storing authentication state (which lives in client-side tokens for stateless API design). Attributes include session identifier, creation time, last activity time, expiration time, user association, device/location information (IP address, user agent). Enables users to view where they're logged in and revoke specific sessions.

• Authentication Credential: Represents the means by which a user proves their identity. Attributes include credential type (password with complexity requirements, or passwordless verification token), verification status, creation date, and last updated date. Relationship to user account.

• Verification Token: Represents a time-limited token for email-based verification. Attributes include token code, associated email address, token purpose (passwordless login, 2FA verification, or password reset), expiration time, usage status (used/unused), and creation timestamp. Used for passwordless authentication (primary) and email-based 2FA fallback (secondary).

• Authentication Event: Represents a security audit record of authentication activity. Attributes include event type (login attempt, successful login, logout, password reset), timestamp, user identifier, source information (IP address, device type), and outcome (success or failure reason).

• API Client: Represents a third-party application authorized to access the API. Attributes include client identifier, client name, approved permission scopes (granular resource:action format), authorization status, creation date, and last used date. Relationship to authorizing user and issued tokens.

• Permission Scope: Represents a specific permission for API access. Attributes include scope identifier (e.g., "events:read", "stands:write"), resource type, action type (read, write, delete), description, and 2FA requirement flag (configurable). Used to control third-party application access at granular level.

• 2FA Configuration: Represents a user's two-factor authentication setup. Attributes include user association, authenticator type (TOTP app or email fallback), secret key (for TOTP), enabled status, setup date, and last used date. Relationship to user account.

• 2FA Verification Code: Represents a time-limited verification code for 2FA challenges. Attributes include code value, associated user, generation timestamp, expiration time, usage status (used/unused), and verification method (authenticator app or email). Used for scope-based 2FA enforcement.

Success Criteria

Measurable Outcomes

• SC-001: Users can complete login and access their dashboard in under 2 seconds with valid credentials
• SC-002: System handles 500 concurrent authenticated users without performance degradation or failed authentication requests
• SC-003: Password reset requests complete within 3 seconds and reset emails arrive within 1 minute
• SC-004: 95% of authentication requests complete successfully on first attempt for users with valid credentials
• SC-005: Token refresh operations complete within 500 milliseconds, enabling seamless session continuation
• SC-006: Authentication service maintains 99.9% uptime measured across a calendar month (excluding planned maintenance)
• SC-007: Users successfully authenticate across multiple devices simultaneously without conflicts or session interference
• SC-008: Zero unauthorized access incidents due to token compromise, brute force attacks, or session hijacking
• SC-009: Users who enable "remember me" remain authenticated for the configured duration (default 30 days) across browser restarts
• SC-010: Rate limiting successfully prevents brute force attacks by limiting authentication attempts to configured thresholds without impacting legitimate users

User Management

User Scenarios & Testing

User Story 1 - Admin Creates Organiser Accounts (Priority: P1)

Administrators need to create organiser accounts for conference organisers who will manage events and invite sponsors, enabling the hierarchical user structure of the platform.

Why this priority: Foundation of the platform's user hierarchy. Without organisers, no events can be managed and no sponsors can be invited. This is the essential first step in onboarding.

Independent Test: Can be fully tested by admin logging in, creating an organiser account with required details, and verifying the organiser receives an invitation email and can set up their account.

Acceptance Scenarios:

1. Given an authenticated administrator, When they create a new organiser account with name, email, and initial details, Then the system creates the organiser account and sends an invitation email with a secure setup link
2. Given an administrator creating an organiser, When they use an email address already in the system, Then the system prevents duplicate accounts and displays a clear error message
3. Given an organiser invitation has been sent, When the organiser clicks the setup link within 7 days, Then they can set their password and complete their profile setup
4. Given an organiser invitation link has expired (>7 days), When the organiser attempts to use it, Then the system rejects the link and provides instructions to request a new invitation
5. Given an administrator viewing organisers, When they access the organiser list, Then they see all organisers with their status (invited, active, deactivated) and last activity date

---

User Story 2 - Organiser Creates Sponsor Accounts (Priority: P1)

Organisers need to create sponsor accounts and invite sponsors to participate in their events, managing the complete sponsor onboarding workflow.

Why this priority: Core workflow enabling sponsors to access the platform. Without this, sponsors cannot be invited to events or assigned to stands. Essential for platform functionality.

Independent Test: Can be fully tested by organiser logging in, creating a sponsor account, and verifying the sponsor receives invitation and can complete setup successfully.

Acceptance Scenarios:

1. Given an authenticated organiser, When they create a new sponsor account with name, email, and company details, Then the system creates the sponsor account and sends an invitation email with a secure setup link
2. Given an organiser creating a sponsor, When they provide required information (name, email, company), Then the system validates all fields before creating the account
3. Given a sponsor invitation has been sent, When the sponsor clicks the setup link within 7 days, Then they can set their password and complete their profile
4. Given an organiser viewing their sponsors, When they access the sponsor list, Then they see sponsors they created with their status and last activity
5. Given an organiser needs to re-send an invitation, When they request to resend for a pending sponsor, Then the system generates a new secure link and sends a fresh invitation email

---

User Story 3 - User Profile Management (Priority: P1)

All users need to view and update their own profile information including personal details, contact information, and preferences to keep their account information current.

Why this priority: Essential for all user types to maintain accurate account information and preferences. Required for communication, identification, and personalization. Core self-service functionality.

Independent Test: Can be fully tested by any user logging in, accessing their profile, updating information, and verifying changes are saved and displayed correctly.

Acceptance Scenarios:

1. Given an authenticated user, When they access their profile, Then they see their current information including name, email, job title, company, and profile picture
2. Given a user editing their profile, When they update their name, job title, or contact details, Then the system saves the changes and displays a confirmation message
3. Given a user wants to change their email address, When they update their email, Then the system sends a verification email to the new address and requires confirmation before updating
4. Given a user uploading a profile picture, When they select an image file, Then the system validates file type and size, uploads the image, and displays it on their profile
5. Given a user viewing their profile, When they see their role (admin, organiser, or sponsor), Then they understand their account type and access level

---

User Story 4 - User Account Status Management (Priority: P2)

Administrators and organisers need to activate, deactivate, and manage user account statuses to control access and maintain security across the platform.

Why this priority: Important for security and access control, but platform can function initially with all users active. Enhances administrative capabilities but not blocking for core functionality.

Independent Test: Can be fully tested by admin/organiser deactivating a user account, verifying that user cannot log in, then reactivating and verifying access is restored.

Acceptance Scenarios:

1. Given an administrator viewing a user account, When they deactivate the account, Then the user's active sessions are invalidated and they cannot log in until reactivated
2. Given an organiser managing their sponsors, When they deactivate a sponsor account, Then that sponsor loses access but their data and stand assignments are preserved
3. Given an administrator reactivating a user, When the account status changes to active, Then the user receives a notification and can log in again with their existing credentials
4. Given a deactivated user attempting to log in, When they submit their credentials, Then the system displays a clear message indicating their account is deactivated and provides contact information
5. Given an administrator viewing user lists, When filtering by status, Then they can see all users or filter to active, deactivated, or pending invitation statuses

---

User Story 5 - Bulk User Operations (Priority: P2)

Organisers need to perform bulk operations like inviting multiple sponsors at once or importing user data from CSV to efficiently manage large numbers of users.

Why this priority: Valuable for efficiency and scalability, especially for large events, but platform can function with individual user creation. Enhances user experience but not essential for MVP.

Independent Test: Can be fully tested by organiser uploading a CSV with multiple sponsor records, verifying all valid records create accounts and send invitations, and invalid records are reported with clear errors.

Acceptance Scenarios:

1. Given an organiser wants to invite multiple sponsors, When they upload a CSV file with sponsor details (name, email, company), Then the system validates all records and creates accounts for valid entries
2. Given a bulk import contains errors, When the system processes the file, Then it reports all validation errors with row numbers and specific issues for correction
3. Given an organiser performing bulk operations, When the process completes, Then they receive a summary showing successful creations, failures, and duplicate emails
4. Given an organiser wants to resend invitations to multiple pending users, When they select users and bulk resend, Then all selected users receive fresh invitation emails with new secure links
5. Given an administrator managing multiple events, When they export user data, Then they receive a CSV with all user information for their records or external processing

---

User Story 6 - User Activity Audit Trail (Priority: P3)

Administrators need to view detailed audit logs of user activities including logins, profile changes, and administrative actions for security monitoring and compliance.

Why this priority: Important for security and compliance but not needed for core platform functionality. Can be added after platform is stable and being used in production.

Independent Test: Can be fully tested by performing various user actions (login, profile update, user creation) and verifying all actions are logged with timestamps, user identifiers, and action details.

Acceptance Scenarios:

1. Given an administrator accessing audit logs, When they view user activity, Then they see chronological log of all user actions with timestamps, action types, and affected entities
2. Given an administrator investigating account security, When they view a specific user's audit trail, Then they see all login attempts, profile changes, and access patterns for that user
3. Given an administrator monitoring the platform, When they filter audit logs by date range or action type, Then they can identify patterns or investigate specific incidents
4. Given an administrator reviewing compliance records, When they export audit logs, Then they receive complete records suitable for compliance reporting and security audits

---

Edge Cases

• Duplicate email addresses: System prevents creating multiple accounts with the same email address, displays clear error with resolution instructions
• Expired invitations: Users with expired invitation links (>7 days) cannot complete setup and must request new invitation from their inviter
• Orphaned sponsors: If a sponsor is created and the organiser who created them is deactivated, the sponsor account remains active for future assignment to events/stands
• Email verification failure: If email verification for profile changes fails to deliver, user can request resend and system tracks verification attempts
• Concurrent profile updates: If same user updates profile from multiple devices simultaneously, last write wins with timestamp tracking
• Invitation link reuse: Used invitation links cannot be reused for security; system requires new invitation generation
• Account deletion vs deactivation: Deactivation preserves all data and allows reactivation; deletion permanently removes user but keeps audit trail
• Profile picture file limits: System enforces file size (max 5MB) and type restrictions (JPEG, PNG) for profile pictures with clear error messages
• Bulk import duplicates: When importing multiple users via CSV, system skips duplicate emails and reports them in summary without failing entire import
• Organiser viewing sponsor list: Organisers only see sponsors they created, not sponsors created by other organisers, ensuring data isolation

Requirements

Functional Requirements

User Account Creation (P1)

• FR-001: Administrators MUST be able to create organiser accounts with required fields: name, email, job title, and company
• FR-002: Organisers MUST be able to create sponsor accounts with required fields: name, email, job title, and company
• FR-003: System MUST validate email addresses for correct format and prevent duplicate email addresses across all user types
• FR-004: System MUST generate secure, unique invitation links for new users with 7-day expiration
• FR-005: System MUST send invitation emails automatically upon account creation with secure setup links
• FR-006: System MUST require email verification when users change their email address in profile settings

User Invitation System (P1)

• FR-007: Invitation links MUST expire after 7 days for security
• FR-008: Invitation links MUST be single-use and cannot be reused after account setup completion
• FR-009: System MUST allow admins and organisers to resend invitations, generating new secure links when requested
• FR-010: Users MUST be able to set their initial password through the invitation setup flow, subject to password complexity requirements (8+ characters, uppercase, lowercase, number)
• FR-011: System MUST display clear error messages when invitation links are expired, invalid, or already used
• FR-012: System MUST track invitation status: pending, accepted, expired for administrative visibility

User Profile Management (P1)

• FR-013: Users MUST be able to view their complete profile information including personal details, contact information, and role
• FR-014: Users MUST be able to update their own profile information including name, job title, phone number, and profile picture
• FR-015: System MUST validate profile picture uploads for file type (JPEG, PNG), size (max 5MB), and dimensions
• FR-016: Users MUST be able to view their role (admin, organiser, sponsor) in their profile
• FR-017: System MUST send email notifications when critical profile changes occur (email address change, password change)
• FR-018: System MUST maintain change history for profile updates for audit purposes

User Access Control (P1)

• FR-019: System MUST implement role-based access control with three distinct roles: Administrator, Organiser, Sponsor
• FR-020: Administrators MUST have full platform access including all user management functions
• FR-021: Organisers MUST only be able to manage sponsor accounts they created
• FR-022: System MUST enforce access controls at the API level, preventing unauthorized access regardless of UI manipulation
• FR-023: Sponsors MUST have accounts ready for future assignment to events and stands (assignment handled in Event Management spec)

Account Status Management (P2)

• FR-024: Administrators MUST be able to activate, deactivate, and reactivate user accounts
• FR-025: Organisers MUST be able to deactivate and reactivate sponsor accounts they created
• FR-026: System MUST immediately revoke all active sessions when a user account is deactivated
• FR-027: Deactivated users MUST be prevented from logging in with clear status messaging
• FR-028: System MUST preserve all user data when accounts are deactivated to allow reactivation
• FR-029: System MUST notify users via email when their account status changes (deactivated, reactivated)

Bulk Operations (P2)

• FR-030: Organisers MUST be able to import multiple sponsor accounts via CSV file upload
• FR-031: System MUST validate CSV data for required fields, format correctness, and duplicate detection
• FR-032: System MUST provide detailed error reporting for bulk import failures with row numbers and specific validation issues
• FR-033: System MUST generate summary reports after bulk operations showing successful creations, failures, and skipped duplicates
• FR-034: Organisers MUST be able to resend invitations to multiple users in bulk operation
• FR-035: Administrators MUST be able to export user data to CSV format for reporting and backup purposes
• FR-036: System MUST provide a downloadable CSV template with correct column headers and example data for bulk user import operations

Audit and Activity Tracking (P3)

• FR-037: System MUST log all user account creation, modification, and deactivation events with timestamp and acting user
• FR-038: System MUST log all authentication events including successful and failed login attempts
• FR-039: Administrators MUST be able to view comprehensive audit logs filtered by date range, user, or action type
• FR-040: System MUST retain audit logs for minimum 12 months for compliance and security investigation
• FR-041: Audit logs MUST be exportable for external compliance reporting and security analysis

Non-Functional Requirements

• NFR-001: User account creation operations MUST complete within 2 seconds excluding email delivery
• NFR-002: Profile updates MUST save within 1 second with immediate UI feedback
• NFR-003: User lists MUST load and display within 2 seconds for lists up to 1000 users
• NFR-004: System MUST support 100 concurrent user management operations without performance degradation
• NFR-005: Bulk import operations MUST process at least 100 records per second
• NFR-006: Email invitations MUST be queued and delivered within 2 minutes of account creation
• NFR-007: Profile picture uploads MUST complete within 5 seconds for files up to 5MB

Key Entities

• User: Represents an individual with access to the platform. Attributes include name (first, last), email (unique), job title, company, phone number, profile picture URL, role (admin, organiser, sponsor), account status (pending, active, deactivated), invitation status, created date, last login date, created by (for organisers/sponsors). Relationships to created users (for admins/organisers) and audit trail. Note: Sponsor assignment to stands/events will be handled in Event Management specification.

• Invitation: Represents a secure setup link sent to new users. Attributes include unique secure token, target user reference, inviting user reference, creation timestamp, expiration timestamp (7 days), status (pending, accepted, expired, revoked), email sent status. Relationship to user account and inviting user.

• Profile: Represents user profile information and preferences. Attributes include user reference, personal details, contact information, profile picture, timezone preference, notification preferences, last updated timestamp, change history. Relationship to user account.

• User Activity Log: Represents audit trail of user actions. Attributes include user reference, action type (create, update, delete, login, logout, deactivate), affected entity type and ID, timestamp, IP address, user agent, previous values (for updates), new values. Relationship to user account and affected entities.

• Role: Represents user access level and permissions. Attributes include role type (admin, organiser, sponsor), permission set, description. Defines what actions users can perform and what data they can access.

Success Criteria

Measurable Outcomes

• SC-001: Administrators can create organiser accounts and organisers can create sponsor accounts in under 30 seconds per account including email invitation delivery
• SC-002: 95% of invited users successfully complete account setup within 7-day invitation period
• SC-003: Users can update their profile information in under 1 minute with immediate confirmation feedback
• SC-004: Bulk import operations process at least 100 sponsor accounts in under 2 minutes with complete error reporting
• SC-005: System handles 500 total users (admins, organisers, sponsors) without performance degradation
• SC-006: Zero unauthorized access incidents due to proper role-based access control enforcement
• SC-007: Invitation email delivery success rate exceeds 99% with delivery within 2 minutes
• SC-008: Users find their profile and update functions on first attempt without support assistance
• SC-009: Account deactivation takes effect immediately with all active sessions revoked within 5 seconds
• SC-010: Organiser can view accurate list of all sponsors they created with current status in under 2 seconds

Event Management

User Scenarios & Testing (mandatory)

User Story 1 - Admin Creates and Publishes Event (Priority: P1)

An admin creates a new conference event with all required details (name, dates, venue, timezone), configures stand packages and artwork requirements, assigns organisers, and publishes the event so sponsors can be invited.

Why this priority: This is the foundational capability - without event creation, no other functionality can exist. It represents the minimum viable feature that delivers value.

Independent Test: Can be fully tested by creating an event, configuring basic settings, assigning at least one organiser, and publishing it. Delivers a functional event ready for sponsor participation.

Acceptance Scenarios:

1. Given an admin is logged in, When they create a new event with name "Tech Summit 2025", dates (start: 2025-06-15, end: 2025-06-17), venue "Excel London", and timezone "Europe/London", Then the event is saved in draft status
2. Given an event in draft status exists, When admin adds configuration deadline (2025-05-01) and artwork deadline (2025-05-15) and validates dates are sequential, Then deadlines are saved correctly
3. Given an event has all required fields completed, When admin assigns an organiser with "admin" permissions, Then the organiser can access the event
4. Given an event in draft status with all required fields, When admin publishes the event, Then status changes to published and organisers are notified
5. Given an admin attempts to create an event, When they use a name that already exists for the same organiser, Then system rejects with validation error

---

User Story 2 - Organiser Invites and Manages Sponsors (Priority: P2)

An organiser views their assigned events, generates secure invitation links for sponsors, sends invitations via email, tracks invitation status, and assigns sponsors to specific stands within the event.

Why this priority: Once events exist, the next critical step is getting sponsors into the system. This enables the core user base to participate.

Independent Test: Can be tested independently by having a published event, generating invitation links, sending emails, and verifying sponsor registration flow. Delivers functional sponsor onboarding.

Acceptance Scenarios:

1. Given an organiser is logged in, When they view their dashboard, Then only events they are assigned to are displayed
2. Given an organiser views a published event, When they generate an invitation link for email "sponsor@company.com", Then a unique secure token is created and invitation is sent
3. Given a sponsor receives an invitation email, When they click the link and complete registration, Then they are assigned to the event and associated stand(s)
4. Given an organiser needs to resend an invitation, When they select "resend" for a sponsor, Then a new secure link is generated and previous link is invalidated
5. Given an organiser has a list of 50 sponsors to invite, When they use bulk invitation tool with validated email addresses, Then all invitations are sent with tracking status

---

User Story 3 - Sponsor Manages Multiple Stands Across Events (Priority: P2)

A sponsor logs in and views all events they are participating in, sees their assigned stands for each event, switches between different stands or events, and views event-specific information (timezone, venue, deadlines).

Why this priority: Sponsors often participate in multiple events or manage multiple stands. This improves user experience and efficiency for the primary end users.

Independent Test: Can be tested by assigning a sponsor to multiple stands across different events, logging in, and verifying stand switching and contextual information display. Delivers enhanced sponsor workflow.

Acceptance Scenarios:

1. Given a sponsor is assigned to 3 stands across 2 events, When they log in, Then they see all events and stands listed with event details
2. Given a sponsor is viewing Stand A in Event 1, When they switch to Stand B in Event 2, Then context changes to show Event 2 timezone, deadlines, and venue information
3. Given a sponsor views an event, When they check submission deadlines, Then they see configuration deadline and artwork deadline in the event's timezone
4. Given a sponsor has multiple stands in the same event, When they switch between stands within that event, Then stand-specific configuration persists and loads correctly
5. Given a sponsor attempts to access a stand they are not assigned to, When they try to load it, Then access is denied via permission system

---

User Story 4 - Admin Archives Completed Event (Priority: P3)

An admin reviews completed events, archives them according to data retention policies, ensures audit logs and historical data remain accessible, and verifies archived events do not appear in active lists but can be retrieved for reference.

Why this priority: While important for long-term system health, this can be deferred until the core event lifecycle is operational.

Independent Test: Can be tested by creating completed events, archiving them, verifying they disappear from active lists, and confirming historical data retrieval works. Delivers data governance compliance.

Acceptance Scenarios:

1. Given an event has passed its end date, When admin views completed events list, Then they see events eligible for archiving
2. Given admin selects an event to archive, When they confirm archiving action, Then status changes to archived and soft delete is applied
3. Given an event is archived, When organisers view their dashboard, Then the archived event does not appear in active event lists
4. Given an event is archived, When admin searches for it by name or ID, Then they can retrieve it and view all historical data including audit logs
5. Given an archived event contains sponsor configurations and artwork, When retrieved for reference, Then all data is accessible for seven-year retention period

---

User Story 5 - Admin and Organiser Monitor Sponsor Progress (Priority: P2)

An admin or organiser views an event dashboard showing all sponsors and their progress through required steps: stand configuration status, artwork upload status, payment status, and proof approval status. They can filter by completion status, identify sponsors who are behind schedule, and take action (send reminders, contact directly) to ensure all sponsors complete their required tasks before deadlines.

Why this priority: This oversight capability is critical for event organisers to ensure all sponsors are ready for the event. Without this, organisers would need to manually track each sponsor individually, leading to missed incomplete submissions and last-minute scrambles.

Independent Test: Can be tested by creating an event with multiple sponsors at different completion stages, viewing the progress dashboard, filtering by status, and verifying progress indicators are accurate. Delivers essential event management oversight.

Acceptance Scenarios:

1. Given an organiser views an event with 20 assigned sponsors, When they access the sponsor progress dashboard, Then they see a list showing each sponsor with completion indicators for: stand configuration (complete/incomplete), artwork upload (complete/incomplete/pending approval), payment (complete/incomplete), and proof approval (complete/incomplete)
2. Given an organiser views the sponsor progress dashboard, When they filter by "incomplete artwork", Then only sponsors who have not uploaded artwork or have pending artwork approvals are displayed
3. Given a sponsor has completed stand configuration but not uploaded artwork, When organiser views that sponsor's progress, Then stand configuration shows green checkmark, artwork shows amber warning icon, and remaining steps show grey pending icon
4. Given an organiser identifies 5 sponsors with incomplete configurations approaching the deadline, When they select those sponsors and click "Send Reminder", Then reminder notifications are sent to those sponsors via the communication system
5. Given an admin views the sponsor progress dashboard, When they click on a sponsor's row, Then they see detailed status including: date stand configured, artwork files uploaded with timestamps, payment date, proof approval date, and any outstanding actions
6. Given a configuration deadline is 3 days away, When organiser views the dashboard, Then sponsors with incomplete configurations are highlighted with urgency indicators based on proximity to deadline

---

User Story 6 - Organiser Modifies Event Settings and Deadlines (Priority: P3)

An organiser updates event details (dates, deadlines, venue), modifies stand package options, adjusts artwork requirements, updates notification preferences, and notifies affected sponsors of changes.

Why this priority: Configuration changes are important but secondary to initial creation and basic operations. Can be added after core functionality is stable.

Independent Test: Can be tested by modifying various event settings on published events and verifying changes propagate correctly. Delivers flexibility for event management.

Acceptance Scenarios:

1. Given an organiser views a published event, When they update the artwork deadline from 2025-05-15 to 2025-05-20, Then deadline is validated against other dates and saved
2. Given an event has 10 assigned sponsors, When organiser changes artwork deadline, Then all sponsors receive notification of deadline change
3. Given an organiser modifies stand package options, When they add or remove configuration categories, Then changes are reflected for new stand configurations (existing configurations remain unchanged)
4. Given an organiser updates venue information, When they save changes, Then all sponsors see updated venue details in their event view
5. Given an organiser attempts to set configuration deadline after artwork deadline, When they save, Then validation error prevents illogical deadline sequence

---

Edge Cases

• What happens when an organiser is removed from an event that has active sponsors? (System must reassign primary contact or prevent removal)
• How does system handle timezone conversion when sponsor and event are in different timezones? (Display all dates in event timezone with clear labeling)
• What happens when a sponsor invitation link is used after it has been invalidated due to resend? (Show clear error message with instructions to use new link)
• How does system handle bulk invitation upload with partially invalid email addresses? (Process valid entries, return detailed error report for invalid ones)
• What happens when an admin attempts to archive an event with pending artwork approvals? (Prevent archiving until all workflows complete, or force-archive with warning)
• How does system handle concurrent editing of event settings by multiple organisers? (Last write wins, with audit log showing both changes and notification to editors)
• What happens when deadlines are reached but sponsors have not submitted configurations? (System sends automated reminders, marks submissions as overdue, but allows late submission based on organiser settings)
• How does system handle a sponsor with 20+ stands across 10+ events? (Implement pagination and filtering on stand/event lists, optimize context switching performance)
• What happens when sponsor progress status changes while organiser is viewing the dashboard? (Use real-time updates or provide refresh mechanism with visual indication of stale data)
• How does system handle sponsor progress when a sponsor has multiple stands in the same event? (Aggregate progress across all stands or display per-stand breakdown with configurable view)
• What happens when deadlines are extended after progress dashboard has calculated urgency indicators? (Recalculate urgency on deadline change and update dashboard in real-time or on next refresh)

Requirements (mandatory)

Functional Requirements

Event Creation and Configuration

• FR-001: System MUST allow admins to create new events with mandatory fields: name (unique per organiser), description, start date, end date, configuration deadline, artwork deadline, venue, and timezone (IANA format)
• FR-002: System MUST validate that event dates follow logical sequence: configuration deadline < artwork deadline < start date < end date
• FR-003: System MUST support three event statuses: draft (initial), published (active), and archived (completed)
• FR-004: System MUST allow admins and organisers to define stand package options through configuration categories linked to events
• FR-005: System MUST allow admins and organisers to define artwork requirements through configuration items linked to events
• FR-006: System MUST support extensible custom fields through event settings for event-specific requirements
• FR-007: System MUST enforce event name uniqueness per organiser (different organisers can use the same event name)

Organiser Management

• FR-008: System MUST allow admins to assign organisers to events using the permission system with three access levels: read, write, or admin
• FR-009: System MUST support three organiser roles: primary contact, contact, or viewer
• FR-010: System MUST provide organisers with a dashboard filtered to show only events they are assigned to
• FR-011: System MUST allow organisers with write or admin permissions to modify event settings (dates, deadlines, venue, configuration options)
• FR-012: System MUST log all organiser actions in the audit logging system for accountability

Sponsor Invitation and Management

• FR-013: System MUST allow organisers to generate unique, secure invitation links for each sponsor via email
• FR-014: System MUST validate email addresses before sending invitations
• FR-015: System MUST track invitation status for each sponsor: pending, accepted, or expired
• FR-016: System MUST allow organisers to resend invitations with new secure tokens that invalidate previous links
• FR-017: System MUST provide bulk invitation tools that validate email addresses and process valid entries
• FR-018: System MUST support multiple stand assignments per sponsor within the same event
• FR-019: System MUST support sponsor participation in multiple events simultaneously
• FR-020: System MUST provide sponsors with a stand switching interface showing all assigned stands grouped by event

Access Control and Security

• FR-021: System MUST enforce access control through the permission system for all event, organiser, and sponsor operations
• FR-022: System MUST validate user permissions before allowing any event modification
• FR-023: System MUST enforce role-based permissions: admins can create/delete events, organisers can manage assigned events, sponsors can view assigned events only
• FR-024: System MUST use token-based authentication for API access to event data
• FR-025: System MUST log all security-relevant actions (access attempts, permission changes, status changes) in audit logs

Event Lifecycle and Data Management

• FR-026: System MUST implement soft deletes for archived events to maintain data integrity and support seven-year retention policy
• FR-027: System MUST notify relevant users (organisers, sponsors) via the notification system when event status changes
• FR-028: System MUST persist sponsor stand context when switching between stands to improve workflow efficiency
• FR-029: System MUST allow admins to archive completed events while preserving all historical data, audit logs, and configurations
• FR-030: System MUST prevent archiving of events with incomplete workflows unless admin explicitly forces archival

Event Information Display

• FR-031: System MUST display all event dates and deadlines in the event's configured timezone
• FR-032: System MUST show sponsors their event deadlines (configuration and artwork) with clear timezone labeling
• FR-033: System MUST provide sponsors with venue information and event description for each assigned event
• FR-034: System MUST display invitation status and tracking information to organisers for monitoring purposes

Sponsor Progress Monitoring

• FR-035: System MUST provide admins and organisers with a sponsor progress dashboard showing all sponsors for an event with completion status for: stand configuration, artwork upload, payment, and proof approval
• FR-036: System MUST display visual indicators for each progress step: complete (green checkmark), incomplete (amber warning), pending approval (blue icon), not started (grey icon)
• FR-037: System MUST allow filtering of sponsor progress by completion status (all, complete, incomplete, pending approval) for each step type
• FR-038: System MUST calculate and display urgency indicators based on proximity to deadlines (e.g., deadline within 3 days shows high urgency)
• FR-039: System MUST allow organisers to select multiple sponsors and send bulk reminder notifications via the communication system
• FR-040: System MUST provide detailed progress view showing timestamps for: stand configuration completion, artwork upload dates, payment date, and proof approval date
• FR-041: System MUST aggregate sponsor progress statistics showing counts of complete, incomplete, and pending for each step across all event sponsors
• FR-042: System MUST link sponsor progress items to the communication system allowing organisers to message sponsors directly from the progress dashboard

Notification and Communication

• FR-043: System MUST send automated email notifications when: invitation is sent, deadline is approaching (configurable warning period), event settings change, event status changes
• FR-044: System MUST support customizable email templates for invitations and notifications within event settings
• FR-045: System MUST notify all assigned sponsors when organisers modify event deadlines or critical settings
• FR-046: System MUST send reminder notifications for approaching deadlines based on organiser-configured notification settings

Performance and Scale

• FR-047: System MUST support concurrent access by multiple organisers editing different aspects of the same event
• FR-048: System MUST handle bulk invitation operations for up to 500 sponsors per batch with progress tracking
• FR-049: System MUST optimize event listing and search using indexed database queries on name, status, and dates
• FR-050: System MUST paginate sponsor lists and stand lists when count exceeds 20 items
• FR-051: System MUST load sponsor progress dashboard with up to 100 sponsors in under 2 seconds using optimized queries

Key Entities

• Event: Represents a conference or exhibition with name, description, dates (start, end, configuration deadline, artwork deadline), venue, timezone (IANA format), status (draft/published/archived), organiser assignments, sponsor assignments, stand packages, artwork requirements, and custom settings
• Organiser Assignment: Links organiser users to events with permission scope (read/write/admin) and role (primary contact/contact/viewer), managed through the permission system
• Sponsor Assignment: Links sponsor users to specific stands within events, supporting multiple stands per event and multiple events per sponsor, managed through the permission system
• Invitation: Tracks sponsor invitation process with unique secure token, email address, status (pending/accepted/expired), sent timestamp, and accepted timestamp
• Stand: Represents an exhibition space within an event, linked to a sponsor, with configuration status and artwork status
• Event Settings: Stores event-specific preferences including notification templates, default values, workflow rules, and custom fields
• Sponsor Progress: Aggregated view of sponsor completion status containing sponsor reference, event reference, stand configuration status (complete/incomplete with timestamp), artwork upload status (complete/incomplete/pending approval with timestamp), payment status (complete/incomplete with timestamp), proof approval status (complete/incomplete with timestamp), and overall completion percentage

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: Admins can create a complete event (including all required fields, organiser assignment, and initial configuration) in under 10 minutes
• SC-002: Organisers can generate and send sponsor invitations at a rate of at least 100 invitations per minute for bulk operations
• SC-003: Sponsors can view all their assigned stands across multiple events and switch between stands in under 3 seconds per switch
• SC-004: System maintains sub-second response times for event listing and search operations with up to 1000 active events
• SC-005: 95% of sponsors successfully accept invitations and access their events on first attempt without support intervention
• SC-006: System supports concurrent access by at least 50 organisers managing different events without performance degradation
• SC-007: Event deadline notifications are delivered within 5 minutes of scheduled send time with 99% reliability
• SC-008: Archived event data remains accessible and retrievable with response times under 2 seconds for seven-year retention period
• SC-009: Audit logs capture 100% of security-relevant actions (access changes, permission modifications, status transitions) with timestamp and user attribution
• SC-010: Bulk invitation operations complete successfully for batches of up to 500 sponsors with detailed error reporting for invalid entries
• SC-011: System correctly handles timezone conversions for events and sponsors in different timezones with zero date/time display errors
• SC-012: 90% of organisers successfully configure event settings (deadlines, packages, artwork requirements) without referring to documentation
• SC-013: Organisers can identify incomplete sponsor submissions and send targeted reminders within 2 minutes using the sponsor progress dashboard
• SC-014: Sponsor progress dashboard loads and displays status for 100 sponsors in under 2 seconds
• SC-015: Progress indicators accurately reflect real-time completion status with updates appearing within 5 seconds of sponsor action completion

Assumptions (mandatory)

1. User Management System: Assumes existing user authentication and registration system handles user accounts, passwords, and session management
2. Permission System: Assumes existing role-based permission system can be extended to support event-organiser and event-sponsor relationships
3. Email Service: Assumes integration with external email service (e.g., transactional email provider) for sending invitations and notifications
4. Notification System: Assumes existing notification infrastructure handles scheduling, delivery, and template management
5. Audit Logging: Assumes existing audit logging system captures user actions with timestamp, user ID, action type, and affected resources
6. File Storage: Assumes artwork files are stored separately and referenced by event/stand context (not managed within event management module)
7. Timezone Data: Assumes IANA timezone database is available and maintained for accurate timezone conversion
8. Database Performance: Assumes database supports indexing on event name, status, dates, and organiser/sponsor relationships for query optimization
9. Soft Delete Implementation: Assumes database and ORM support soft delete pattern (deleted_at timestamp) for data retention
10. Concurrent Access: Assumes database supports row-level locking or optimistic concurrency control for conflict resolution
11. Default Notification Timing: Deadline reminder notifications sent 7 days and 24 hours before deadline unless organiser configures different intervals
12. Invitation Link Expiry: Invitation tokens expire after 30 days if not accepted unless organiser resends
13. Event Archival Trigger: Events become eligible for archiving 30 days after end date, subject to admin discretion
14. Stand Context Persistence: Stand context stored in user session or browser local storage for duration of user session

Dependencies (mandatory)

Internal Dependencies

• User management system: required for authentication, registration, user profiles, and session management
• Permission system: required for access control, role assignment, and authorization checks
• Stand configuration system: required for stand package definitions, configuration categories, and sponsor configurations
• Artwork management system: required for artwork requirements, submission workflows, approval processes, and progress status tracking
• Notification system: required for email invitations, deadline reminders, status change notifications, and template management
• Communication system: required for sending targeted reminders and direct messages from progress dashboard
• Payment system: required for payment status tracking in sponsor progress monitoring
• Audit logging system: required for tracking user actions, security events, and compliance reporting

External Dependencies

• Transactional email service: required for sending invitation emails and notification emails with delivery tracking
• IANA timezone database: required for timezone validation and date/time conversion
• File storage service: required for storing uploaded artwork files referenced by event context

Constraints (mandatory)

Business Constraints

• Event names must be unique per organiser (but not globally unique across platform)
• Event dates must follow logical sequence: configuration deadline < artwork deadline < start date < end date
• Stand package options limited to configuration categories and items defined in stand configuration system
• User access controlled by permission system - cannot bypass role-based access controls
• Archived events must retain all data (configurations, artwork, audit logs) for seven-year compliance period
• Sponsors may be assigned to multiple stands within same event and participate in multiple events simultaneously
• Organisers must belong to at least one event; cannot delete last organiser from published event

Technical Constraints

• API rate limits: 100 requests per minute per user for event creation/modification operations
• Bulk invitation operations: maximum 500 sponsors per batch to prevent timeout and memory issues
• Storage quotas: event configuration data (excluding artwork files) limited to 10MB per event
• Concurrent user access: system designed to support up to 100 concurrent users per event without degradation
• Invitation token length: 64 characters (cryptographically secure random string)
• Database query timeout: 5 seconds for complex event listing queries with filters
• Event listing pagination: 50 events per page maximum to maintain response time under 1 second

Open Questions

None - all requirements are specified with reasonable defaults documented in Assumptions section.

Stand Configuration

User Scenarios & Testing (mandatory)

User Story 1 - Sponsor Selects Base Package and Views Included Items (Priority: P1)

A sponsor logs into their assigned stand and views available stand packages (mapped from Nimlogix kits). If the sponsor has permission to select packages, they can choose their preferred package. If package selection permission is disabled for their stand, they view their pre-allocated package assigned by the organiser. All sponsors see included items with quantities, descriptions, and any mandatory components that cannot be changed.

Why this priority: This is the foundational capability - viewing and potentially selecting a base package is the starting point for all stand configuration. Without this, no other configuration can occur.

Independent Test: Can be fully tested by logging in as a sponsor, viewing available packages with pricing (if selection permission granted) or viewing pre-allocated package (if selection permission disabled), selecting one (if allowed), and verifying included items are displayed correctly. Delivers a functional package selection/viewing MVP.

Acceptance Scenarios:

1. Given a sponsor is assigned to a stand with package selection permission enabled, When they access the stand configuration page, Then they see all available packages with names, descriptions, and total prices
2. Given a sponsor is assigned to a stand with package selection permission disabled, When they access the stand configuration page, Then they see their pre-allocated package with name, description, and included items (no selection interface displayed)
3. Given a sponsor views available packages (selection permission enabled), When they select a package (e.g., "3m x 2m Shell Scheme"), Then the package is assigned to their stand and all included items are displayed
4. Given a sponsor has a package (either selected or pre-allocated), When they view non-configurable items (min = included = max), Then they see item names with locked quantities displayed as read-only
5. Given a package has configurable options (min < max), When a sponsor views configuration categories, Then all configurable options are displayed with quantity controls between minimum and maximum
6. Given a sponsor attempts to change their selected package (selection permission enabled), When they select a different package, Then the system warns about losing current configuration and allows confirmation before switching
7. Given a sponsor has a pre-allocated package (selection permission disabled), When they attempt to change packages, Then no package selection interface is available and current package is locked

---

User Story 2 - Sponsor Configures Options Within Configuration Categories (Priority: P1)

A sponsor views available configuration categories (mapped from Nimlogix bolt-on groups), selects options per category where required, configures variable quantity items where allowed, and sees real-time pricing updates as they make selections.

Why this priority: Configuration option selection is core to the stand configuration workflow and must work immediately after package selection for a viable MVP.

Independent Test: Can be tested by selecting a package, viewing configuration categories, selecting options, adjusting quantities for variable items, and verifying pricing updates. Delivers functional configuration option selection.

Acceptance Scenarios:

1. Given a sponsor has selected a package, When they view available configuration options, Then they see configuration categories (e.g., "Backwall AV", "Furniture", "Lighting") with options listed under each category
2. Given a configuration category is single-select (e.g., "Backwall AV"), When a sponsor selects one option (e.g., "43 inch screen"), Then only that option is selected and other options in the category are deselected
3. Given a configuration category is multi-select (e.g., "Extras"), When a sponsor selects multiple options (e.g., "Literature Holder" and "Bar Stool"), Then both options remain selected and can be configured independently
4. Given a configuration option has included quantity of 2 and maximum of 5, When a sponsor adjusts the quantity from default 2 to 4, Then the quantity is validated against min/max limits and additional charge calculated for 2 extra units
5. Given a sponsor configures options, When they view the pricing summary, Then they see base package price (includes all included quantities), additional charges for quantities above included, and total price
6. Given a configuration option has included quantity greater than zero, When a sponsor views it, Then it shows included quantity as default with ability to adjust between minimum and maximum

---

User Story 3 - Organiser Configures Stand Package Permissions (Priority: P1)

An organiser views packages available for their event (provided by external system), configures package selection permissions per stand (allow sponsor to select packages or restrict to pre-allocated package), assigns packages to stands when permission is disabled, and makes packages available for sponsor use. Package data itself (items, configuration options, pricing) is read-only and managed by external system.

Why this priority: Without organisers being able to configure package selection permissions and assign packages, sponsors cannot access configuration. This is a critical prerequisite for the system.

Independent Test: Can be tested by viewing available packages, setting package selection permissions for individual stands, assigning packages to stands with disabled permission, and verifying sponsors see appropriate interface based on their permission. Delivers organiser package configuration MVP.

Acceptance Scenarios:

1. Given an organiser is setting up an event, When they view available packages, Then they see packages provided by external system with names, descriptions, base prices, and included items (read-only)
2. Given an organiser views package details, When they review configuration categories and options, Then they see all configuration categories with selection mode (single-select or multi-select) defined by external system (read-only)
3. Given an organiser attempts to modify package data, When they try to edit package name, items, or configuration options, Then system prevents editing with message indicating data is managed by external system
4. Given an organiser assigns a sponsor to a stand, When they enable package selection permission for that stand, Then the sponsor will see package selection interface with all available packages
5. Given an organiser assigns a sponsor to a stand, When they disable package selection permission for that stand, Then the sponsor will only see their assigned package without selection interface
6. Given an organiser has disabled package selection permission for a stand, When they assign a sponsor to that stand, Then they must assign a specific package to the stand from available packages
7. Given an event has multiple stands, When an organiser configures package selection permissions, Then they can enable permission for some stands and disable it for others independently
8. Given package data includes cost and pricing information, When organiser views package details, Then internal cost data is visible for reporting purposes but not displayed to sponsors

---

User Story 4 - Sponsor Saves Draft and Submits Configuration (Priority: P2)

A sponsor works on their stand configuration over multiple sessions, saves progress as a draft, receives confirmation of saved changes, returns later to continue editing, completes configuration, submits for review, and receives confirmation with submission deadline reminder.

Why this priority: Draft saving is essential for user experience but can be delivered after core configuration functionality works. Submission workflow is required before artwork management.

Independent Test: Can be tested by starting configuration, saving as draft, logging out, logging back in, resuming configuration, submitting, and verifying status transitions. Delivers complete configuration workflow.

Acceptance Scenarios:

1. Given a sponsor is configuring their stand, When they save their progress, Then all selections (package, configuration options, quantities) are saved as a draft with timestamp
2. Given a sponsor has saved a draft, When they return to the stand configuration page, Then their previous selections are restored and they can continue editing
3. Given a sponsor completes their configuration, When they submit for review, Then status changes from "draft" to "submitted" and configuration becomes read-only
4. Given a sponsor submits their configuration, When submission is confirmed, Then they receive confirmation message with submission deadline, organiser contact details, and next steps
5. Given a configuration has been submitted, When an organiser reviews it, Then they see all selected items, quantities, pricing breakdown, and can approve or request changes

---

User Story 5 - Organiser Reviews and Approves Stand Configuration (Priority: P2)

An organiser views all submitted stand configurations for their event, filters by status and stand, reviews configuration details and pricing, approves configurations that meet requirements, requests changes with comments for incomplete configurations, and tracks approval status across all stands.

Why this priority: Approval workflow is important but secondary to the configuration creation process. Can be delivered after sponsors can submit configurations.

Independent Test: Can be tested by submitting multiple configurations as sponsor, logging in as organiser, viewing pending configurations, approving some, requesting changes on others, and verifying status updates. Delivers complete review workflow.

Acceptance Scenarios:

1. Given an organiser manages an event, When they view stand configurations dashboard, Then they see all stands with status indicators (draft, submitted, approved, changes requested)
2. Given an organiser selects a submitted configuration, When they review details, Then they see sponsor name, package selection, all configuration options with quantities, total pricing, and submission timestamp
3. Given an organiser approves a configuration, When they confirm approval, Then status changes to "approved", sponsor is notified, and configuration triggers artwork requirement generation
4. Given an organiser identifies issues, When they request changes, Then they provide comments, status changes to "changes requested", and sponsor receives notification with comments
5. Given a sponsor receives change request, When they edit and resubmit, Then status changes back to "submitted" and organiser is notified of resubmission

---

Edge Cases

• What happens when an organiser disables package selection permission for a stand after sponsor has already selected a package? (Treat selected package as pre-allocated, lock it from further sponsor changes)
• What happens when an organiser enables package selection permission for a stand that previously had it disabled? (Unlock package for sponsor editing)
• What happens when a sponsor switches packages after configuring multiple options (with selection permission enabled)? (All configuration selections are cleared, user is warned before switch, pricing resets to new base package)
• How does system handle organiser attempting to change a pre-allocated package after sponsor has configured options? (Require confirmation, warn that option selections may become invalid if new package has different configuration categories, clear incompatible selections)
• What happens when an organiser changes package selection permission for multiple stands simultaneously? (System processes each stand independently, applying appropriate lock status changes)
• How does system handle configuration option with minimum quantity 1, included quantity 2, and maximum quantity 5? (Display with default quantity of 2, allow adjustment from 1-5, charge only for quantities above included 2)
• What happens when a configuration category has only one option? (For single-select categories: display as checkbox to include/exclude; for multi-select categories: same behavior as checkbox)
• What happens when external system updates package data after sponsors have already configured stands? (Existing submitted/approved configurations remain unchanged on previous version, draft configurations may be affected, new configurations use updated data)
• How does system handle size modifiers and metadata from external system? (Store modifiers for external system integration but don't expose to sponsor interface)
• What happens when a sponsor tries to submit configuration past the deadline? (System allows submission but marks as late, organiser receives notification, configuration requires explicit approval)
• How does system handle nested packages (kits containing other kits)? (Nested kits are treated as configuration options; if quantity is configurable, sponsors can adjust quantity between min/included/max; if quantity is locked, displayed as non-configurable item)
• How does system handle configuration option with included quantity of 0 (purely optional)? (Display with minimum quantity as default, all selected quantity incurs charges)
• What happens when sponsor selects quantity below included quantity? (System allows selection between minimum and included with no pricing adjustment; included quantity is already included in base package price, selecting less does not provide credit or discount)
• How does system handle concurrent editing when sponsor and organiser both modify configuration? (Last write wins for draft status, submitted/approved configurations are locked from sponsor editing until status reverts to draft)
• What happens when external system tries to update package data that is referenced by approved configurations? (Accept update but maintain version history, existing configurations reference previous version, new configurations use new version)

Requirements (mandatory)

Functional Requirements

Package Selection and Display

• FR-001: System MUST support package selection permission configuration per stand, allowing organisers to enable or disable sponsor's ability to select packages independently for each stand
• FR-002: System MUST display all available packages for a stand with package name, description, base price, and key features when package selection permission is enabled for that stand
• FR-003: System MUST display only the pre-allocated package (no selection interface) when package selection permission is disabled for that stand
• FR-004: System MUST allow sponsors to select one package per stand from available options when package selection permission is enabled for their stand
• FR-005: System MUST prevent sponsors from changing packages when package selection permission is disabled for their stand
• FR-006: System MUST display all non-configurable items (where min = included = max) for assigned package showing item name, locked quantity, and unit of measure
• FR-007: System MUST display configuration options with locked quantities (min = included = max) as non-editable items in package summary
• FR-008: System MUST warn sponsors before allowing package changes (when permission enabled) that will clear all current configuration selections and require confirmation
• FR-009: System MUST preserve and display Nimlogix kit ID, kit code, and kit description for integration purposes

Configuration Categories and Options

• FR-010: System MUST organize configuration options into configuration categories that map to external system bolt-on groups; options without an assigned category are grouped under "Other Options" or displayed as uncategorized list if no categorized options exist
• FR-011: System MUST enforce selection rules per configuration category as defined by external system - categories can be either single-select (mutually exclusive) or multi-select (allow multiple options)
• FR-012: System MUST support three quantity types for configuration options: minimum quantity (floor), included quantity (included in package), and maximum quantity (ceiling)
• FR-013: System MUST display included quantity as the default/starting quantity for configuration options included in package
• FR-014: System MUST allow sponsors to adjust quantities between minimum and maximum limits (inclusive)
• FR-015: System MUST validate configuration option quantity selections to ensure they are within minimum and maximum bounds
• FR-016: System MUST calculate additional charges only for quantities above included quantity using unit price multiplied by (selected quantity - included quantity); quantities at or below included incur no additional charges and provide no credits
• FR-017: System MUST preserve external system identifiers (bolt-on ID, bolt-on group, item code) for integration

Pricing and Calculations

• FR-018: System MUST calculate and display total configuration price as sum of base package price (which includes all included quantities) plus all additional configuration option charges (only for quantities above included)
• FR-019: System MUST update pricing in real-time as sponsors make selections and quantity adjustments
• FR-020: System MUST display pricing breakdown showing base package price (includes all included quantities regardless of sponsor's actual selection), additional quantity charges (only for quantities above included × unit price), and total; selecting quantities below included does not reduce price or provide credits
• FR-021: System MUST preserve unit cost and unit price for reporting but display only customer-facing prices to sponsors
• FR-022: System MUST calculate configuration option additional charges as: MAX(0, selected quantity - included quantity) × unit price; selecting quantities at or below included always results in zero additional charges (no credits or discounts applied)

Draft Saving and Session Management

• FR-023: System MUST auto-save draft configurations every 2 minutes while sponsor is actively editing
• FR-024: System MUST provide manual "Save Draft" action that confirms save with timestamp
• FR-025: System MUST restore all saved selections (package, configuration options, quantities) when sponsor returns to configuration
• FR-026: System MUST track configuration status transitions: draft → submitted → approved/changes requested → draft (if changes requested)
• FR-027: System MUST prevent concurrent editing conflicts by locking submitted/approved configurations from sponsor changes

Submission and Approval Workflow

• FR-028: System MUST allow sponsors to submit completed configurations for organiser review
• FR-029: System MUST change configuration status to "submitted" and make configuration read-only to sponsor upon submission
• FR-030: System MUST notify organiser when sponsor submits configuration for review
• FR-031: System MUST display submission confirmation to sponsor with deadline reminder, organiser contact details, and next steps
• FR-032: System MUST allow organisers to approve configurations, which changes status to "approved" and triggers artwork requirement generation
• FR-033: System MUST allow organisers to request changes with comments, which changes status to "changes requested" and notifies sponsor
• FR-034: System MUST allow sponsors to edit configurations after changes are requested, making status revert to "draft"
• FR-035: System MUST allow late submissions past deadline but mark them as late and require explicit organiser approval

Organiser Package Configuration and External Integration

• FR-036: System MUST allow organisers to configure package selection permission per stand, enabling or disabling sponsor's ability to select packages independently for each stand
• FR-037: System MUST require organisers to assign specific packages to stands when package selection permission is disabled for that stand
• FR-038: System MUST display available packages to organisers with all details (name, description, base price, items, configuration categories) in read-only view
• FR-039: System MUST prevent organisers from creating, editing, or deleting packages, items, or configuration options
• FR-040: System MUST accept package data from external system API including packages, configuration options, configuration categories, and all attributes (nested kits treated as configuration options)
• FR-041: System MUST store external system identifiers (kit ID, kit code, bolt-on ID, group identifier) and category selection mode for each package, category, and option provided by external system
• FR-042: System MUST store three quantity values for each configuration option: minimum quantity, included quantity (included in package), and maximum quantity
• FR-043: System MUST store cost data (unit cost for packages and options) alongside pricing for reporting and external system synchronization
• FR-044: System MUST store and enforce configuration rules (quantity constraints via min/included/max, category selection mode) as defined by external system
• FR-045: System MUST validate incoming package data from external system for required fields (package name, kit ID, base price, unit cost, quantity constraints) before accepting
• FR-046: System MUST make packages available for sponsor use (selection or pre-allocation) based on data provided by external system
• FR-047: System MUST maintain version history when package data is updated by external system, preserving existing stand configurations on previous package versions
• FR-048: System MUST store additional metadata (size modifiers) provided by external system for reporting without displaying to sponsors
• FR-049: System MUST allow external system to update package data which affects new configurations but preserves existing submitted/approved configurations

Organiser Review Dashboard

• FR-050: System MUST provide organisers with dashboard showing all stands for their event with status indicators and assigned packages (whether selected by sponsor or pre-allocated)
• FR-051: System MUST allow organisers to filter stand configurations by status (draft, submitted, approved, changes requested, late)
• FR-052: System MUST display configuration details for organiser review including sponsor name, package (selected or pre-allocated), all configuration options with quantities (included vs selected), pricing breakdown, and submission timestamp
• FR-053: System MUST track and display configuration submission timestamp, approval timestamp, and organiser who performed approval
• FR-054: System MUST provide approval actions (approve, request changes) with confirmation dialogs

Data Retention and Compliance

• FR-055: System MUST preserve all configuration data (package selections/allocations, configuration options, quantities, pricing, cost data, status history) for seven-year retention period
• FR-056: System MUST log all configuration changes with timestamp, user ID, and changed fields in audit log including package allocation actions by organisers
• FR-057: System MUST support soft deletes for stand configurations to maintain referential integrity with artwork and payment records

Key Entities

• Stand Configuration: Represents a sponsor's configuration for a specific stand, including assigned package (either selected by sponsor or pre-allocated by organiser), package selection permission flag (enabled/disabled), configuration option selections, quantities, total pricing, status (draft/submitted/approved/changes requested), submission timestamp, approval timestamp, and version reference to package data
• Package Allocation: Records organiser's pre-allocation of a specific package to a stand when package selection permission is disabled, including allocated package, allocated by organiser ID, allocation timestamp, and lock status
• Package: Represents a stand package configuration, including package name, description (may include details of non-configurable items), base price, unit cost (for reporting), external system identifiers (kit ID, kit code) for integration, list of available configuration categories, and publication status
• Configuration Category: Represents a grouping of related configuration options for package customisation, including category name, external group identifier for integration, display order, selection mode (single-select for mutually exclusive options, or multi-select for independent options), and list of configuration options
• Configuration Option: Represents any item associated with a package (both configurable and non-configurable), including option name, external identifiers (bolt-on ID, item code) for integration, category assignment (null if uncategorized), minimum quantity (cannot select less), included quantity (amount included in package), maximum quantity (cannot select more), unit price, unit cost (for reporting), size modifiers for external systems, and default selection indicator. Note: When min = included = max, the item is non-configurable (display-only with locked quantity). Options with null category are grouped together or displayed as uncategorized list
• Configuration Selection: Represents sponsor's choice within a configuration category, including selected option, chosen quantity, pricing calculation, and timestamp
• Package Version: Tracks changes to package data over time, preserving historical configurations when packages are modified, including version number, effective date, and snapshot of package/item/option data

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: Sponsors can complete stand configuration from package selection through configuration option selection to submission in under 15 minutes for typical packages with 3-5 configuration categories
• SC-002: 90% of sponsors successfully select package, configure options, and submit configuration without requiring support assistance
• SC-003: Organisers can configure package selection permissions per stand and assign packages in under 10 minutes per event
• SC-004: System accurately calculates pricing for 100% of configurations with zero arithmetic errors in totals and line items
• SC-005: Draft configurations auto-save within 2 minutes of changes with 99% reliability
• SC-006: Configuration dashboard loads and displays up to 100 stands with status indicators in under 2 seconds
• SC-007: Real-time pricing updates appear within 500 milliseconds of configuration option selection or quantity adjustment
• SC-008: Organisers can review and approve/request changes on submitted configurations in under 5 minutes per stand
• SC-009: 95% of submitted configurations receive organiser response (approved or changes requested) within 48 hours
• SC-010: System supports concurrent editing by up to 50 sponsors configuring different stands without performance degradation
• SC-011: Configuration options display correctly regardless of complexity (nested kits treated as configuration options)
• SC-012: Configuration version history preserves 100% of historical configurations when package data is updated, with zero data loss

Assumptions (mandatory)

1. External System Integration: Assumes external system (Nimlogix) will create and update all package data via portal API; portal does not pull data from external systems
2. Package Data Management: Assumes all package data (packages, configuration options, configuration categories, pricing) is created and managed exclusively by external system; organisers have read-only access for viewing and configuration assignment purposes only
3. Single Package Per Stand: Assumes each stand can have only one active package at a time; sponsors cannot mix and match base packages
4. Package Selection Permission Default: Assumes default package selection permission is enabled; organisers must explicitly disable permission per stand if they want to restrict package selection
5. Pre-allocation Timing: Assumes organisers pre-allocate packages before sponsors access configuration interface when permission is disabled; sponsors never see empty/unassigned stand when permission is disabled
6. Category Selection Mode: Assumes configuration categories can be either single-select (mutually exclusive options) or multi-select (independent options); selection mode defined by external system per category
7. Pricing Currency: Assumes all pricing is in GBP; multi-currency support would require separate specification
8. Included Quantity Pricing: Assumes included quantity is always included in base package price regardless of actual sponsor selection; selecting quantities below included never provides credits or discounts to sponsor
9. Auto-save Interval: Assumes 2-minute auto-save interval balances data safety with system performance; configurable by system administrator
10. Nested Kit Handling: Assumes nested kits from external system are treated as configuration options; if quantity is configurable (min ≠ max), sponsors can adjust quantity; if locked (min = included = max), displayed as non-configurable item
11. Internal Data Visibility: Assumes cost data is internal data not displayed to sponsors, only used for reporting and external system integration
12. Late Submission Handling: Assumes late submissions are allowed but require explicit organiser approval rather than automatic rejection
13. Configuration Lock Behavior: Assumes submitted/approved configurations are locked from sponsor editing to maintain approval integrity; changes requested status unlocks for editing
14. Artwork Trigger: Assumes approved configuration status automatically triggers artwork requirement generation (handled by separate artwork management module)
15. Metadata Storage: Assumes external system identifiers (kit ID, item code, bolt-on ID) and metadata (size modifiers, cost data) are stored for integration but not displayed to sponsors unless explicitly configured
16. Concurrent Edit Resolution: Assumes last write wins for draft configurations; submitted/approved configurations prevent concurrent edits through status locking
17. Permission Switching Impact: Assumes changing package selection permission after sponsors have configured stands is rare; when it occurs, existing configurations are preserved with appropriate lock status changes

Dependencies (mandatory)

Internal Dependencies

• Event management system: required for event context, sponsor assignments, and configuration deadlines
• User management system: required for authentication, sponsor/organiser role verification, and permission checks
• Notification system: required for submission confirmations, approval notifications, change request alerts, and deadline reminders
• Artwork management system: required for receiving trigger when configuration is approved to generate artwork requirements
• Audit logging system: required for tracking all configuration changes, status transitions, and approval actions
• Reporting system: required for accessing configuration data and pricing breakdowns

External Dependencies

• External system integration API: optional integration endpoint for external systems to create/update package data, query configurations, and sync stand details
• Pricing service: required for currency formatting and tax calculations if applicable

Constraints (mandatory)

Business Constraints

• Package data (packages, configuration options, configuration categories, pricing) is read-only for portal users; all changes must come from external system
• Portal users (organisers and sponsors) cannot create, edit, or delete packages - all package management is external
• Package selection permission is configured per stand - event can have mix of stands with permission enabled and disabled
• Package selection limited to one active package per stand at any time
• When permission is disabled for a stand, organisers must assign packages before sponsors can access configuration
• When permission is enabled for a stand, sponsors must select package before configuring options
• Configuration category selection mode (single-select or multi-select) enforced as defined by external system
• Configuration changes not allowed after submission unless organiser requests changes
• Approved configurations cannot be modified without reverting approval status
• Cost data must be preserved for reporting but not displayed to sponsors
• Late submissions past deadline require explicit organiser approval rather than automatic processing
• Configuration data must be retained for seven years for compliance and historical reference
• Package version changes must preserve existing configurations on historical versions
• Changing package selection permission after configurations exist requires organiser confirmation and may impact sponsor workflow

Technical Constraints

• Configuration options displayed as flat list (nested kits treated as individual configuration options)
• External system API calls for package data updates must complete within 30 seconds or be queued for async processing
• Auto-save interval set to 2 minutes minimum to balance data safety with server load
• Configuration dashboard pagination required for events with more than 100 stands
• Real-time pricing updates must complete within 500 milliseconds to maintain responsive user experience
• System designed to support up to 50 concurrent sponsors configuring stands without degradation
• Package data validation from external system must complete within 5 minutes for packages with up to 200 configuration options
• Configuration pricing calculations must be arithmetically accurate with zero rounding errors beyond standard currency precision (2 decimal places)

Open Questions

None - all requirements are specified with reasonable defaults documented in Assumptions section.

Artwork Management

User Scenarios & Testing

User Story 1 - Upload Artwork Files (Priority: P1)

As a sponsor, I need to upload artwork files for my stand so that Nimlok can print my graphics according to the specifications.

Why this priority: This is the core workflow - without the ability to upload artwork, the entire feature is non-functional. This delivers immediate value by allowing sponsors to submit their graphics.

Independent Test: Can be fully tested by having a sponsor with a configured stand view their artwork requirements, upload files up to 1GB, and verify the files are stored and Nimlogix is notified. Delivers value by accepting artwork submissions.

Acceptance Scenarios:

1. Given a sponsor has a configured stand with artwork requirements, When they view their artwork list, Then they see all required artwork items with specifications
2. Given a sponsor is viewing an artwork requirement, When they download the specification document, Then they receive the PDF guidance from Nimlogix
3. Given a sponsor is uploading a 500MB PDF file, When the upload connection is interrupted mid-transfer, Then the upload resumes from where it left off
4. Given a sponsor successfully uploads an artwork file, When the upload completes, Then Nimlogix receives a webhook notification with the file details
5. Given a sponsor uploads a file larger than 1GB, When they attempt the upload, Then they see an error message stating the maximum file size

---

User Story 2 - Handle Artwork Approval/Rejection (Priority: P1)

As a sponsor, I need to know whether my artwork was approved or rejected so that I can correct any issues and resubmit if necessary.

Why this priority: This is essential feedback for the core workflow. Without approval/rejection handling, sponsors cannot know if their artwork is acceptable, blocking the entire process.

Independent Test: Can be tested by simulating Nimlogix webhook responses (approved/rejected) and verifying sponsors receive appropriate notifications and can take corrective action. Delivers value by closing the feedback loop.

Acceptance Scenarios:

1. Given a sponsor has uploaded artwork, When Nimlogix approves the artwork via webhook, Then the sponsor sees the artwork status as "Approved"
2. Given a sponsor has uploaded artwork, When Nimlogix rejects the artwork via webhook with a reason, Then the sponsor receives both an in-app notification and an email with the rejection reason
3. Given a sponsor's artwork was rejected, When they view the rejected artwork, Then they can see the rejection reason and upload a corrected version
4. Given a sponsor uploads a corrected version after rejection, When the new file is uploaded, Then the previous version is retained in history and Nimlogix is notified of the new submission

---

User Story 3 - Approve Artwork Proofs (Priority: P1)

As a sponsor or organiser, I need to review and approve final artwork proofs so that Nimlok can proceed with printing my graphics.

Why this priority: This is the final step before printing and is essential for the complete workflow. Without proof approval, the artwork cannot move to production.

Independent Test: Can be tested by having Nimlogix upload proof documents and verifying sponsors/organisers can view, approve, or reject them with reasons. Delivers value by enabling final sign-off.

Acceptance Scenarios:

1. Given Nimlogix uploads a proof document, When the sponsor views their artwork, Then they see the proof is available for review
2. Given a sponsor is reviewing a proof, When they approve it, Then Nimlogix receives a webhook notification of the approval
3. Given a sponsor is reviewing a proof, When they reject it, Then they must enter a rejection reason before submitting
4. Given an organiser has proof approval enabled for an event with sponsor-first sequence, When a sponsor approves a proof, Then the organiser receives a notification to review and approve
5. Given an organiser has proof approval enabled with organiser-first sequence, When Nimlogix uploads a proof, Then the organiser must approve before sponsor can review
6. Given an organiser has proof approval enabled with parallel sequence, When Nimlogix uploads a proof, Then both sponsor and organiser can approve in any order
7. Given both sponsor and organiser must approve, When both parties have approved the proof according to the configured sequence, Then Nimlogix receives the final approval notification

---

User Story 4 - Track Artwork Progress (Priority: P2)

As a sponsor or organiser, I need to see the status of all artwork items so that I can track progress and identify any blockers.

Why this priority: This provides visibility and helps users manage their workflow, but the system can function without it. It enhances user experience rather than enabling core functionality.

Independent Test: Can be tested by viewing artwork lists with various statuses (pending upload, submitted, rejected, approved, proof pending, proof approved) and verifying status displays are accurate.

Acceptance Scenarios:

1. Given a sponsor has multiple artwork items, When they view their artwork dashboard, Then they see the status of each item (not uploaded, submitted, rejected, approved, proof pending, proof approved)
2. Given an organiser is viewing an event, When they view the artwork overview, Then they see a summary of all sponsors' artwork progress
3. Given artwork has been rejected, When a user views the artwork history, Then they can see all previous submissions and rejection reasons

---

Edge Cases

• What happens when a sponsor uploads a file in an unsupported format (not PDF)?
• How does the system handle Nimlogix webhook failures or timeouts?
• What happens if a sponsor tries to upload artwork before their stand configuration is complete?
• How does the system handle simultaneous proof approvals by sponsor and organiser?
• What happens when a sponsor uploads a new artwork version while the previous version is still being reviewed by Nimlogix?
• How does the system handle file uploads that are interrupted multiple times?
• What happens if organiser approval is disabled after a proof is already pending organiser review?
• What happens when Nimlogix uploads a proof for artwork that was subsequently rejected?

Requirements

Functional Requirements

• FR-001: System MUST allow Nimlogix to create artwork requirements via API after stand configuration
• FR-002: System MUST store and display artwork specification documents (typically PDF) for each required artwork item
• FR-003: System MUST support file uploads up to 1GB for artwork files
• FR-004: System MUST use chunked upload mechanism to handle connection interruptions gracefully
• FR-005: System MUST support PDF format only for artwork uploads
• FR-006: System MUST send webhook notification to Nimlogix when artwork is uploaded
• FR-007: System MUST receive webhook from Nimlogix containing approval or rejection status with reason
• FR-008: System MUST notify sponsors when their artwork is rejected with the rejection reason via both in-app notification and email
• FR-009: System MUST allow sponsors to upload corrected artwork files after rejection
• FR-010: System MUST retain version history of all uploaded artwork files for the event lifecycle plus 3 years post-event
• FR-011: System MUST allow Nimlogix to upload proof documents via API
• FR-012: System MUST display proof documents to sponsors for review
• FR-013: System MUST allow sponsors to approve or reject proofs
• FR-014: System MUST require sponsors to provide a reason when rejecting a proof
• FR-015: System MUST send webhook notification to Nimlogix when proof is approved
• FR-016: System MUST support optional organiser approval of proofs based on event configuration, including configurable approval sequence (sponsor-first, organiser-first, or parallel)
• FR-017: System MUST display artwork specification documents to sponsors before upload
• FR-018: System MUST track status of each artwork item through the workflow (not uploaded, submitted, under review, rejected, approved, proof pending, proof approved)
• FR-019: System MUST prevent artwork upload if stand configuration is incomplete
• FR-020: System MUST validate file size before accepting uploads
• FR-021: System MUST validate file format and reject non-PDF uploads with clear error message
• FR-022: System MUST handle Nimlogix webhook failures with automatic retry logic (3 attempts with exponential backoff over 30 minutes) and send email notification to administrators on final failure
• FR-023: System MUST automatically archive or purge artwork version history 3 years after event completion date

Key Entities

• Artwork Requirement: Represents a single artwork item needed for a stand, created by Nimlogix via API. Contains artwork specifications (typically PDF), status, and metadata
• Artwork Submission: Represents an uploaded artwork file from a sponsor. Contains file reference, upload timestamp, version number, and approval status. Related to an Artwork Requirement
• Artwork Specification Document: PDF or document provided by Nimlogix that guides sponsors on artwork requirements. Associated with an Artwork Requirement
• Artwork Proof: Final proof document uploaded by Nimlogix for sponsor and optional organiser approval. Contains file reference, approval status by sponsor, approval status by organiser (if required)
• Artwork Version History: Historical record of all submissions for an Artwork Requirement, including rejected versions with rejection reasons

Success Criteria

Measurable Outcomes

• SC-001: Sponsors can successfully upload files up to 1GB without connection failures
• SC-002: Artwork upload process resumes automatically after connection interruption without data loss
• SC-003: Nimlogix receives webhook notifications within 5 seconds of artwork upload or proof approval
• SC-004: Sponsors receive rejection notifications (both in-app and email) within 1 minute of Nimlogix webhook callback
• SC-005: 95% of sponsors can complete the artwork upload process without requiring support assistance
• SC-006: Sponsors can view complete history of all artwork submissions and status changes
• SC-007: Proof approval workflow (when organiser approval required) completes within defined business timeline
• SC-008: System handles concurrent uploads and approvals without data corruption or race conditions

Assumptions

• Chunked upload mechanism will use industry-standard approaches (e.g., multipart uploads with resume capability)
• Nimlogix API provides reliable webhook endpoints with reasonable timeout thresholds (assumed 30 seconds)
• Proof documents are typically PDF format
• Sponsors must convert all artwork to PDF format before upload (simplifies validation and processing)
• Artwork specification documents are static once created by Nimlogix
• Stand configuration must be in "approved" or "complete" status before artwork requirements are generated
• Webhook authentication will use standard approaches (e.g., HMAC signatures, API keys)
• File storage will use secure, scalable object storage (consistent with existing infrastructure)
• Maximum of 20 artwork items per stand (based on typical exhibition requirements)
• Nimlogix webhooks will be idempotent (can be safely retried)
• Organiser approval requirement and approval sequence (sponsor-first, organiser-first, or parallel) are both configured at event level, not per artwork item
• Webhook retry mechanism uses exponential backoff (e.g., retry after 1 min, 5 min, 15 min)
• Administrator email notifications are sent via existing notification system
• Artwork version history retained for 3 years post-event for business records compliance

Dependencies

• Stand configuration feature must be complete (006-stand-configuration)
• Nimlogix API integration for creating artwork requirements
• Nimlogix webhook endpoints for artwork upload and proof approval notifications
• Nimlogix webhook callbacks for approval/rejection responses
• File storage infrastructure for large file handling
• User notification system for rejection alerts
• Email notification system for administrator alerts on webhook failures
• Event management configuration for organiser approval settings (enabled/disabled, approval sequence preference)

Constraints

• Maximum file size: 1GB per artwork file
• Upload mechanism must be resilient to network interruptions
• Webhook delivery must be reliable with appropriate retry mechanisms
• File storage must be secure and access-controlled
• Version history must be maintained for audit purposes (retained for event lifecycle + 3 years)
• System must handle concurrent proof approvals by multiple parties
• Proof rejection reasons must be captured and stored

Payment Processing and VAT Calculation

User Scenarios & Testing

User Story 1 - Initial Stand Configuration Payment (Priority: P1)

A sponsor configures their exhibition stand by selecting package options and add-ons. They need to see the total cost including VAT and complete payment to confirm their booking.

Why this priority: This is the core payment flow that enables the business to collect revenue. Without this, no bookings can be confirmed.

Independent Test: Can be fully tested by creating a stand configuration, verifying the calculated total (base cost + VAT), and completing a card payment. Delivers immediate value by enabling bookings.

Acceptance Scenarios:

1. Given a sponsor has selected a stand package and add-ons, When they view the checkout summary, Then they see itemised costs, VAT amount, and total due
2. Given a sponsor is ready to pay, When they click the payment button, Then they are directed to a secure card payment interface
3. Given a sponsor completes payment successfully, When the payment is confirmed, Then they receive a receipt showing all items purchased and amounts paid
4. Given payment fails, When the error occurs, Then the sponsor sees a clear error message and can retry payment

---

User Story 2 - Balance Payment for Configuration Changes (Priority: P1)

After initial booking, a sponsor modifies their stand configuration by adding or removing items. They need to pay any outstanding balance or receive information about refunds.

Why this priority: Configuration changes are a core feature differentiator for v2. Without balance payments, sponsors cannot modify bookings post-payment.

Independent Test: Can be tested by modifying an existing paid configuration, verifying the balance calculation (new items minus removed items), and completing a balance payment. Delivers value by enabling flexible booking modifications.

Acceptance Scenarios:

1. Given a sponsor with a paid booking before the modification cutoff deadline, When they add new items to their configuration, Then they see the additional cost and can proceed to pay the balance
2. Given a sponsor modifies their configuration, When they view the payment summary, Then they see what changed (e.g., "Added: 2 stools - £40.00") with the incremental VAT and balance due
3. Given a sponsor removes items from their configuration, When they review changes, Then they see the credit amount and information about refund processing
4. Given a sponsor completes a balance payment, When payment succeeds, Then they receive an updated receipt showing the modification details and new total paid
5. Given the modification cutoff deadline has passed, When a sponsor attempts to modify their configuration, Then they see a message indicating modifications are no longer allowed
6. Given a sponsor has made multiple configuration changes, When they view their balance due, Then they see a single cumulative total reflecting all unpaid modifications
7. Given a sponsor with multiple unpaid changes, When they complete balance payment, Then all accumulated changes are paid in one transaction and receipt shows all modifications
8. Given VAT rules have changed since initial payment, When a sponsor pays balance, Then the system applies the current VAT rate to the balance payment (not the original rate)

---

User Story 3 - International VAT Calculation (Priority: P2)

Administrators configure VAT rules based on company and event locations. The system automatically applies the correct VAT rate when sponsors checkout.

Why this priority: VAT compliance is legally required but can be configured once and works automatically. Less urgent than core payment flows.

Independent Test: Can be tested by configuring VAT rules for different location combinations, then verifying correct rates are applied during checkout for various sponsor/event scenarios.

Acceptance Scenarios:

1. Given an administrator, When they configure VAT settings, Then they can define VAT rates for different combinations of sponsor location and event location
2. Given configured VAT rules exist, When a UK sponsor books for a UK event, Then the system applies the UK VAT rate to their checkout
3. Given configured VAT rules exist, When an EU sponsor books for a UK event, Then the system applies the appropriate cross-border VAT rate
4. Given no VAT rule matches, When a sponsor attempts checkout, Then the system applies a default rate and logs a warning for administrator review

---

Edge Cases

• How does the system handle partial refunds when sponsors remove some but not all items?
• How does the system handle currency conversion for international events?
• What happens if a sponsor's configuration change results in a negative balance (refund due)?
• What happens if a sponsor attempts to modify configuration after the cutoff deadline?
• How does the system communicate VAT rate changes to sponsors before balance payment?

Requirements

Functional Requirements

• FR-001: System MUST calculate total amount due based on selected stand package, add-ons, and configuration items with their individual prices
• FR-002: System MUST apply the correct VAT rate based on sponsor company location and event location as configured by administrators
• FR-003: System MUST display itemised breakdown showing base costs, VAT amount, and total due before payment
• FR-004: System MUST integrate with card payment processing to collect payment securely
• FR-005: System MUST generate a receipt showing all purchased items, quantities, individual costs, VAT, and total paid
• FR-006: System MUST detect when a sponsor modifies their stand configuration after initial payment
• FR-007: System MUST calculate the balance due when configuration changes, accounting for added and removed items
• FR-008: System MUST display configuration changes in human-readable format on receipts (e.g., "Added: 2 stools", "Removed: 1 display screen")
• FR-009: System MUST allow sponsors to complete balance payments for configuration changes
• FR-010: System MUST generate updated receipts showing modification details, previous payments, balance paid, and new total
• FR-011: Administrators MUST be able to configure VAT rates for different combinations of sponsor location and event location
• FR-012: System MUST store VAT configuration as part of event settings
• FR-013: System MUST handle payment failures gracefully and allow sponsors to retry
• FR-014: System MUST prevent duplicate payments for the same balance
• FR-015: System MUST track payment history for each booking, including initial payment and all balance payments
• FR-016: System MUST handle refund scenarios when sponsors remove items (credit or refund process to be defined by business policy)
• FR-017: Administrators MUST be able to set a modification cutoff deadline for each event (e.g., 14 days before event date)
• FR-018: System MUST prevent sponsors from modifying stand configurations after the cutoff deadline has passed
• FR-019: System MUST display clear messaging to sponsors when modification deadline is approaching or has passed
• FR-020: System MUST accumulate all unpaid configuration changes into a single cumulative balance
• FR-021: System MUST allow sponsors to make multiple configuration changes before paying the accumulated balance
• FR-022: System MUST process cumulative balance payments in a single transaction
• FR-023: System MUST display all unpaid configuration changes when showing balance due to sponsors
• FR-024: System MUST apply the current VAT rate at the time of balance payment, not the original rate from initial booking
• FR-025: System MUST recalculate VAT on balance payments using current VAT rules when balance payment is made
• FR-026: Receipts MUST show which VAT rate was applied to each payment transaction
• FR-027: System MUST allow concurrent modifications to booking configurations without locking
• FR-028: When concurrent modifications occur, system MUST save the most recent change, overwriting previous unsaved changes

Key Entities

• Booking: Represents a sponsor's exhibition booking with associated stand configuration and payment status
• Stand Configuration: The selected package, add-ons, and items that make up the sponsor's exhibition stand; last saved version is authoritative
• Configuration Item: Individual purchasable elements (packages, add-ons, furniture) with prices
• Payment: A completed financial transaction including amount, VAT, timestamp, payment method reference, and VAT rate applied at time of payment
• Receipt: A record of payment showing itemised breakdown, configuration changes (if applicable), totals, and VAT rate used
• VAT Rule: Configuration defining VAT rate for specific combinations of sponsor location and event location
• Configuration Change: A modification to an existing booking, tracking added and removed items with cost implications; multiple unpaid changes accumulate into cumulative balance
• Event: Includes modification cutoff deadline timestamp

Success Criteria

Measurable Outcomes

• SC-001: Sponsors can complete initial stand configuration and payment in under 5 minutes
• SC-002: 95% of payment transactions complete successfully on first attempt
• SC-003: System correctly calculates and applies VAT for 100% of bookings based on configured rules
• SC-004: Sponsors can view and understand configuration changes and balance due without contacting support
• SC-005: System processes balance payments within 3 seconds of payment gateway confirmation
• SC-006: Receipts clearly show itemised costs and configuration changes, reducing payment-related support queries by 60%
• SC-007: Administrators can configure VAT rules for new event/location combinations in under 2 minutes
• SC-008: Zero payment processing errors due to incorrect VAT calculation
• SC-009: Payment failure recovery rate (successful retry) exceeds 80%
• SC-010: Zero sponsors able to modify configurations after cutoff deadline enforcement
• SC-011: Sponsors can make multiple configuration changes and pay cumulative balance in single transaction without confusion
• SC-012: System correctly applies current VAT rate to 100% of balance payments, regardless of original rate

Assumptions

• Card payment processing will be handled by an external payment gateway (Stripe mentioned in description)
• Prices for stand packages and add-ons are managed elsewhere in the system
• Sponsor company location and event location data already exists in the system
• VAT rules can change over time and balance payments use the current rate at time of payment
• Currency for all payments is consistent per event (single currency per event)
• Business will define the refund process policy separately (immediate refund, credit note, manual process)
• Payment gateway integration supports both full payments and incremental balance payments
• Receipt generation and delivery method (email, PDF download) already exists in the system
• Administrators have access to a settings area where VAT configuration can be managed
• Payment gateway timeouts and unavailability are handled by the external payment service (Stripe Checkout)
• Modification cutoff deadline is set per event by administrators and applies to all sponsors for that event
• Sponsors can make unlimited configuration changes before paying cumulative balance (no limit on number of unpaid changes)
• VAT rate changes between payments are acceptable and legally compliant (each payment uses rate applicable at its time)
• Concurrent modifications to the same booking are rare enough that last-save-wins approach is acceptable
• Lost changes due to concurrent modifications are acceptable business risk (no conflict detection or recovery needed)

Dependencies

• Stand configuration system (items, packages, add-ons with prices)
• User and company management (to identify sponsor location)
• Event management (to identify event location and modification deadline)
• Payment gateway integration capability
• Receipt generation and delivery system
• Email notification system for payment confirmations

Out of Scope

• Payment gateway failure handling and retry mechanisms (delegated to Stripe Checkout)
• Refund processing workflows (handled separately)
• Payment methods other than card (invoice, bank transfer, etc.)
• Multi-currency support
• Payment plans or instalments
• Discount codes or promotional pricing
• Tax compliance reporting
• Payment gateway selection or switching
• Historical VAT rate changes for past bookings (already paid)
• Notification system for upcoming modification deadlines
• Notification system for VAT rate changes
• Concurrent edit conflict detection or resolution
• Edit locking mechanisms
• Change history tracking for concurrent modifications

Additional Fees Management

User Scenarios & Testing (mandatory)

User Story 1 - Add Additional Fee to Sponsor Stand (Priority: P1)

An admin needs to charge a sponsor for services or changes that fall outside the standard package pricing. The admin adds a fee by entering an amount and description, which immediately updates the sponsor's balance owed.

Why this priority: Core functionality that enables the billing model - without this, admins cannot charge for additional services, which directly impacts revenue and operational workflow.

Independent Test: Can be fully tested by logging in as an admin, navigating to a sponsor's stand details, adding a fee with an amount (e.g., £150.00) and description (e.g., "Artwork design fee"), and verifying the balance owed increases by that amount.

Acceptance Scenarios:

1. Given an admin is viewing a sponsor's stand details, When they add a fee of £150.00 with description "Artwork design fee", Then the fee is saved and the sponsor's total balance owed increases by £150.00
2. Given a sponsor stand has existing package costs of £500.00, When an admin adds a £75.00 "Late change fee", Then the total balance owed displays as £575.00
3. Given an admin enters a fee amount and description, When they submit the fee, Then the fee appears in the sponsor's itemised costs breakdown with the exact amount and description provided

---

User Story 2 - View All Fees on a Stand (Priority: P2)

An admin or sponsor needs to see all additional fees that have been applied to a stand, including the amount and description of each fee, to understand the complete cost breakdown.

Why this priority: Essential for transparency and audit trail - users need to see what they're being charged for, but can be implemented after the ability to add fees exists.

Independent Test: Can be tested by viewing a stand that has multiple fees added, verifying each fee displays with its amount and description in a clear list or table format.

Acceptance Scenarios:

1. Given a stand has three fees added (£150 artwork design, £75 late change, £50 rush processing), When an admin views the stand details, Then all three fees are listed with their descriptions and amounts
2. Given a stand has no additional fees, When viewing the stand details, Then the fees section indicates no additional fees have been added
3. Given a sponsor views their own stand details, When they access the costs section, Then they can see all additional fees with descriptions so they understand their charges

---

User Story 3 - Modify or Remove Added Fees (Priority: P3)

An admin needs to correct a mistake or remove a fee that was added in error, ensuring the balance owed is recalculated accurately.

Why this priority: Important for error correction but not essential for initial launch - admins can work around this by adding offsetting fees if needed initially.

Independent Test: Can be tested by adding a fee, then removing or editing it, and verifying the balance owed updates correctly and the change is reflected in the itemised breakdown.

Acceptance Scenarios:

1. Given a stand has a £150 fee added in error, When the admin removes the fee, Then the fee is deleted and the balance owed decreases by £150
2. Given a fee was added with incorrect amount (£100 instead of £150), When the admin edits the fee amount, Then the balance owed adjusts by the difference (increases by £50)
3. Given a fee description contains a typo, When the admin edits the description, Then the description updates without affecting the balance owed

---

User Story 4 - Apply Credits or Refunds (Priority: P3)

An admin needs to apply a credit or refund to a sponsor's balance by entering a negative fee amount, reducing the total amount owed.

Why this priority: Useful for handling discounts, goodwill gestures, or corrections, but can be deferred if needed - initial launch can handle positive charges only.

Independent Test: Can be tested by adding a negative fee amount (e.g., -£50.00) with description "Discount applied", and verifying the balance owed decreases by that amount.

Acceptance Scenarios:

1. Given a sponsor has a balance owed of £500.00, When an admin adds a fee of -£50.00 with description "Early payment discount", Then the balance owed decreases to £450.00
2. Given an admin enters a negative fee amount, When they submit it, Then the fee displays clearly as a credit in the itemised breakdown (e.g., with distinctive styling or labeling)
3. Given a stand has multiple positive and negative fees, When calculating the balance owed, Then the system correctly sums all fees including the negative values

---

Edge Cases

• What happens when an admin enters a negative fee amount that exceeds the current balance (resulting in a negative balance owed)?
• How does the system handle very large fee amounts (e.g., exceeding typical stand costs)?
• What happens if a fee is added after a sponsor has already paid their balance in full?
• How are fees handled if a stand is cancelled or removed?
• What happens when an admin enters a zero amount fee?
• Can fees have decimal precision issues (e.g., £150.999)?
• What happens if an admin deletes a fee after a sponsor has already viewed or referenced it?
• How are edited fees tracked for audit purposes?

Requirements (mandatory)

Functional Requirements

• FR-001: System MUST allow admins to add additional fees to any sponsor stand
• FR-002: System MUST require both an amount and description when adding a fee
• FR-003: System MUST accept fee amounts as monetary values with standard currency precision (two decimal places)
• FR-004: System MUST accept both positive and negative fee amounts (negative amounts represent credits or refunds)
• FR-005: System MUST accept fee descriptions as free-text input with reasonable length limits (minimum 3 characters, maximum 255 characters)
• FR-006: System MUST include all additional fees (positive and negative) in the calculation of a sponsor's total balance owed
• FR-007: System MUST display the sum of all fees as a line item in the sponsor's cost breakdown
• FR-008: System MUST display each individual fee with its amount and description in the itemised costs view
• FR-009: System MUST clearly distinguish credits (negative fees) from charges (positive fees) in the display
• FR-010: System MUST recalculate the total balance owed immediately when a fee is added, modified, or removed
• FR-011: System MUST prevent adding fees with invalid amounts (non-numeric, empty, or improperly formatted values)
• FR-012: System MUST allow multiple fees to be added to a single stand
• FR-013: System MUST persist fees so they remain associated with the stand across sessions
• FR-014: Admins MUST be able to view all fees added to a stand in chronological order
• FR-015: Admins MUST be able to edit the amount and description of existing fees
• FR-016: Admins MUST be able to delete fees from a stand
• FR-017: System MUST recalculate the balance owed when a fee is edited or deleted
• FR-018: System MUST handle balance calculations correctly when negative fees result in a negative balance owed (credit to sponsor)

Key Entities (include if feature involves data)

• Additional Fee: Represents a custom charge or credit applied to a sponsor stand, containing an amount (monetary value, can be positive or negative), description (text explaining the charge/credit), the stand it's associated with, timestamp of creation, and the admin who added it
• Sponsor Stand: Existing entity that now has a relationship to multiple additional fees, with the total balance owed calculated from package costs plus the sum of all associated fees (including negative fees)
• Balance Owed: Calculated value representing the total amount a sponsor must pay (or credit owed if negative), now including base package costs plus the sum of all additional fees

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: Admins can add a fee to a sponsor stand in under 30 seconds from the stand details page
• SC-002: Balance owed calculations update in real-time (within 2 seconds) when fees are added, modified, or removed
• SC-003: 100% of fees added by admins appear correctly in the sponsor's itemised cost breakdown
• SC-004: Fee descriptions display completely without truncation in all views where costs are shown
• SC-005: System accurately calculates balance owed with multiple fees including negative amounts (verified through test cases with 10+ fees totaling various amounts)
• SC-006: Credits (negative fees) are visually distinguishable from charges in under 3 seconds of viewing the breakdown
• SC-007: Admins can edit or delete a fee in under 20 seconds

Assumptions (optional)

• Fees are associated with individual sponsor stands, not with entire events or organisers
• Multiple fees can be added to a single stand without limit
• Fees can be added at any point in the event lifecycle (before, during, or after the event)
• Standard currency handling applies (GBP with 2 decimal precision)
• Fees are visible to both admins and the sponsors who own the stand
• Fee amounts are additive to existing costs (not replacement values)
• Admins have appropriate permissions to add, edit, and delete fees (existing admin role suffices)
• Negative balances (when credits exceed charges) are acceptable and handled by the payment system
• Edit and delete operations on fees do not require special approval or audit logging beyond standard system activity logs

Communication and Notifications

• Q: When a new message thread is created and routed to a team (e.g., "admins"), who receives the notification? → A: All members who have that particular notification enabled either in-app or email
• Q: When a user's WebSocket connection drops, what is the reconnection behavior? → A: delegated to frontend websockets provider

User Scenarios & Testing (mandatory)

User Story 1 - Sponsor Submits Event Query (Priority: P1)

A sponsor has a question about their stand configuration for an upcoming event and needs to contact the organiser. They create a new message thread which automatically routes to the event organiser, who receives both an email notification and an in-app alert. The organiser responds within the thread, and the sponsor is notified immediately through their chosen notification method.

Why this priority: This is the core messaging functionality that enables basic communication between sponsors and organisers. Without this, sponsors cannot get help with event-specific questions, which is essential for the platform's primary purpose.

Independent Test: Can be fully tested by having a sponsor create a message about an event, verifying it routes to the correct organiser, and confirming both parties receive notifications and can exchange responses.

Acceptance Scenarios:

1. Given a sponsor is viewing their event dashboard, When they click "Contact Organiser" and submit a question about stand requirements, Then a message thread is created and routed to the event organiser
2. Given a message thread has been created by a sponsor, When the organiser logs in, Then they see an unread message notification and can view the full thread
3. Given an organiser has responded to a sponsor's message, When the response is submitted, Then the sponsor receives a notification through their preferred channel (email or in-app)
4. Given a sponsor has in-app notifications enabled, When they are logged in and a new response arrives, Then they see a real-time notification without refreshing the page

---

User Story 2 - Sponsor Requests Artwork Assistance (Priority: P1)

A sponsor encounters a technical issue while uploading artwork and needs admin support. They create a message with the subject "Artwork Upload Problem" which automatically routes to the admin team. The admin team receives immediate notification and can respond with troubleshooting steps, with all communication tracked in a threaded conversation.

Why this priority: Artwork management is a critical workflow, and sponsors need quick access to technical support when issues arise. This is equally important to event queries as it unblocks sponsors from completing their required tasks.

Independent Test: Can be tested by having a sponsor create an artwork-related message, verifying it routes to admins (not organisers), and confirming the admin team can respond and resolve the issue within the thread.

Acceptance Scenarios:

1. Given a sponsor is on the artwork management page, When they create a message with an artwork-related subject, Then the message is automatically routed to the admin team
2. Given a message has been routed to admins, When an admin views their message inbox, Then they see the new thread marked as "Artwork Query"
3. Given an admin responds to an artwork query, When the sponsor receives the response, Then they can continue the conversation in the same thread without creating a new message

---

User Story 3 - User Customises Notification Preferences (Priority: P2)

A sponsor who receives many notifications prefers to check the platform regularly rather than receive email alerts. They navigate to their profile settings and configure their notification preferences to receive in-app notifications only for new messages, while keeping email notifications enabled for payment confirmations and deadline reminders.

Why this priority: Notification fatigue is a real concern, and users need control over how they're contacted. This improves user experience but isn't required for basic communication functionality to work.

Independent Test: Can be tested by having a user update their notification preferences for different notification types, then triggering those notification types and verifying they are delivered only through the selected channels.

Acceptance Scenarios:

1. Given a user is in their profile settings, When they view the notification preferences section, Then they see a list of all notification types with options to enable/disable email and in-app notifications for each
2. Given a user has disabled email notifications for message responses, When they receive a new message response, Then they only receive an in-app notification and no email is sent
3. Given a user has enabled both email and in-app notifications for a notification type, When that notification is triggered, Then they receive both an email and an in-app alert
4. Given a user has disabled all in-app notifications, When notifications are triggered, Then they still receive emails (if email is enabled) and can view notifications in their notification history

---

User Story 4 - Admin Configures Message Types and Routing (Priority: P2)

An admin needs to adjust how messages are routed because the organisation has added a new team to handle sponsorship package queries. They access the system settings and create a new message type called "Sponsorship Enquiry" and configure it to route to the sales team rather than event organisers. When sponsors create messages, they select from available message types.

Why this priority: Flexible routing is important for scaling the platform as organisations grow and add new teams, but the system can function with basic message types initially. This can be implemented after core messaging works.

Independent Test: Can be tested by an admin creating or modifying message types and routing rules, then having sponsors create messages of different types and verifying they route to the correct recipients.

Acceptance Scenarios:

1. Given an admin is in system settings, When they navigate to message type configuration, Then they see a list of existing message types with options to add, edit, or remove types
2. Given an admin creates a new message type with a routing destination, When a sponsor creates a message and selects that type, Then the message is routed to the configured recipient team
3. Given a sponsor is creating a new message, When they view the message type selector, Then they see all active message types to choose from (each thread can only have one type)
4. Given an admin modifies a message type's routing destination, When new messages of that type are created, Then they route to the updated destination (existing threads remain with original routing)

---

User Story 5 - User Receives Real-Time In-App Notification (Priority: P3)

An organiser is working in the platform reviewing sponsor registrations when a new message arrives from a sponsor. Without refreshing the page, a notification badge appears on the messages icon in the navigation bar, and a toast notification briefly displays in the corner of the screen with a preview of the message.

Why this priority: Real-time notifications enhance user experience and improve response times, but users can still function effectively by refreshing the page or checking their email. This is a polish feature that can be implemented after core functionality is stable.

Independent Test: Can be tested by having a user logged in while another user sends them a message, verifying the notification appears instantly without page refresh, and confirming the notification UI elements work correctly.

Acceptance Scenarios:

1. Given a user is logged in with in-app notifications enabled, When a new message or response is sent to them, Then they see a real-time notification within 2 seconds without page refresh
2. Given a notification arrives while a user is on any page, When the notification displays, Then it includes a preview of the message and a link to view the full thread
3. Given multiple notifications arrive in quick succession, When they are displayed, Then they stack or queue appropriately without overlapping or blocking the interface
4. Given a user clicks on a notification toast, When they are navigated to the relevant content, Then the notification is marked as read

---

Edge Cases

• What happens when a message doesn't match any routing rule? (Default behaviour needed)
• How does the system handle messages sent to users who have deleted their accounts or been removed from events?
• What happens if a user has disabled all notification methods for a critical notification type?
• How are notifications handled for users who are logged in on multiple devices simultaneously?
• What occurs when the real-time notification service is temporarily unavailable?
• How does the system manage notification delivery for users in different time zones or with scheduled "do not disturb" preferences?
• What happens to unread notifications when a user's role changes (e.g., organiser becomes admin)?
• How are notification preferences migrated if notification types are added or removed in future updates?

Requirements (mandatory)

Functional Requirements

Message Management

• FR-001: System MUST allow sponsors to create new message threads with a message type, subject, message body, and optional attachments
• FR-002: System MUST require users to select exactly one message type when creating a thread
• FR-003: System MUST route messages to appropriate recipients (organisers or admins) based on the selected message type
• FR-004: System MUST support threaded conversations with chronological message history
• FR-005: System MUST display message status indicators (new, read, replied, resolved)
• FR-006: System MUST allow all participants in a thread to add responses (sponsor creator, any routed recipient team member, and event organiser) using a collaborative support model
• FR-007: System MUST support file attachments up to 10MB per message
• FR-008: System MUST preserve message context by linking messages to relevant entities (events, stands, artwork submissions)
• FR-009: System MUST prevent changing the message type after a thread is created

Message Type Configuration

• FR-010: System MUST provide admins with an interface to create and manage message types
• FR-011: System MUST allow admins to configure a routing destination (recipient team) for each message type
• FR-012: System MUST support at minimum two routing destinations: organisers and admins
• FR-013: System MUST allow admins to set message types as active or inactive
• FR-014: System MUST hide inactive message types from user selection but preserve them for existing threads
• FR-015: System MUST validate message type configuration to ensure each type has a routing destination
• FR-016: System MUST apply routing based on the message type selected at thread creation time
• FR-017: System MUST provide default message types on system installation (e.g., "Event Query" → organisers, "Artwork Support" → admins, "Technical Issue" → admins)

Notification System

• FR-018: System MUST generate notifications to all routed team members when a new message thread is created, respecting each user's notification preferences
• FR-019: System MUST generate notifications to all thread participants when a response is added to an existing thread, respecting each user's notification preferences
• FR-020: System MUST support multiple notification types beyond messaging (e.g., payment confirmations, deadline reminders, event updates, artwork approval status)
• FR-021: System MUST deliver notifications through email channels when enabled
• FR-022: System MUST deliver notifications through in-app channels when enabled
• FR-023: System MUST persist in-app notifications indefinitely as unread if user lacks an active WebSocket connection and display them when user next logs in
• FR-024: System MUST track notification delivery status (sent, delivered, read, failed)
• FR-025: System MUST provide users with a notification history showing all past notifications

Notification Preferences

• FR-026: System MUST allow users to configure notification preferences in their profile settings
• FR-027: System MUST provide per-notification-type controls for email delivery
• FR-028: System MUST provide per-notification-type controls for in-app delivery
• FR-029: System MUST allow users to enable, disable, or configure both channels independently for each notification type
• FR-030: System MUST save notification preference changes immediately and apply them to all future notifications
• FR-031: System MUST provide reasonable default notification preferences for new users
• FR-032: System MUST respect user preferences when generating notifications across all platform features, delivering only through channels enabled by each individual user

Real-Time In-App Notifications

• FR-033: System MUST deliver in-app notifications in real-time to logged-in users without requiring page refresh
• FR-034: System MUST use persistent connections for real-time notification delivery
• FR-035: System MUST display notification count badges on relevant navigation elements
• FR-036: System MUST display transient notification toasts when new notifications arrive
• FR-037: System MUST update notification UI across all open browser tabs for the same user
• FR-038: System MUST handle connection failures gracefully with reconnection behavior delegated to the frontend WebSocket provider
• FR-039: System MUST fall back to polling or next-page-load notification display if real-time delivery fails
• FR-040: System MUST mark notifications as read when user views the related content

Key Entities

• Message Thread: Represents a conversation initiated by a user, containing a subject, message type, creation date, participants, status, and linked entity references (event, stand, artwork). Threads maintain chronological message history. Each thread has exactly one message type that cannot be changed after creation. Participants always include: the sponsor who created the thread, the routed recipient team (based on message type), and the event organiser for that event.

• Message: Individual communication within a thread, containing sender, timestamp, message body, optional attachments, read status, and relationship to parent thread.

• Message Type: System-configurable category that determines how messages are routed, containing type name, description, routing destination (organiser/admin team), active status, and display order. Examples: "Event Query", "Artwork Support", "Technical Issue", "Sponsorship Enquiry".

• Notification: Record of an event requiring user attention, containing notification type, recipient, creation timestamp, delivery status, related content reference, read status, and delivery channels used.

• Notification Preference: User-specific configuration defining how each notification type should be delivered, containing user reference, notification type, email enabled flag, in-app enabled flag, and last updated timestamp.

• Notification Type: System-defined category of notifications (e.g., "New Message", "Payment Confirmation", "Deadline Reminder"), containing type identifier, display name, description, and default delivery settings.

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: Sponsors can send a message and receive a response from the appropriate recipient within one business day for 90% of queries
• SC-002: 95% of messages are automatically routed to the correct recipient type without requiring manual re-assignment
• SC-003: Users receive in-app notifications within 2 seconds of the triggering event when logged in
• SC-004: 80% of users configure at least one notification preference within their first week of using the platform
• SC-005: Message threads maintain complete conversation history with zero message loss
• SC-006: Users can locate and respond to messages within 3 clicks from any page in the platform
• SC-007: System successfully delivers 99% of email notifications within 5 minutes of generation
• SC-008: Notification preference changes take effect immediately for all subsequent notifications
• SC-009: Real-time notification connections remain stable for 95% of user sessions without disconnection
• SC-010: Users report improved communication satisfaction scores compared to external email-only communication

Assumptions (optional)

User Behaviour Assumptions

• Users will select the appropriate message type when creating threads
• Users will check the platform at least once per business day when active with an event
• Users understand the difference between organisers (event-specific queries) and admins (technical support)
• Users who disable all notification methods understand they are responsible for checking the platform regularly

System Context Assumptions

• User authentication and session management are already implemented
• User roles (sponsor, organiser, admin) are defined and enforced
• File upload infrastructure exists for handling attachments
• Email delivery service integration is available
• Events, stands, and artwork entities exist and can be referenced by messages

Technical Assumptions

• Modern browsers supporting WebSocket connections are used by majority of users
• Email service has sufficient sending capacity for notification volumes
• User devices have stable internet connections for real-time features
• Platform has infrastructure to maintain persistent connections for real-time features
• WebSocket reconnection logic is handled by the frontend WebSocket provider library

Configuration Assumptions

• System will be installed with default message types: "Event Query" → organisers, "Stand Configuration Query" → organisers, "Artwork Support" → admins, "Technical Issue" → admins, "Payment Query" → admins
• Default notification preferences for new users: all notification types enabled for both email and in-app
• Attachments are limited to standard document and image formats (PDF, JPG, PNG, DOC, XLS)
• Message history is retained for the lifetime of the associated event plus 12 months

Dependencies (optional)

Internal Dependencies

• User Management System: Required for user authentication, role determination, and profile management
• Event Management System: Required to link messages to specific events and identify event organisers
• Permission System: Required to enforce access controls on message threads and routing configuration
• File Storage System: Required for attachment upload, storage, and retrieval
• Email Service Integration: Required for email notification delivery

External Dependencies

• Email Service Provider: Service must support transactional email sending with tracking
• Browser Support: Requires browsers with WebSocket support (all modern browsers)
• Network Infrastructure: Requires stable network connectivity for real-time features

Constraints (optional)

Business Constraints

• Messages must be retained for audit purposes for the duration of the event relationship
• Admins are the only users permitted to configure message types and routing destinations
• Message types cannot be changed after a thread is created to maintain audit trail
• Notification preferences are user-controlled and cannot be overridden by admins (except for system-critical notifications)
• Response time expectations: admins should respond to technical queries within 4 business hours; organisers should respond to event queries within 1 business day

Technical Constraints

• File attachment size limited to 10MB per message
• Supported attachment types limited to common business formats (no executable files)
• Real-time notification delivery requires WebSocket support
• Email sending subject to rate limits imposed by email service provider (typically 100-500 per hour for transactional emails)
• Notification history retained for 90 days after being marked as read (unread notifications persist indefinitely)

User Experience Constraints

• Message threads cannot be deleted by users (only marked as resolved/closed) to maintain audit trail
• Message type cannot be changed after thread creation
• Threads use collaborative support model - no assignment or locking mechanism required
• Notification toasts should auto-dismiss after 5-8 seconds to avoid cluttering the interface
• Maximum of 3 simultaneous notification toasts displayed to prevent UI overload
• Message routing based solely on user-selected message type (no keyword analysis or AI-based classification)

Security and Privacy Constraints

• Users can only view message threads they are participants in (sponsor creator, routed recipient team members, and event organiser for the associated event)
• Attachments are scanned for malware before being made available
• Message content is not indexed for full-text search to protect privacy (only subject lines and metadata)
• Notification content in emails must not expose sensitive information beyond what's necessary to prompt user login

System Administration

User Scenarios & Testing (mandatory)

User Story 1 - Admin Configures Default Event Deadlines (Priority: P1)

An admin accesses the system settings area and configures default deadline offsets that will automatically apply to new events. They set configuration deadline to 30 days before event start, artwork deadline to 14 days before event start, and proof approval deadline to 7 days before event start. When organisers create new events, these deadlines are automatically calculated based on the event start date, but can be overridden per event if needed.

Why this priority: Default deadlines eliminate repetitive data entry and ensure consistency across events. Without this, every event requires manual deadline entry, leading to errors and inconsistency. This is foundational for efficient event creation.

Independent Test: Can be fully tested by configuring default deadline offsets, creating a new event, verifying deadlines are auto-calculated correctly, and confirming organisers can override them. Delivers immediate value by streamlining event creation.

Acceptance Scenarios:

1. Given an admin is in system settings, When they navigate to deadline configuration and set "Configuration Deadline" to "30 days before event start", Then the default offset is saved and will apply to all new events
2. Given default deadlines are configured, When an organiser creates a new event with start date 2025-06-15, Then the system automatically calculates configuration deadline as 2025-05-16, artwork deadline based on its offset, and proof approval deadline based on its offset
3. Given an event is created with auto-calculated deadlines, When an organiser views the event details, Then they see the calculated deadlines and can manually adjust them if needed
4. Given an admin updates a default deadline offset, When organisers create new events, Then the new offset is used for calculation (existing events remain unchanged)
5. Given default deadline offsets are configured, When validation runs, Then the system ensures deadlines maintain logical sequence (configuration < artwork < proof < event start)

---

User Story 2 - Admin Manages VAT Rate Configuration (Priority: P1)

An admin configures VAT rates for different combinations of sponsor location and event location. They define that UK sponsors booking UK events pay 20% VAT, EU sponsors booking UK events pay 0% VAT (reverse charge), and set a default rate of 20% for unmatched combinations. The system maintains a history of rate changes with effective dates for audit compliance.

Why this priority: VAT calculation is legally required and must be correct from day one. Incorrect VAT rates lead to compliance issues, financial penalties, and loss of customer trust. This must be configurable before any payments are processed.

Independent Test: Can be tested by configuring VAT rules for various location combinations, creating bookings with different sponsor/event locations, and verifying correct rates are applied at checkout. Delivers legal compliance.

Acceptance Scenarios:

1. Given an admin is in VAT configuration, When they create a rule for "UK sponsor + UK event = 20% VAT" with effective date 2025-01-01, Then the rule is saved and will apply to qualifying transactions from that date
2. Given multiple VAT rules exist, When a UK sponsor books a UK event after the effective date, Then the system applies the 20% VAT rate
3. Given no VAT rule matches a booking combination, When the system calculates VAT, Then it applies the configured default rate and logs a warning for admin review
4. Given an admin updates a VAT rate, When they save changes with a future effective date, Then the new rate applies from that date forward while maintaining rate history for audit
5. Given an organiser creates an event, When they access event settings, Then they can override system-wide VAT rules for that specific event if needed

---

User Story 3 - Admin Customises Notification Templates (Priority: P2)

An admin reviews system notification templates and customises the "Sponsor Invitation" email to include company-specific branding and wording. They use template variables like {event_name}, {sponsor_name}, and {invitation_link} to personalize messages. They preview the template with sample data, save changes, and organisers immediately see the updated template when sending invitations.

Why this priority: Custom notification templates improve brand consistency and user experience, but the system can function with default templates. This enhances professionalism but isn't required for core operations.

Independent Test: Can be tested by modifying a template, previewing it with sample data, saving changes, and triggering that notification type to verify the customized version is used. Delivers brand customization capability.

Acceptance Scenarios:

1. Given an admin is in template management, When they view available templates, Then they see categories including: Invitations, Deadline Reminders, Payment Confirmations, Event Updates, and System Notifications
2. Given an admin selects the "Sponsor Invitation" template, When they edit content using the rich text editor and insert variables {event_name} and {sponsor_name}, Then the template is updated and variable placeholders are highlighted
3. Given an admin has modified a template, When they click "Preview", Then they see how the email will look with sample variable values populated
4. Given an admin saves template changes, When organisers send invitations, Then the customized template is used with actual variable values from the event and sponsor data
5. Given multiple templates exist, When an organiser creates an event, Then they can optionally override system templates with event-specific versions

---

User Story 4 - Admin Reviews and Updates System Settings (Priority: P3)

An admin periodically reviews system-wide settings to ensure they reflect current business needs. They check default deadline offsets, review recent VAT transactions for compliance, verify notification templates are appropriate, and adjust settings as regulations or business processes change. All changes are logged for audit purposes.

Why this priority: Regular review and maintenance are important for long-term system health, but can be scheduled activities rather than immediate requirements. This provides ongoing optimization capability.

Independent Test: Can be tested by accessing system settings, reviewing each configuration area, making adjustments, and verifying audit logs capture all changes. Delivers system maintenance capability.

Acceptance Scenarios:

1. Given an admin accesses system settings dashboard, When they view the overview, Then they see sections for: Deadline Configuration, VAT Rules, Notification Templates, and System Preferences
2. Given an admin is reviewing VAT configuration, When they view the rate history, Then they see all historical rate changes with effective dates, who made changes, and when
3. Given an admin needs to update multiple settings, When they make changes across different configuration areas, Then each change is independently saved and logged in the audit system
4. Given an admin wants to understand system defaults, When they view deadline configuration, Then they see current default offsets, when they were last modified, and how many events are using defaults vs overrides
5. Given changes are made to system settings, When admins review audit logs, Then they see complete change history including: setting changed, old value, new value, timestamp, and admin user who made the change

---

Edge Cases

• What happens when an admin sets deadline offsets that result in negative dates or invalid sequences? (Validation prevents saving illogical configurations)
• How does the system handle VAT rate changes that occur mid-booking between initial payment and balance payment? (Balance payment uses rate effective at time of payment, documented in assumptions)
• What happens when a template variable references data that doesn't exist for a particular notification? (Variable displays as empty string or placeholder text like "[Not Available]")
• How does the system handle concurrent admin updates to the same setting? (Last save wins, with both changes logged in audit trail)
• What happens when an event with overridden settings is duplicated? (Duplicated event inherits current system defaults, not the original event's overrides)
• How does the system handle multiple VAT rules with overlapping effective dates? (Most recent effective date takes precedence; system prevents creating rules with same criteria and overlapping dates)
• What happens when default deadlines are updated after many events already exist? (Existing events retain their configured deadlines; only new events use updated defaults)
• How are notification templates handled when events span multiple languages or regions? (Out of scope for initial version; single template set in system default language)

Requirements (mandatory)

Functional Requirements

Default Deadline Configuration

• FR-001: System MUST allow admins to configure default deadline offsets as number of days before event start date
• FR-002: System MUST support deadline types: configuration deadline, artwork deadline, proof approval deadline, and payment deadline
• FR-003: System MUST validate that default deadline offsets maintain logical sequence when applied (configuration < artwork < proof < event start)
• FR-004: System MUST automatically calculate event deadlines based on default offsets when events are created
• FR-005: System MUST allow organisers to override auto-calculated deadlines at the event level
• FR-006: System MUST display whether an event is using default deadlines or has overrides in event management interface
• FR-007: System MUST track when default deadline offsets were last modified and by which admin user
• FR-008: System MUST apply updated default offsets only to newly created events, not existing events

VAT Rate Configuration

• FR-009: System MUST allow admins to create VAT rules based on sponsor location and event location combinations
• FR-010: System MUST support location categories: UK, EU, and Rest of World for both sponsor and event locations
• FR-011: System MUST allow admins to set VAT rate as a percentage (0-100%) for each location combination
• FR-012: System MUST support effective dates for VAT rules to handle future rate changes
• FR-013: System MUST maintain complete history of VAT rate changes with effective dates for audit compliance
• FR-014: System MUST allow admins to configure a default VAT rate that applies when no specific rule matches
• FR-015: System MUST log a warning when default VAT rate is applied due to no matching rule
• FR-016: System MUST allow organisers to override system-wide VAT rules at the event level
• FR-017: System MUST validate VAT rates are between 0% and 100%
• FR-018: System MUST prevent creating duplicate VAT rules with overlapping effective dates for the same location combination

Notification Template Management

• FR-019: System MUST provide admins with access to manage system-wide notification templates
• FR-020: System MUST support template categories: Invitations, Deadline Reminders, Payment Confirmations, Event Updates, System Notifications
• FR-021: System MUST provide a rich text editor for template content editing
• FR-022: System MUST support template variables that are replaced with actual data when notifications are sent
• FR-023: System MUST support minimum template variables: user information (name, email, company), event details (name, date, location, deadlines), stand information, payment information
• FR-024: System MUST highlight template variables in the editor to distinguish them from regular text
• FR-025: System MUST provide a preview function that shows how templates appear with sample data
• FR-026: System MUST allow organisers to create event-specific template overrides that take precedence over system defaults
• FR-027: System MUST handle missing variable data gracefully by displaying empty string or "[Not Available]" placeholder
• FR-028: System MUST maintain template version history for rollback capability

System Settings Access and Security

• FR-029: System MUST restrict system settings access to users with admin role only
• FR-030: System MUST provide a system settings dashboard showing all configurable areas
• FR-031: System MUST validate admin permissions before allowing any configuration changes
• FR-032: System MUST log all system setting changes in the audit system with: setting name, old value, new value, timestamp, admin user
• FR-033: System MUST prevent non-admin users from accessing or viewing system settings pages
• FR-034: System MUST support concurrent admin access with last-save-wins approach for conflict resolution

Event-Level Overrides

• FR-035: System MUST allow organisers with appropriate permissions to override default deadlines for specific events
• FR-036: System MUST allow organisers to override VAT rules for specific events
• FR-037: System MUST allow organisers to override notification templates for specific events
• FR-038: System MUST display whether an event is using system defaults or has overrides
• FR-039: System MUST track override history at the event level
• FR-040: System MUST allow organisers to revert event-level overrides back to system defaults

Key Entities

• Default Deadline Configuration: System-wide settings defining deadline offsets in days before event start, containing configuration deadline offset, artwork deadline offset, proof approval deadline offset, payment deadline offset, last modified date, and last modified by admin user. Applied automatically to new events.

• VAT Rule: Configuration defining VAT rates for sponsor-event location combinations, containing sponsor location (UK/EU/Rest of World), event location (UK/EU/Rest of World), VAT rate percentage, effective date, end date (optional), created date, and created by admin user. Maintains historical record for audit compliance.

• Notification Template: Customizable email or in-app message template containing template name, category (Invitations/Reminders/Confirmations/Updates/System), subject line, body content (rich text), supported variables list, version number, last modified date, last modified by admin user, and active status.

• System Setting: General configuration entry containing setting name, setting value, data type, default value, validation rules, last modified date, last modified by admin user, and description.

• Event Override: Record of event-specific configuration that supersedes system defaults, containing event reference, override type (deadline/VAT/template), override value, original system default value at time of override, created date, created by user, and active status.

• Template Variable: Placeholder in notification templates that gets replaced with actual data, containing variable name, variable key (e.g., {event_name}), data source (user/event/stand/payment), description, example value, and supported templates.

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: Admins can configure complete default deadline settings (all deadline types) in under 5 minutes
• SC-002: 90% of newly created events use auto-calculated deadlines without requiring manual adjustment
• SC-003: System correctly applies VAT rates for 100% of bookings based on configured rules
• SC-004: Admins can create or modify a VAT rule in under 2 minutes
• SC-005: Notification templates can be customized and previewed in under 10 minutes per template
• SC-006: 95% of notification templates use variables correctly without missing data errors
• SC-007: System settings page loads all configuration areas in under 2 seconds
• SC-008: Audit logs capture 100% of system setting changes with complete attribution
• SC-009: Organisers can override event-specific settings in under 3 minutes
• SC-010: Event creation time is reduced by 40% when using default deadline auto-calculation compared to manual entry
• SC-011: VAT compliance audit requests can be satisfied within 30 minutes using system rate history
• SC-012: Template preview accurately represents final notification appearance with 100% variable replacement accuracy

Assumptions (optional)

Business Process Assumptions

• Admin users are trusted to configure system-wide settings appropriately
• VAT rules require periodic review and updates as tax legislation changes
• Template customization follows corporate brand guidelines managed outside the system
• Event-level overrides are exception cases, not the norm (most events use defaults)

User Behaviour Assumptions

• Admins will validate deadline sequences before saving default configurations
• Admins understand VAT compliance requirements for their jurisdiction
• Admins test notification templates using preview before deploying to production use
• Organisers understand when to use system defaults vs when overrides are necessary

System Context Assumptions

• User management system enforces admin role-based access control
• Audit logging system exists and captures all configuration changes
• Event management system supports deadline calculation from event start date
• Payment system can query VAT rules based on sponsor and event locations
• Notification system can parse and replace template variables with actual data

Data Assumptions

• Location data (UK/EU/Rest of World) is maintained for both sponsors and events
• Event start dates are mandatory and validated before deadline calculation
• Template variables reference data that exists in the system at notification send time
• Historical VAT rates are retained indefinitely for compliance (no data purging)

Configuration Assumptions

• Default deadline offsets initially configured as: configuration deadline = 30 days, artwork deadline = 14 days, proof approval deadline = 7 days, payment deadline = 7 days
• Default VAT rate set to 20% UK standard rate when no specific rule matches
• System installed with standard template set covering all notification categories
• Concurrent admin edits resolve with last-save-wins (no conflict detection or locking)

Dependencies (optional)

Internal Dependencies

• User Management System: Required for admin role validation and access control
• Event Management System: Required to apply default deadlines and support event-level overrides
• Payment System: Required to query and apply VAT rules during checkout
• Notification System: Required to use templates and replace variables when sending notifications
• Audit Logging System: Required to track all system setting changes for compliance
• Permission System: Required to enforce admin-only access to system settings

External Dependencies

• Email Service: Required for sending notifications using customized templates
• None for VAT or deadline configuration (purely internal system functionality)

Constraints (optional)

Business Constraints

• System settings changes require admin privileges - cannot be delegated to organiser role
• VAT rate changes must maintain historical records for minimum 7 years for audit compliance
• Default deadline offsets must result in future dates when applied to event start dates
• Event-level overrides do not affect other events (changes are isolated per event)
• Template variables must reference data that exists in the system (no external data sources)

Technical Constraints

• Maximum 50 VAT rules can be configured to maintain query performance
• Template content limited to 50,000 characters to prevent email delivery issues
• Default deadline offsets limited to 365 days maximum (approximately 1 year before event)
• Concurrent admin setting updates use last-save-wins (no optimistic locking)
• Template preview limited to 10 sample records to prevent performance impact

User Experience Constraints

• System settings interface must clearly indicate which settings affect new events vs existing events
• Template editor must validate variable syntax before saving
• VAT rule effective dates cannot overlap for the same location combination
• Event-level overrides must clearly display which system default they are replacing
• Audit logs for system settings must be accessible to admins within 2 clicks

Security and Compliance Constraints

• All system setting changes must be logged with user attribution for audit trail
• VAT rate history cannot be deleted or modified retroactively
• Admin access to system settings must be validated on every request
• Template content is not sanitized for script injection (templates created by trusted admin users only)
• Event-level overrides do not require approval workflow (organiser decision is final)

Frequently Asked Questions

User Scenarios & Testing (mandatory)

User Story 1 - Central FAQ Library Management (Priority: P1)

As a system administrator, I need to manage a central library of frequently asked questions that can be reused across all events, so that I can maintain consistent information and reduce duplication of effort.

Why this priority: This is the foundation of the FAQ system. Without a central library, organisers would need to recreate FAQs for every event, leading to inconsistency and wasted effort. This delivers immediate value by creating a single source of truth.

Independent Test: Can be fully tested by creating, editing, and deleting FAQs in the central library, assigning them to categories, and verifying they are available as defaults for new events. Delivers value by reducing content creation time for organisers.

Acceptance Scenarios:

1. Given I am logged in as an admin, When I navigate to the central FAQ management area, Then I can see all global FAQs organised by category
2. Given I am creating a new FAQ, When I enter a question and answer, Then I can assign it to one or more categories
3. Given I have created a FAQ, When I edit the question or answer, Then the changes are saved and reflected in the central library
4. Given I have created a FAQ, When I delete it from the central library, Then it is removed from the global defaults but remains on events where it has been explicitly added or overridden
5. Given I am an event organiser, When I attempt to access the central FAQ admin area, Then I am denied access

---

User Story 2 - Event-Specific FAQ Management for Organisers (Priority: P2)

As an event organiser, I need to manage FAQs for my specific event by inheriting global defaults, overriding their content when needed, and adding event-specific questions, so that attendees and sponsors receive accurate information relevant to my event.

Why this priority: This enables event customisation while maintaining the efficiency of global defaults. It's the primary use case for organisers and directly impacts the attendee/sponsor experience.

Independent Test: Can be fully tested by creating an event, viewing inherited FAQs, overriding a global FAQ's answer, adding a new event-specific FAQ, and verifying these changes only affect the current event. Delivers value by allowing event customisation without affecting other events.

Acceptance Scenarios:

1. Given I am logged in as an event organiser, When I view my event's FAQ section, Then I see all global FAQs inherited as defaults, organised by category
2. Given I have inherited FAQs from the central library, When I override the answer for a specific FAQ, Then the modified answer is displayed for my event only and the global FAQ remains unchanged
3. Given I am managing my event's FAQs, When I create a new FAQ specific to my event, Then it is added to the event's FAQ list and is not visible in the central library or other events
4. Given I have overridden a global FAQ, When an admin updates the original global FAQ, Then my event-specific override remains unchanged
5. Given I have added event-specific FAQs, When I delete them, Then they are removed from my event only

---

User Story 3 - Category-Based FAQ Organisation (Priority: P3)

As an admin or organiser viewing FAQs, I need to see FAQs organised by categories, so that I can quickly find and manage related questions and provide a better user experience for those reading the FAQs.

Why this priority: This improves usability and discoverability for both administrators and end users. While important, the system can function without categories initially.

Independent Test: Can be fully tested by creating categories, assigning multiple FAQs to multiple categories, and verifying that FAQs appear under all assigned categories. Delivers value by improving content organisation and navigation.

Acceptance Scenarios:

1. Given I am managing FAQs, When I assign an FAQ to multiple categories, Then it appears in all selected categories
2. Given I am viewing FAQs by category, When I select a category filter, Then I see only FAQs assigned to that category
3. Given I am creating a category, When I save it, Then it becomes available for assigning to FAQs
4. Given an FAQ is assigned to a category that is later deleted, When the category is deleted, Then the FAQ is unassigned from that category and remains in any other categories it is assigned to (or becomes uncategorised if it was the only category)

---

Edge Cases

• What happens when an admin deletes a global FAQ that has been overridden on specific events? (System should preserve the event-specific overrides as independent content)
• What happens when an organiser attempts to override an FAQ that has already been overridden? (System should allow re-editing the override)
• What happens when multiple admins edit the same global FAQ simultaneously? (Last save wins with standard conflict resolution)
• What happens when an FAQ exists without any category assigned? (FAQ should still be accessible and function normally, displayed in an "Uncategorised" section)
• What happens when an event is duplicated or cloned? (Event-specific FAQs and overrides should be copied to the new event)

Requirements (mandatory)

Functional Requirements

• FR-001: System MUST provide a central FAQ library accessible only to admins for creating, editing, and deleting global FAQs
• FR-002: System MUST allow FAQs to be assigned to multiple categories via many-to-many relationships
• FR-003: System MUST automatically inherit all global FAQs as defaults when a new event is created
• FR-004: System MUST allow event organisers to override the answer of any inherited global FAQ for their specific event
• FR-005: System MUST allow event organisers to create new FAQs specific to their event that do not appear in other events or the central library
• FR-006: System MUST preserve event-specific overrides when the original global FAQ is updated by an admin
• FR-007: System MUST distinguish between inherited FAQs, overridden FAQs, and event-specific FAQs in the organiser interface
• FR-008: System MUST allow deletion of event-specific FAQs without affecting the central library or other events
• FR-009: System MUST prevent event organisers from accessing the central FAQ admin area
• FR-010: System MUST allow event organisers and admins to manage FAQ categories for their respective contexts
• FR-011: System MUST display FAQs organised by their assigned categories
• FR-012: System MUST handle FAQs with no category assignment by displaying them in an accessible manner
• FR-013: System MUST allow deletion of categories, automatically unassigning all FAQs from the deleted category whilst preserving the FAQs themselves
• FR-014: System MUST provide a search bar that allows users to search FAQs by entering a string query that matches against question text and answer content

Key Entities

• FAQ: Represents a question and answer pair, with attributes including question text, answer text, category assignments, and tracking whether it is global or event-specific
• Category: Represents a grouping mechanism for FAQs, with many-to-many relationships allowing FAQs to belong to multiple categories
• Event: The context within which FAQs are displayed, with relationships to both inherited global FAQs and event-specific FAQs/overrides
• FAQ Override: Links an event to a global FAQ with a modified answer, preserving the original global FAQ while providing event-specific content

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: Admins can create and manage global FAQs in under 2 minutes per FAQ
• SC-002: Event organisers can locate and override an inherited FAQ in under 1 minute
• SC-003: Event organisers can create a new event-specific FAQ in under 2 minutes
• SC-004: 90% of events use at least 70% of global FAQs without requiring overrides, demonstrating the value of the central library
• SC-005: Time spent on FAQ management across all events is reduced by 60% compared to creating FAQs independently for each event
• SC-006: Users can navigate FAQ categories and find relevant questions in under 30 seconds

Assumptions

• Event organisers have sufficient permissions to manage content within their assigned events
• The system tracks creation and modification dates for audit purposes
• FAQs support rich text formatting for answers (e.g., bullet points, links, basic formatting)
• The display interface for end users (attendees/sponsors viewing FAQs) is separate from the admin/organiser management interface
• Multiple admins may work on the central FAQ library, requiring standard concurrent editing safeguards
• Categories are managed separately from FAQs and can be created/edited by admins and organisers within their respective contexts

Non-Functional Requirements

Overview

This section outlines the non-functional requirements for Conference Expo Portal v2.0. These requirements ensure the platform is robust, secure, scalable, and maintainable, and that it meets all relevant compliance obligations.

Performance Requirements

• The system must provide a response time of less than 500ms for 95% of API requests under normal load.
• The portal must support at least 200 concurrent users without significant degradation in performance.
• File uploads and downloads should complete within acceptable timeframes for files up to 1 GB.
• The dashboard and reporting features should load within 2 seconds for typical event sizes (up to 75 sponsors).

Scalability

• The platform must support scaling to accommodate growth in user numbers, events, and data volume.
• Infrastructure should allow for horizontal scaling of application and database layers.
• The system should support the addition of new features and integrations with minimal disruption.
• Caching strategies should be used to optimise performance for frequently accessed data.

Security

• All data in transit must be encrypted using TLS 1.2 or higher.
• Sensitive data at rest (e.g. passwords, payment tokens) must be encrypted or securely hashed.
• The system must implement role-based access control for all user actions.
• Regular security audits and vulnerability assessments must be conducted.
• The platform must protect against common web vulnerabilities (OWASP Top 10).
• Audit logs must be maintained for all critical actions and access to sensitive data.
• Static analysis tools must be used to detect security vulnerabilities in the codebase.

Reliability

• The system must achieve 99.9% uptime, excluding planned maintenance.
• Automated monitoring and alerting must be in place for all critical services.
• The platform must support automated daily backups of all critical data.
• Disaster recovery procedures must be documented and tested at least annually.
• The system must degrade gracefully in the event of partial outages.

Maintainability

• The codebase must follow established coding standards and be well documented.
• Automated tests must cover all critical business logic and integrations.
• The system must support zero-downtime deployments for routine updates.
• Configuration should be managed via environment variables and not hard-coded.
• The platform must provide clear error messages and logging for troubleshooting.
• Static analysis tools must be used to enforce code quality and detect vulnerabilities.

Compliance

• The platform must comply with UK GDPR and other relevant data protection regulations.
• Data retention and deletion policies must be implemented in line with legal requirements.
• The system must support user requests for data export and deletion.
• All third-party integrations must meet relevant compliance standards (e.g. PCI DSS for payments).

Accessibility

• The platform must comply with WCAG 2.1 AA accessibility standards.
• All interactive elements must be operable via keyboard navigation.
• The system must support screen readers and provide appropriate ARIA labels.
• Sufficient colour contrast must be maintained for all text and interface elements.
• All images and icons must have meaningful alternative text.
• Forms must be accessible, with clear labels, instructions, and error messages.
• Focus indicators must be visible for all interactive elements.
• Accessibility must be considered in all new features and updates.

Implementation Strategy

Overview

This section describes the approach for delivering Conference Expo Portal v2.0, including development methodology, testing, deployment, and quality assurance. The strategy is designed to ensure a robust, maintainable, and timely delivery of the platform.

Development Methodology

• The project will use a continuous delivery approach, with feature branches merged into main when ready.
• Weekly calls will be held with Nimlok to review progress, gather feedback, and keep the project on track.
• Features will be deployed to a development environment for review throughout the project.

Testing Strategy

• The API will be covered by unit and integration tests.
• The front-end will use Vitest for unit and integration tests, and Playwright (with Nuxt Test Utils) for end-to-end testing.
• Accessibility testing will be performed using axe-core.
• Manual QA and user acceptance testing will be conducted in the development environment.

Deployment Pipeline

• GitLab CI will be used for continuous integration, with DeployHQ handling deployments via webhooks.
• Rollbacks are supported via DeployHQ.
• Environments (development, staging, production) are described in the Architecture.

Continuous Integration/Delivery

• Code is deployed when feature branches are merged into main and all tests pass.
• Code review and approval are required before merging.
• Automated code quality checks and security scans are enforced.

Quality Assurance

• Acceptance criteria will be defined for each feature or milestone.
• Sentry will be used for error tracking.
• Bugs and issues will be tracked using ClickUp (with Nimlok access).
• Stakeholder feedback will be gathered during weekly calls and incorporated into the backlog.

Code Quality & Static Analysis

• ESLint and Prettier will be used for API code style and formatting.
• TypeScript will be used for type safety in both backend and frontend.
• ESLint will be used for frontend static analysis.
• Automated type checking in CI/CD pipeline.

Planning and Delivery

Overview

This section outlines a proposed timeline and approach for delivering Conference Expo Portal v2.0. The plan is indicative only and will be finalised after the specification phase is complete. All durations are given in weeks, as the actual start date is to be confirmed. The overall process is expected to take 4–6 months, including specification, development, testing, and rollout.

Proposed Timeline (Example)

Phase	Activities	Duration (weeks)
Specification	Finalise requirements, technical design, UI/UX, planning	4
Development: Core	Build core features (user management, events, stands, artwork)	8
Development: Extras	Integrations, reporting, admin tools, polish	4
Testing & QA	Automated/manual testing, bug fixing, UAT	4
Rollout & Training	Production setup, migration, training, go-live support	2
Total		18–26

• Some phases may overlap (e.g. testing can begin before all development is complete).
• Weekly review calls will be held to monitor progress and adjust plans as needed.
• The timeline will be updated and finalised after the specification phase.

Milestones

• Requirements and specification sign-off
• Core feature completion
• Integrations and reporting complete
• User acceptance testing (UAT) complete
• Production go-live

Resource Requirements

• Backend developer
• Frontend developer
• Project management and QA responsibilities will be shared between the development team
• Stakeholder representatives (for feedback and UAT)

Risk Assessment

• Timeline is indicative and may change based on requirements or feedback
• Resource availability and external dependencies may impact delivery
• Early and regular feedback will help mitigate risks

Success Metrics

• On-time delivery of agreed features
• User acceptance and positive feedback
• System stability and performance targets met
• Smooth rollout and adoption

Budget Estimate

The proposed budget for the delivery of Conference Expo Portal v2.0 is £30,000 (excluding VAT and third-party costs). This is based on:

• A two-person team (backend and frontend developer)
• A total of approximately 416 hours at a blended rate of £72 per hour

The allocation of effort will vary throughout the project, with more focus on backend/API development in the early phases, increased frontend integration later, and periods of reduced activity during client acceptance testing or feedback cycles. The budget is expected to be sufficient for the delivery of the agreed scope, given the team's prior experience with the v1 portal and established domain knowledge. The budget will be reviewed and adjusted if the scope changes significantly during the specification phase.

---

This plan is a starting point and will be refined as the project progresses.

Project Schedule

Overview

This schedule outlines the proposed timeline for delivering Conference Expo Portal v2.0. All dates are provisional and subject to refinement during project planning and execution. Development commences on Monday, 3 November 2025, with a scheduled break for the holiday period (22 December 2025 - 5 January 2026).

Key Milestones

Specification Phase

• Specification completion: 31 October 2025
• Client review and feedback: 31 October - 31 October 2025
• Final specification sign-off: 31 October 2025

Development Phase

• Project kickoff: 3 November 2025
• Holiday break: 22 December 2025 - 5 January 2026 (no work)
• Backend development complete: 6 February 2026
• Frontend development complete: 6 March 2026
• System integration complete: 13 March 2026

Launch Phase

• User acceptance testing: 16-18 March 2026
• Production deployment: 19 March 2026
• Go-live: 20 March 2026

Detailed Timeline

Phase 1: Backend Development

3 November 2025 - 6 February 2026 (14 working weeks, excluding 22 Dec - 5 Jan)

This phase focuses on establishing the core system architecture and business logic:

• Weeks 1-2 (3-17 Nov): Environment setup and database design
• Weeks 3-6 (18 Nov-15 Dec): Core API development and user management
• Week 7 (16-21 Dec): Event and stand configuration systems (partial week)
• Holiday break: 22 December 2025 - 5 January 2026 (no work)
• Weeks 8-11 (6 Jan-2 Feb): Event and stand configuration systems (continued)
• Weeks 12-14 (3-6 Feb): Artwork workflow, payment integration, testing, and documentation

Phase 2: Frontend Development

9 February 2026 - 6 March 2026 (4 weeks)

Development of the user interface and client-side functionality:

• Week 1 (9-16 Feb): Project setup, design system, and core components
• Week 2 (17-23 Feb): User interface implementation
• Week 3 (24 Feb-2 Mar): Integration with backend APIs
• Week 4 (3-6 Mar): Testing, optimisation, and polish

Phase 3: Integration and Testing

9 March 2026 - 13 March 2026 (1 week)

System integration and comprehensive testing:

• Days 1-3 (9-11 Mar): End-to-end testing and critical bug fixes
• Days 4-5 (12-13 Mar): Performance optimisation and security review

Phase 4: Launch

16 March 2026 - 20 March 2026 (1 week)

Final preparation and deployment:

• Days 1-3 (16-18 Mar): User acceptance testing and final adjustments
• Days 4-5 (19-20 Mar): Production deployment and go-live

Risk Considerations

Timeline Buffers

The development timeline accounts for the holiday break whilst maintaining project momentum:

• Holiday break (22 Dec - 5 Jan) explicitly excluded from working time
• Backend development adjusted to 14 working weeks
• Limited buffer time in development phases requiring disciplined execution
• Critical path management essential due to compressed timeline
• Early risk identification and mitigation crucial for success

Critical Dependencies

Several factors could impact the proposed timeline:

• Specification approval: Delays in sign-off (due 31 October) will push all subsequent phases
• Holiday period: No work scheduled between 22 December 2025 and 5 January 2026
• Third-party integrations: Stripe and Nimlogix API development
• Infrastructure setup: DigitalOcean service provisioning and configuration
• Work resumption: Smooth restart of work on 6 January 2026
• Tight timeline: Limited buffer time requires disciplined execution and early risk identification

Milestone Flexibility

The launch date is now scheduled for 20 March 2026, accounting for the later start and holiday break:

• Backend development comprises 14 working weeks (excluding holiday break)
• Frontend development maintains 4 weeks requiring parallel work where possible
• Integration phase comprises 1 week - critical issues must be identified early
• Launch phase maintains 3 days of user acceptance testing
• Risk: Any significant delays in backend completion could impact the entire schedule
• Holiday impact: 2-week break requires good handover documentation before 22 December

Resource Allocation

Development Team

The timeline assumes a core development team comprising:

• Senior full-stack developer (lead)
• Frontend specialist
• Part-time DevOps/infrastructure support

Client Involvement

Key client engagement points are built into the schedule:

• Weekly check-ins during active development phases
• Milestone reviews at the end of each major phase
• User acceptance testing participation in the final week
• Go-live support during launch week

Success Metrics

Progress will be measured against:

• Feature completion: Delivery of all specified functionality
• Quality gates: Passing automated tests and code review
• Performance benchmarks: Meeting non-functional requirements
• User acceptance: Successful completion of acceptance testing
• Launch readiness: Production environment stability and monitoring

Next Steps

Following specification sign-off on 31 October 2025, the immediate priorities are:

1. Finalise resource allocation and team assignments
2. Set up development and staging environments
3. Establish project management and communication protocols
4. Begin Phase 1 backend development on 3 November 2025

This proposed schedule starts development on 3 November 2025 and accounts for a two-week holiday break (22 December 2025 - 5 January 2026), targeting a go-live date of 20 March 2026. The timeline is achievable with disciplined execution, requiring careful coordination between phases and early identification of potential risks. Good documentation before the holiday break will be essential to ensure smooth work resumption in January.

Appendices

API Documentation

Overview

The Conference Expo Portal API provides a secure, RESTful interface for integrating with the platform. It enables external systems and partners to manage events, stands, sponsors, users, artwork, and related resources. All access is authenticated and authorised using OAuth 2.0.

• Base URL: https://portal.conferenceexpo.com/api/v1

For detailed API design requirements and specifications, see API Design. For authentication details, see the section below.

Authentication

The API uses OAuth 2.0 Client Credentials flow. All requests must include a valid Bearer token in the Authorization header.

Token Endpoint:

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=...&client_secret=...

Token Response Example:

{
    "access_token": "string",
    "token_type": "Bearer",
    "expires_in": 3600
}

Authenticated Request Example:

GET /api/v1/events
Authorization: Bearer <access_token>

Request & Response Structure

• All requests and responses use JSON.
• List endpoints support pagination via page and per_page query parameters.
• Standard HTTP status codes are used.
• Error responses:

{
    "error": {
        "code": "string",
        "message": "string"
    }
}

Pagination Example:

{
    "data": [ ... ],
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 5,
        "per_page": 20,
        "to": 20,
        "total": 100
    },
    "links": {
        "first": "...",
        "last": "...",
        "prev": null,
        "next": "..."
    }
}

Endpoints

Note: The following is a representative list of core endpoints. It is not exhaustive. A complete, up-to-date API specification will be provided in Swagger (OpenAPI) format for full reference and integration details.

Events

• GET /events — List events
• POST /events — Create event
• GET /events/{id} — Get event details
• PUT /events/{id} — Update event
• DELETE /events/{id} — Archive event

Users

• GET /users — List users
• POST /users — Create user
• GET /users/{id} — Get user details
• PUT /users/{id} — Update user
• DELETE /users/{id} — Deactivate user

Stands

• GET /stands — List stands
• POST /stands — Create stand
• GET /stands/{id} — Get stand details
• PUT /stands/{id} — Update stand
• DELETE /stands/{id} — Remove stand

Packages

• GET /packages — List packages (includes filters for active/available)
• POST /packages — Create package (external system only)
• GET /packages/{id} — Get package details with categories and options
• PUT /packages/{id} — Update package (external system only)
• DELETE /packages/{id} — Archive package (external system only)
• GET /packages/{id}/versions — List package version history

Stand Configurations

• GET /stand-configurations — List configurations
• POST /stand-configurations — Create configuration
• GET /stand-configurations/{id} — Get configuration details with selections
• PUT /stand-configurations/{id} — Update configuration (draft only)
• POST /stand-configurations/{id}/submit — Submit configuration for review
• POST /stand-configurations/{id}/approve — Approve configuration (organisers only)
• POST /stand-configurations/{id}/request-changes — Request changes (organisers only)
• DELETE /stand-configurations/{id} — Remove configuration

Package Allocation

• GET /stands/{standId}/package-allocation — Get stand package allocation settings
• PUT /stands/{standId}/package-allocation — Set package selection permission and pre-allocate package
• DELETE /stands/{standId}/package-allocation — Remove package allocation

Configuration Categories

• GET /packages/{packageId}/categories — List categories for a package
• GET /categories/{id} — Get category details with options

Configuration Options

• GET /packages/{packageId}/options — List all options for a package
• GET /categories/{categoryId}/options — List options for a category
• GET /options/{id} — Get option details

Configuration Selections

• GET /stand-configurations/{configId}/selections — List selections for a configuration
• POST /stand-configurations/{configId}/selections — Add selection to configuration
• PUT /stand-configurations/{configId}/selections/{id} — Update selection quantity
• DELETE /stand-configurations/{configId}/selections/{id} — Remove selection

Artworks

• GET /artworks — List artworks
• POST /artworks — Upload artwork
• GET /artworks/{id} — Get artwork details
• PUT /artworks/{id} — Update artwork
• DELETE /artworks/{id} — Remove artwork

User Permissions

• GET /user-permissions — List permissions
• POST /user-permissions — Grant permission
• GET /user-permissions/{id} — Get permission details
• PUT /user-permissions/{id} — Update permission
• DELETE /user-permissions/{id} — Revoke permission

Files

• POST /files — Upload file
• GET /files/{id} — Get file metadata
• DELETE /files/{id} — Delete file

Webhooks

Webhooks are used to notify external systems of key events:

• package_created — New package added to system
• package_updated — Package data modified
• stand_configured — Stand configuration submitted
• configuration_approved — Configuration approved by organiser
• artwork_uploaded — Artwork file uploaded
• proof_approved — Proof approved by sponsor/organiser
• proof_rejected — Proof rejected with feedback
• payment_received — Payment completed

Webhook Payload Example:

{
    "event": "stand_configured",
    "timestamp": "2025-10-23T14:30:00Z",
    "data": {
        "configuration_id": "uuid",
        "stand_id": "uuid",
        "package_id": "uuid",
        "package_version": 1,
        "total_price": 2500.00,
        "status": "submitted"
    }
}

Best Practices

• Use HTTPS for all requests
• Handle error responses and rate limits
• Store credentials securely
• Rotate client secrets regularly

Database Schema

This appendix documents the database schema for the Conference Expo Portal v2.0. The schema is designed to support all core features while maintaining data integrity and performance.

Common Fields

All entities include these base fields:

Field	Type	Description
id	uuid	Primary key (UUID v7)
created_at	timestamp	Record creation timestamp
updated_at	timestamp	Last update timestamp
deleted_at	timestamp	Soft delete timestamp (nullable)

Core Entities

Event

Represents a conference or exhibition event.

Field	Type	Description	Constraints
name	string	Event name	Required, Unique per organiser
description	text	Event description	Required
organiser_id	uuid	Foreign key to Organiser	Required, Foreign Key
venue_id	uuid	Foreign key to Venue	Required, Foreign Key
status	enum	Event status	draft, published, archived
timezone	string	Event timezone	Required, IANA timezone
started_at	timestamp	Event start date/time	Required
ended_at	timestamp	Event end date/time	Required, After started_at
cut_off_at	timestamp	Stand configuration deadline	Required, Before started_at
artwork_required_at	timestamp	Artwork submission deadline	Required, Before started_at

Relationships:

• belongs_to: Organiser
• belongs_to: Venue
• has_many: Stands

User

Represents system users (admins, organisers, sponsors).

Field	Type	Description	Constraints
first_name	string	User's first name	Required
last_name	string	User's last name	Required
email	string	Email address	Required, Unique, Valid email
phone_number	string	Contact phone number	Optional, Valid phone format
password	string	Hashed password	Required, Secure hash
is_admin	boolean	Admin status flag	Default: false
status	enum	User status	active, inactive, suspended
last_login_at	timestamp	Last login timestamp	Nullable

Relationships:

• has_many: UserPermissions
• has_many: Notifications

Stand

Represents a physical stand at an event.

Field	Type	Description	Constraints
number	string	Stand reference number	Required, Unique per event
event_id	uuid	Foreign key to Event	Required, Foreign Key
sponsor_id	uuid	Foreign key to Sponsor	Required, Foreign Key
status	enum	Stand status	assigned, configured, approved, completed
notes	text	Additional information	Optional

Relationships:

• belongs_to: Event
• belongs_to: Sponsor
• has_many: StandConfigurations
• has_many: Artworks

Package

Represents a stand package configuration provided by external system.

Field	Type	Description	Constraints
name	string	Package name	Required
description	text	Package description	Required
kit_id	string	External system kit ID	Required
kit_code	string	External system kit code	Required
base_price	decimal	Package base price	Required, >= 0
unit_cost	decimal	Package cost (internal)	Required, >= 0
status	enum	Package status	active, inactive, archived
version	integer	Package version	Required, Auto-increment
effective_date	timestamp	Version effective date	Required

Relationships:

• has_many: StandConfigurations
• has_many: ConfigurationCategories
• has_many: PackageVersions

Package Version

Tracks historical versions of package data.

Field	Type	Description	Constraints
package_id	uuid	Foreign key to Package	Required, Foreign Key
version_number	integer	Version number	Required
effective_date	timestamp	When version became active	Required
data_snapshot	jsonb	Complete package data	Required

Relationships:

• belongs_to: Package

Stand Configuration

Represents a sponsor's configuration for a specific stand.

Field	Type	Description	Constraints
stand_id	uuid	Foreign key to Stand	Required, Foreign Key
package_id	uuid	Foreign key to Package	Required, Foreign Key
package_version	integer	Package version used	Required
package_selection_permission	boolean	Can sponsor select package	Default: true
allocated_by	uuid	Foreign key to User (if pre-allocated)	Nullable, Foreign Key
allocation_timestamp	timestamp	When package was allocated	Nullable
status	enum	Configuration status	draft, submitted, approved, changes_requested
submission_timestamp	timestamp	When submitted for review	Nullable
approval_timestamp	timestamp	When approved	Nullable
approved_by	uuid	Foreign key to User (approver)	Nullable, Foreign Key
total_price	decimal	Total configuration price	Required, >= 0

Relationships:

• belongs_to: Stand
• belongs_to: Package
• belongs_to: User (allocator)
• belongs_to: User (approver)
• has_many: StandConfigurationSelections
• has_many: Artworks

Configuration Category

Categories for grouping configuration options, provided by external system.

Field	Type	Description	Constraints
package_id	uuid	Foreign key to Package	Required, Foreign Key
name	string	Category name	Required
description	text	Category description	Optional
external_group_id	string	External system group ID	Optional
position	integer	Display order	Required
selection_mode	enum	Selection mode	single, multiple

Relationships:

• belongs_to: Package
• has_many: ConfigurationOptions

Configuration Option

Individual items/options that can be configured for a stand, provided by external system.

Field	Type	Description	Constraints
package_id	uuid	Foreign key to Package	Required, Foreign Key
category_id	uuid	Foreign key to Category	Nullable, Foreign Key
name	string	Option name	Required
description	text	Option description	Optional
bolt_on_id	string	External system bolt-on ID	Optional
item_code	string	External system item code	Optional
artwork_code	string	Artwork specification code	Optional
min_quantity	integer	Minimum quantity	Required, >= 0
included_quantity	integer	Quantity included in package	Required, >= min_quantity
max_quantity	integer	Maximum quantity	Required, >= included_quantity
unit_price	decimal	Price per unit (customer-facing)	Required, >= 0
unit_cost	decimal	Cost per unit (internal)	Required, >= 0
size_modifiers	jsonb	External system metadata	Optional
position	integer	Display order	Required
is_default_selected	boolean	Default selection indicator	Default: false

Relationships:

• belongs_to: Package
• belongs_to: ConfigurationCategory
• has_many: ConfigurationSelections

Configuration Selection

Records sponsor's selected options and quantities for a configuration.

Field	Type	Description	Constraints
stand_configuration_id	uuid	Foreign key to Configuration	Required, Foreign Key
option_id	uuid	Foreign key to Option	Required, Foreign Key
quantity	integer	Selected quantity	Required, >= 0
unit_price_at_selection	decimal	Unit price when selected	Required, >= 0
additional_charge	decimal	Charge above included qty	Required, >= 0
selected_at	timestamp	Selection timestamp	Required

Relationships:

• belongs_to: StandConfiguration
• belongs_to: ConfigurationOption

Artwork

Artwork required for stand configurations.

Field	Type	Description	Constraints
stand_configuration_id	uuid	Foreign key to Configuration	Required, Foreign Key
specification_file_id	uuid	Artwork specification file	Required, Foreign Key
artwork_file_id	uuid	Uploaded artwork file	Required, Foreign Key
status	enum	Artwork status	pending, approved, rejected
approved_at	timestamp	Approval timestamp	Nullable
approved_by	uuid	Foreign key to User	Nullable, Foreign Key
rejection_reason	text	Rejection reason	Nullable

Relationships:

• belongs_to: StandConfiguration
• belongs_to: User (approver)

User Permission

Manages user access to different entities.

Field	Type	Description	Constraints
user_id	uuid	Foreign key to User	Required, Foreign Key
entity_type	enum	Entity type	organiser, sponsor, stand
entity_id	uuid	Entity ID	Required
scope	enum	Permission scope	read, write, admin
role	enum	User role	primary_contact, contact, viewer
granted_at	timestamp	Grant timestamp	Required
granted_by	uuid	Foreign key to User	Required, Foreign Key

Relationships:

• belongs_to: User (permission holder)
• belongs_to: User (granter)

Indexes

Performance Indexes

• events(organiser_id, status)
• stands(event_id, status)
• packages(kit_id, status)
• packages(status, effective_date)
• stand_configurations(stand_id, status)
• stand_configurations(package_id, package_version)
• configuration_options(package_id, category_id)
• configuration_selections(stand_configuration_id, option_id)
• artworks(stand_configuration_id, status)
• user_permissions(user_id, entity_type, entity_id)

Unique Constraints

• events(organiser_id, name)
• stands(event_id, number)
• users(email)
• package_versions(package_id, version_number)

Data Integrity

Foreign Key Constraints

• All foreign keys are indexed
• Cascading deletes are disabled
• Soft deletes are used where appropriate

Validation Rules

• Email addresses must be valid
• Phone numbers must be in E.164 format
• Timestamps must be in UTC
• Prices must be non-negative
• Quantities must be within min/max bounds

Data Retention

Archiving Rules

• Events are archived after completion
• Stand configurations are retained for 7 years
• Artwork files are retained for 7 years
• User data is retained while active
• Audit logs are retained for 7 years

For detailed technical specifications, see the Architecture. For database schema details, refer to the Database Schema.

UI/UX Specification

This document outlines the key UI/UX requirements and considerations for the Conference Expo Portal v2.0. Detailed wireframes and visual designs will be developed during the design phase if the proposal is approved.

User Interface Requirements

Progress and Status Indicators

Long-Running Operations

• File uploads require progress indication
• Artwork processing needs status updates
• Stand configuration generation should show progress
• All long-running operations must provide:
  • Clear progress indication
  • Error handling
  • Recovery options
  • Status updates

Workflow Status

• Submission status tracking
• Approval workflow progress
• Clear indication of current stage
• Visibility of next steps
• Blocking issues highlighted

Form Requirements

File Upload

• Support for drag and drop
• File validation
• Size restrictions
• Preview capabilities
• Multiple file handling
• Batch processing

Stand Configuration

• Interactive form elements
• Real-time validation
• Auto-save
• Draft management
• Change tracking
• Comparison views

Navigation Requirements

Dashboard

• Role-specific navigation
• Quick actions
• Status overview
• Activity tracking
• Notifications
• Search functionality

Mobile Experience

• Responsive navigation
• Touch-friendly interface
• Gesture support
• Efficient mobile workflows
• Offline capabilities
• Back navigation

Communication Requirements

Messaging

• Real-time updates
• File sharing
• Message threading
• User presence
• Read receipts
• Typing indicators

Notifications

• In-app notifications
• Email notifications
• Priority levels
• Actionable notifications
• Notification preferences
• Dismissal options

Error Handling Requirements

Form Validation

• Inline validation
• Field-level validation
• Form-level validation
• Error summaries
• Recovery guidance
• Contextual help

System Errors

• User-friendly messages
• Technical details available
• Recovery options
• Support access
• Error reporting
• Retry mechanisms

Loading States

Page Transitions

• Loading indicators
• Progress feedback
• Placeholder content
• Error handling
• State management
• Transition handling

Data Loading

• Pagination
• Infinite scroll
• Loading states
• Empty states
• Error states
• Retry options

Accessibility Requirements

Screen Reader Support

• ARIA implementation
• Focus management
• Navigation structure
• Content hierarchy
• Alternative text
• Keyboard support

Visual Accessibility

• High contrast support
• Font size control
• Colour blind consideration
• Focus visibility
• Motion control
• Text spacing

Responsive Requirements

Breakpoints

• Mobile support (320px+)
• Tablet support (481px+)
• Desktop support (769px+)
• Large screen support (1025px+)
• Responsive layouts
• Content adaptation

Touch Support

• Touch targets
• Gesture support
• Swipe actions
• Zoom capabilities
• Touch feedback
• Long press actions

Implementation Notes

This specification will be used to:

1. Guide the design phase upon approval
2. Inform the development of wireframes and visual designs
3. Ensure consistent implementation across the application
4. Maintain accessibility and usability standards

The actual visual design, including:

• Colour schemes
• Typography
• Component styling
• Layout specifics
• Visual hierarchy
• Brand implementation

Will be developed during the design phase, following Nimlok's brand guidelines and design system.

Changelog

All notable changes to the Conference Expo Portal v2.0 Specification will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[1.2.0] - 2025-11-13

Added

• Print-site plugin integration allowing full specification to be printed as a single document via browser print dialog
• Footer link to print page for easy access to printable specification version

[1.1.0] - 2025-11-06

Added

• FR-014 to FAQs specification: Search bar requirement allowing users to search FAQs by entering string queries that match against question text and answer content
• FR-036 to User Management specification: Downloadable CSV template with correct column headers and example data for bulk user import operations

Changed

• Updated project schedule: Adjusted development start date to 3 November 2025, explicitly scheduled holiday break (22 December 2025 - 5 January 2026), and revised go-live date to 20 March 2026

[1.0.0] - 2025-10-23

Changed

• Replaced Laravel with NestJS in architecture specification
• Updated functional requirements with final specifications across all domains

Added

• System administration specification
• Communication systems specification
• Frequently asked questions specification
• Versioning system with changelog
• Document status tracking

[0.5.0] - 2025-10-09

Added

• Event management system specification with comprehensive workflows
• User management system specification with hierarchical account creation
• User authentication system specification with prioritised requirements
• Stand configuration specification
• Artwork management specification
• Payments system specification
• Additional fees specification
• API specification framework with clear priority distinctions

Changed

• Clarified authentication priorities across API and auth system specifications

[0.4.0] - 2025-10-01

Added

• Project structure guide for Laravel + Nuxt implementation
• Constitution v1.0.0 for specification project
• OAuth 2.0/Passport authentication details in architecture

Changed

• Clarified authentication specification to resolve 5 critical ambiguities

[0.3.0] - 2025-09-18

Added

• Schedule page with project timeline and milestones

Changed

• Aligned schedule dates with weekdays for accuracy

[0.2.0] - 2025-06-03

Added

• Logo and branding assets

Changed

• Renamed executive summary section for clarity
• Updated document structure and navigation
• Renamed Nimlok API references for consistency

Fixed

• Fixed spacing and formatting issues throughout documentation

[0.1.0] - 2025-05-16

Added

• Initial specification structure and framework
• README with project overview
• Core documentation sections and navigation
• MkDocs configuration with Material theme

Version History Summary

• v1.2.0 - Print-friendly specification export capability
• v1.1.0 - Enhanced search capabilities and bulk import usability improvements
• v1.0.0 - Complete specification with all functional requirements and finalized architecture
• v0.5.0 - Core system specifications and workflow framework
• v0.4.0 - Architecture details and project constitution
• v0.3.0 - Project timeline and schedule
• v0.2.0 - Branding and structure refinements
• v0.1.0 - Initial documentation framework