Architecture overview

​

System overview

​

Core components

​

Application layer

• Python 3.13 runtime environment
• Flask application factory pattern for flexible initialization
• Three blueprint architecture for request handling:
  • main_blueprint - Primary application routes
  • json_updates_blueprint - AJAX endpoints for real-time updates
  • status_blueprint - Health check and status endpoints
  • no_cookie_blueprint - Cookie-free routes for embedded content

• Custom NotifyAdminSessionInterface for secure session handling
• 20-hour permanent session lifetime for standard users
• 30-minute inactive timeout for platform administrators
• Redis-backed session storage with configurable TTL
• Session refresh disabled by default except for specific endpoints

• Flask-Login for user session management
• Multi-factor authentication with three methods:
  • Email 2FA (30-minute code expiry)
  • SMS 2FA via user mobile number
  • WebAuthn support for hardware keys and biometrics
• Custom AnonymousUser class for unauthenticated contexts
• Permission-based access control with decorators:
  • @user_has_permissions() - Checks user service permissions
  • @user_is_platform_admin - Restricts to platform administrators
  • @service_has_permission() - Validates service capabilities

​

Data layer

• service_api_client - Service CRUD and configuration
• user_api_client - User management and authentication
• template_folder_api_client - Template organization
• notification_api_client - Notification sending and tracking
• job_api_client - Batch job management
• billing_api_client - Usage tracking and cost calculation
• organisations_client - Organization management
• invite_api_client - User invitation workflow
• api_key_api_client - API key generation and management
• template_statistics_client - Analytics and reporting
• events_api_client - Audit logging

• Bearer token authentication via ADMIN_CLIENT_SECRET
• Automatic retry logic for transient failures
• Request/response logging for debugging
• Error handling with HTTPError exceptions

• Session storage with automatic expiry
• Search query caching (7-day TTL for notification searches)
• Memo resetters for cache invalidation
• Optional Redis usage controlled by REDIS_ENABLED flag
• Local development fallback when Redis unavailable

​

Storage layer

• S3_BUCKET_CSV_UPLOAD - Batch upload CSV files with metadata
• S3_BUCKET_CONTACT_LIST_UPLOAD - Reusable contact lists
• S3_BUCKET_LOGO_UPLOAD - Email and letter branding logos
• S3_BUCKET_TRANSIENT_UPLOADED_LETTERS - Temporary letter PDFs
• S3_BUCKET_PRECOMPILED_ORIGINALS_BACKUP_LETTERS - Letter backups
• S3_BUCKET_LETTER_ATTACHMENTS - Letter attachment files
• S3_BUCKET_TEMPLATE_EMAIL_FILES - Email template attachments
• S3_BUCKET_REPORT_REQUESTS_DOWNLOAD - Generated CSV reports
• S3_BUCKET_MOU - Memorandum of Understanding documents

• Logo files served via LOGO_CDN_DOMAIN for performance
• Static assets served from ASSET_DOMAIN with fingerprinting
• DNS prefetch and preconnect headers for optimized loading

​

External integrations

• TEMPLATE_PREVIEW_API_HOST - Renders email and letter previews
• Generates PNG previews for letters
• PDF page counting for postage calculation
• Real-time template rendering with test data

• ANTIVIRUS_API_HOST - Scans uploaded files for malware
• Validates CSV uploads and letter PDFs
• Blocks malicious content before processing
• Optional in development, required in production

• ZENDESK_API_KEY - Support ticket creation
• Feedback form submission to Zendesk
• Automatic ticket categorization with subject prefixes

​

Request lifecycle

@main.route("/services/<uuid:service_id>")
@user_has_permissions()
def service_dashboard(service_id):
    # Route handler

g.current_service  # Service from URL parameter or session
g.current_organisation  # Organization from URL parameter
g.user_id  # Authenticated user ID
g.start  # Request start time for metrics

@user_has_permissions('send_messages', 'manage_templates')
def send_notification(service_id):
    # User must have send_messages OR manage_templates

def service_dashboard(service_id):
    return render_template(
        'views/dashboard/dashboard.html',
        updates_url=url_for('json_updates.service_dashboard_updates'),
        partials=get_dashboard_partials_lazy()
    )

​

Security architecture

​

Transport security

• HTTPS enforced in production via HTTP_PROTOCOL and SESSION_COOKIE_SECURE
• HSTS headers with includeSubDomains and preload directives
• TLS certificate validation for API calls

​

Application security

• Flask-WTF CSRF tokens on all forms
• Automatic validation on POST requests
• No time limit on CSRF tokens (WTF_CSRF_TIME_LIMIT = None)
• Session-tied tokens prevent reuse across sessions

Content-Security-Policy:
  default-src 'self' {asset_domain} 'unsafe-inline';
  script-src 'self' {asset_domain} 'nonce-{csp_nonce}';
  connect-src 'self' {asset_domain};
  object-src 'self';
  font-src 'self' {asset_domain} data:;
  img-src 'self' {asset_domain} *.notifications.service.gov.uk {logo_domain} data:;
  frame-ancestors 'self';

request.csp_nonce = secrets.token_urlsafe(16)

• WTForms for declarative form validation
• Email address format validation
• UK phone number validation with international support
• Postal address validation for letters
• File upload validation (size, type, content)
• CSV structure validation with error reporting

​

Session security

• Secure cookie flags (httponly, secure, samesite=Lax)
• Session data stored server-side in Redis
• Session IDs never exposed in URLs
• Automatic session expiry based on inactivity
• Platform admin sessions expire faster (30 minutes)

​

File upload security

• Antivirus scanning before processing
• File type validation (CSV, PDF, PNG, JPG)
• File size limits enforced
• S3 bucket access restricted via IAM
• Temporary file cleanup after processing

​

Performance optimizations

​

Frontend performance

• Asset fingerprinting for cache busting
• CDN delivery for static files and logos
• Rollup for JavaScript bundling
• CSS and JavaScript minification
• Font subsetting with WOFF2 compression
• DNS prefetch and preconnect for external resources

• Server-side rendering for initial page load
• AJAX updates for dynamic content (dashboard statistics, notification lists)
• Lazy loading for dashboard partials
• JSON update endpoints for polling:
  @json_updates.route("/services/<uuid:service_id>/dashboard.json")
  def service_dashboard_updates(service_id):
      return jsonify(**get_dashboard_partials())
  

​

Backend performance

• Redis caching for search queries (7-day TTL)
• Memoization for expensive computations
• Service and organization data cached in g object per request
• Asset fingerprint caching across requests

• Pagination for large result sets (50 notifications per page)
• Lazy loading of related objects
• Efficient filtering at API level
• Aggregated statistics instead of individual queries

• Eventlet for async I/O in production
• Parallel API calls where possible
• Background job processing for batch operations
• Non-blocking file uploads to S3

​

Deployment architecture

​

Environment configuration

class Development(Config):
    DEBUG = True
    SESSION_COOKIE_SECURE = False
    ANTIVIRUS_ENABLED = False
    REDIS_ENABLED = False

class Sandbox(CloudFoundryConfig):
    HTTP_PROTOCOL = "https"
    HEADER_COLOUR = "#F499BE"  # Pink header for visual distinction

class Config:
    DEBUG = False
    SESSION_COOKIE_SECURE = True
    ANTIVIRUS_ENABLED = True
    REDIS_ENABLED = True

​

Logging and monitoring

• GDS Metrics integration for performance tracking
• Request start time recording via g.start
• Error logging with structured context
• API call logging with URL and status code

• 400 - Client errors logged as exceptions
• 401/403 - Authentication/authorization failures
• 404 - Not found with service-specific templates
• 410 - Gone resources
• 500 - Internal errors with stack traces in debug mode
• 504 - Eventlet timeout handling
• HTTPError - API client errors with response details
• CSRFError - CSRF validation failures with session checks

• Status blueprint for uptime monitoring
• Unauthenticated, unstyled, no-cookie status page
• Integration with platform health checks

​

Data models

class Service(JSONModel):
    id: UUID
    name: str
    active: bool
    trial_mode: bool  # Alias for 'restricted'
    permissions: List[str]  # email, sms, letter, etc.
    message_limit: int
    rate_limit: int
    organisation: Organisation
    email_branding: EmailBranding
    letter_branding: LetterBranding

class User(JSONModel):
    id: UUID
    email_address: str
    mobile_number: str
    auth_type: str  # email_auth, sms_auth, webauthn_auth
    permissions: Dict[str, List[str]]  # Service ID -> permissions
    platform_admin: bool
    organisations: List[Organisation]
    services: List[Service]

class Notification(JSONModel):
    id: UUID
    template_id: UUID
    template_version: int
    created_at: datetime
    status: str  # sending, delivered, failed, etc.
    notification_type: str  # email, sms, letter
    recipient: str  # Redacted in UI
    personalisation: Dict[str, str]

​

Development workflow

​

Local setup

# Install dependencies
make bootstrap

# Run development server
make run-flask  # Starts on localhost:6012

# Watch frontend assets
make watch-frontend

# Run tests
make test
npx jest  # JavaScript tests

​

Project structure

app/
├── __init__.py          # Application factory
├── config.py            # Environment configurations
├── main/                # Main blueprint
│   ├── views/           # Route handlers
│   │   ├── dashboard.py
│   │   ├── templates.py
│   │   ├── send.py
│   │   └── ...
│   ├── forms.py         # WTForms definitions
│   └── validators.py    # Custom validators
├── models/              # Domain models
│   ├── service.py
│   ├── user.py
│   ├── organisation.py
│   └── ...
├── notify_client/       # API clients
├── templates/           # Jinja2 templates
├── static/              # CSS, JS, images
└── navigation.py        # Navigation menus

​

Next steps