BR-001: Multi-Tenant Organization Support

Priority: CRITICAL
Owner: Product Owner

Description

The system shall support multiple independent utility companies (organizations) with complete data isolation at blob storage, processing, and user access levels.

Business Value

1. Revenue Model: Enables SaaS subscription model across Nordic markets
2. Cost Efficiency: Shared infrastructure reduces per-customer cost by 60-70%
3. Market Penetration: Faster onboarding enables rapid customer acquisition
4. Scalability: Single platform scales to serve 150+ Swedish utilities alone

Nordic Market Context

• Sweden: ~150 electricity suppliers, ~290 district heating companies
• Norway: ~140 electricity suppliers
• Denmark: ~60 electricity suppliers
• Finland: ~80 electricity suppliers

Total Addressable Market: 700+ potential customers

Acceptance Criteria

Dependencies

• Azure Blob Storage (container-per-organization strategy)
• PostgreSQL schema with user_organization_roles table
• Organization context middleware
• Role-based access control (RBAC) implementation

Risks & Mitigation

...

BR-002: Multi-Vendor XML Format Support

Priority: HIGH
Owner: Product Owner

Description

The system shall process invoice batch files from multiple vendor billing systems (GASEL/Telinet, XELLENT/Karlskoga, ZYNERGY/EG Software) with automatic format detection and transformation to canonical JSON.

Business Value

1. Market Coverage: Supports 70% of Swedish utilities market
2. Zero Custom Development: No per-vendor integration coding required
3. Faster Onboarding: 80% reduction in integration time
4. Vendor Agnostic: Future-proofs against vendor migrations

Nordic Market Context

Top 3 Billing Systems in Swedish Market:

• Telinet (EDIEL/GASEL format): ~30% market share
• Karlskoga/Xellent (OIOXML format): ~25% market share
• EG Zynergy (proprietary): ~15% market share

Combined Coverage: ~70% of addressable market

Acceptance Criteria

Vendor-Specific Requirements

GASEL (Telinet/EDIEL):

• Namespace: urn:ediel:se:electricity:invoice:1.0
• Date format: ISO 8601 (YYYY-MM-DD)
• Amount format: Decimal with period separator
• Required elements: InvoiceNumber, PartyName, PayableAmount

XELLENT (Karlskoga/OIOXML):

• Namespace: http://rep.oio.dk/ubl/xml/schemas/0p71/pie/
• Multiple namespace prefixes: com:, main:, fsv:
• Amount format: "1 245,00" (space separator, comma decimal)
• Must normalize to standard decimal

ZYNERGY (EG Software):

• Namespace: http://eg.dk/Zynergy/1.0/invoice.xsd
• Nested structure: Invoice > Customer, InvoiceData, InvoiceAddress
• Multiple company ID references throughout
• InvoiceAmount vs InvoiceBalance distinction

Dependencies

• Schema registry with field mappings per vendor
• XML parsing library (System.Xml.Linq)
• XSD schema files from vendors
• Canonical JSON schema definition

Risks & Mitigation

...

BR-003: Batch Invoice Processing

Priority: HIGH
Owner: Product Owner

Description

The system shall process batch invoice files containing up to 100,000 invoices with parallel processing, retry logic, and granular status tracking.

Business Value

1. High-Volume Support: Typical Swedish utility has 50K-200K customers
2. Time Efficiency: 95% reduction in manual processing effort
3. Customer Satisfaction: Days → hours delivery time
4. Predictable SLAs: Enables committed service levels

Nordic Market Context

Monthly Invoice Patterns:

• Peak concentration: First/last week of month
• Heating season (Oct-Mar): 40% higher volumes
• January peak: Coldest month, highest consumption
• Summer (Jun-Aug): 50-60% of winter volumes

Acceptance Criteria

Processing Flow

1. API receives batch upload → 201 Created (batch stored)
2. POST /start → 202 Accepted (queued for processing)
3. ParserService picks from batch-upload-queue
4. Parse XML → Individual JSON files (canonical format)
5. Group into 32-item batches → Enqueue to batch-items-queue
6. DocumentGenerator renders 32 items in parallel
7. Generate HTML → PDF → Store in blob
8. Route to delivery queue (email or postal)
9. Update batch statistics in real-time
10. Complete when all items processed

Dependencies

• Azure Storage Queues (message passing)
• Worker auto-scaling (Container Apps + KEDA)
• Blob storage (source files + processed invoices)
• Batch metadata storage (real-time updates)

Risks & Mitigation

...

BR-004: Template-Based Invoice Rendering

Priority: HIGH
Owner: Product Owner

Description

The system shall generate PDF and HTML invoices using organization-specific Handlebars templates with dynamic data binding and brand customization.

Business Value

1. Brand Consistency: Professional appearance across all communications
2. Regulatory Compliance: Swedish Energy Markets Inspectorate requirements
3. Flexibility: Per-organization customization without code changes
4. Future-Proof: Multi-language support foundation (SE, NO, DK, FI)

Swedish Regulatory Requirements

Energimarknadsinspektionen (Swedish Energy Markets Inspectorate) mandates:

• Consumption details (period, kWh)
• Tax breakdown (25% VAT for electricity)
• Grid owner information
• Metering point ID (mätpunkt)
• Price per kWh
• Fixed monthly fee (månadsavgift)

Acceptance Criteria

Template Structure

Required Fields (Swedish Regulations):

• Invoice number (Fakturanummer)
• Invoice date (Fakturadatum)
• Due date (Förfallodatum)
• Period (Period)
• Metering point ID (Mätpunkt)
• Grid area (Elområde)
• Grid owner (Nätägare)
• Consumption (Förbrukning)
• Previous/current reading (Mätarställning)
• Unit price (Pris per kWh)
• Monthly fee (Månadsavgift)
• Subtotal (Delsumma)
• VAT 25% (Moms 25%)
• Total amount (Att betala)
• Payment info (Bankgiro, OCR)

Dependencies

• Handlebars.Net template engine
• PDF generation (Playwright + Chromium or IronPDF)
• Blob storage (template files)
• Template metadata storage with versioning

Risks & Mitigation

...

BR-005: Multi-Channel Delivery with Nordic Integration

Priority: HIGH
Owner: Product Owner

Description

The system shall deliver invoices through multiple channels (email, postal, future: Kivra, e-Faktura) with configurable priority, automatic fallback, and integration with Nordic delivery partners.

Business Value

1. Delivery Success: >98% vs ~92% email-only
2. Cost Reduction: Reduced returned mail costs
3. Customer Preference: Digital-first with postal backup
4. Legal Compliance: Swedish "rätt till pappersfaktura" (right to paper invoice)
5. Future-Ready: Digital mailbox mandate preparations

Nordic Market Context

Legal Requirements:

• Sweden: Postal option legally required for all customers
• Kivra Adoption: 4.2M users in Sweden (40% of population)
• E-faktura: Standard for B2B invoicing across Nordics
• Postal Tradition: Especially important for elderly customers

Delivery Statistics (Industry Average):

• Email delivery: 90-95% success
• Email + Postal fallback: 98-99% success
• Pure postal: 97-98% success

Acceptance Criteria

Channel Specifications

Email (SendGrid):

• Dedicated Nordic IP for sender reputation
• SPF/DKIM/DMARC configuration
• Swedish-localized email templates
• PDF attachment (compressed if >5MB)
• Retry: 2 attempts (1 min, 5 min delays)
• Failure → Postal fallback

Postal (21G Bulk SFTP):

• Scheduled processing: 12:00 and 20:00 CET
• ZIP archive format: PDFs + XML metadata
• SFTP upload to /incoming/{org-code}/
• SLA: 24-48 hours from upload to print
• Tracking: Email confirmation from 21G

Phase 2 Channels:

• Kivra digital mailbox (4.2M Swedish users)
• e-Faktura/PEPPOL (B2B standard)
• SMS notifications (Wiraya integration)

Dependencies

• SendGrid account (Nordic IP reputation)
• 21G SFTP server access and credentials
• Azure Key Vault (credential storage)
• Postal queue processing service
• ZIP file generation for 21G format

Risks & Mitigation

...

Non-Functional Requirements

NFR-001: Performance Targets

Priority: HIGH
Owner: Technical Architect

Performance Metrics

Load Testing Scenarios

Scenario 1: Steady State (Normal Month)

• Duration: 24 hours
• Load: 333K invoices evenly distributed
• Concurrent batches: 5-10
• Expected: All targets met, no errors

Scenario 2: Peak Load (Heating Season)

• Duration: 8 hours
• Load: 314K invoices (first week concentration)
• Concurrent batches: 20+
• Expected: 2-hour SLA met, >99% success

Scenario 3: Spike Test

• Duration: 30 minutes
• Load: 10 batches (50K invoices) uploaded simultaneously
• Expected: Auto-scales, processes without degradation

Acceptance Criteria

...

NFR-002: Scalability & Auto-Scaling

Priority: HIGH
Owner: Technical Architect

Scaling Configuration

Peak Load Capacity

Normal Load (non-heating, mid-month):

• 333K invoices/day average
• 5-10 concurrent batches
• Worker instances: 10-20 total

Peak Load (heating season, first/last week):

• 2.2M invoices/week
• 314K invoices/day
• 20+ concurrent batches
• Worker instances: 80-100 total

Pre-Warming Strategy (Heating Season)

Monthly Schedule:
- Day 1-7: Pre-warm to 50 instances at 00:00
- Day 8-23: Scale based on queue (2-20 instances)
- Day 24-31: Pre-warm to 50 instances at 00:00

Heating Season (Oct-Mar): Double levels
- Day 1-7: Pre-warm to 80 instances
- Day 24-31: Pre-warm to 80 instances

...

NFR-003: Availability & Reliability

Priority: HIGH
Owner: Technical Architect

Availability Targets

Multi-Region Deployment

Primary Region: West Europe (Sweden, Denmark)
Secondary Region: North Europe (Norway, Finland)

Traffic Routing:

• Azure Traffic Manager (Performance routing)
• Health check: /health every 30 seconds
• Auto-failover: 3 consecutive failures
• Failover time: <2 minutes

...

NFR-004: Security Requirements

Priority: CRITICAL
Owner: Technical Architect

Authentication & Authorization

OAuth 2.0:

• Grant Type: Client Credentials
• Token Provider: Microsoft Entra ID
• Token Lifetime: 1 hour
• Algorithm: RS256

Roles:

1. Super Admin (global)
2. Organization Admin (single org)
3. Template Admin (single org)
4. Batch Operator (single org)
5. Read-Only User (single org)
6. API Client (single org)

Encryption

In Transit:

• TLS 1.3 minimum
• HSTS enabled

At Rest:

• Blob Storage: AES-256
• PostgreSQL: AES-256
• Backups: AES-256

...

NFR-005: Data Retention

Priority: HIGH
Owner: Legal/Compliance

...

Approval Section

Stakeholder Sign-Off

Approval Criteria

•  All CRITICAL requirements reviewed and accepted
•  All HIGH requirements reviewed and accepted
•  All dependencies identified and acknowledged
•  All risks reviewed with mitigation strategies
•  All acceptance criteria defined and measurable
•  Budget and timeline implications understood
•  Resource allocation confirmed
•  Compliance requirements validated (GDPR, Bokföringslagen)

Change Control

Any changes to approved CRITICAL or HIGH priority requirements must follow the change control process:

1. Document proposed change in Jira (tag with egflow version)
2. Impact assessment (scope, timeline, cost)
3. Re-approval by Product Owner and Technical Architect
4. Update this document with version increment
5. Communicate changes to development team
6. Update affected Jira issues with new fixVersion

Version History

...

End of Business Requirements Document

2. Business Requirements

2.0 Priority Level Definitions

2.1 BR-001: Multi-Tenant Organization Support

Requirement: The system shall support multiple independent utility companies (organizations) with complete data isolation at the blob storage, processing, and user access levels.

Business Value:

• Enables SaaS business model for Nordic utilities market
• Reduces per-customer infrastructure costs by 60-70%
• Accelerates new customer onboarding (weeks → days)
• Increases addressable market across Sweden, Norway, Denmark, Finland

Priority: CRITICAL

Nordic Market Context: Swedish utilities market has ~150 electricity suppliers, ~290 district heating companies. Multi-tenancy is essential for market penetration.

Acceptance Criteria:

Dependencies:

• Azure Blob Storage with container-per-organization strategy
• PostgreSQL schema with user_organization_roles table
• Middleware for organization context extraction and validation
• Role-based access control implementation

Risks & Mitigation (Nordic Context):

2.2 BR-002: Multi-Vendor XML Format Support

Requirement: The system shall process invoice batch files from multiple vendor billing systems (GASEL/Telinet, XELLENT/Karlskoga, ZYNERGY/EG Software) with automatic format detection and transformation to canonical JSON.

Business Value:

• Eliminates integration barrier for new customers (any billing system supported)
• Reduces onboarding time by 80% (no custom integration development)
• Increases market addressability to all Nordic utilities regardless of billing system
• Enables vendor-agnostic downstream processing

Priority: HIGH

Nordic Market Context: Top 3 billing systems in Swedish utilities market: Telinet (EDIEL format), Karlskoga/Xellent (OIOXML), EG Zynergy (proprietary). Supporting these covers ~70% of market.

Acceptance Criteria:

Dependencies:

• Schema registry with field mappings for each vendor
• XML parsing library supporting complex namespaces
• XSD schema files from vendors (Telinet, Karlskoga, EG)
• Canonical JSON schema definition

Risks & Mitigation (Nordic Context):

2.3 BR-003: Batch Invoice Processing

Requirement: The system shall process batch invoice files containing up to 100,000 invoices with parallel processing, retry logic, and granular status tracking.

Business Value:

• Enables high-volume monthly invoice runs (typical Swedish utility: 50K-200K customers)
• Reduces manual processing effort by 95%
• Improves time-to-customer (days → hours)
• Enables predictable SLA commitments to customers

Priority: HIGH

Nordic Market Context: Monthly invoice cycles concentrated in first/last week of month. Heating season (Oct-Mar) has 40% higher volumes. System must handle seasonal peaks.

Acceptance Criteria:

Dependencies:

• Azure Storage Queues for message passing
• Worker auto-scaling (Container Apps with KEDA)
• Blob storage for batch source files and processed invoices
• Batch metadata storage with real-time updates

Risks & Mitigation (Nordic Context):

2.4 BR-004: Template-Based Invoice Rendering

Requirement: The system shall generate PDF and HTML invoices using organization-specific Handlebars templates with dynamic data binding and brand customization.

Business Value:

• Enables brand consistency across all customer communications
• Supports regulatory requirements (Swedish Energy Markets Inspectorate guidelines)
• Allows per-organization customization without code changes
• Future-proofs for multi-language support (Swedish, Norwegian, Danish, Finnish)

Priority: HIGH

Nordic Market Context: Swedish regulations require specific invoice information (consumption details, tax breakdown, grid owner, metering point). Templates must support regulatory compliance.

Acceptance Criteria:

Dependencies:

• Handlebars.Net template engine library
• PDF generation library (Playwright with headless Chromium or IronPDF)
• Blob storage for template files
• Template metadata storage with version tracking

Risks & Mitigation (Nordic Context):

2.5 BR-005: Multi-Channel Delivery with Nordic Integration

Requirement: The system shall deliver invoices through multiple channels (email, postal, future: Kivra, e-Faktura, SMS) with configurable priority, automatic fallback, and integration with Nordic delivery partners.

Business Value:

• Increases delivery success rate to >98% (vs ~92% email-only)
• Reduces returned mail costs (postal fallback)
• Meets customer preferences (digital-first, postal backup)
• Enables compliance with Swedish "rätt till pappersfaktura" (right to paper invoice)
• Future-proofs for digital mailbox mandate discussions

Priority: HIGH

Nordic Market Context: Swedish law requires postal option for all customers. Kivra has 4.2M users in Sweden (40% population). E-faktura standard for B2B. Multi-channel is regulatory and competitive necessity.

Acceptance Criteria:

Dependencies:

• SendGrid account with Nordic sender reputation
• 21G SFTP server access and credentials
• Azure Key Vault for credential storage
• Postal queue processing service (scheduled workers)
• ZIP file generation for 21G format

Risks & Mitigation (Nordic Context):

2.6 BR-006: Real-Time Batch Status Visibility

Requirement: Users shall view batch processing status, progress statistics, and individual invoice statuses in real-time through the API with granular breakdown by processing stage and delivery channel.

Business Value:

• Reduces support inquiries by 60% (self-service status checking)
• Enables proactive issue resolution before customer complaints
• Improves operational transparency and trust
• Provides audit trail for service level agreement (SLA) tracking

Priority: MEDIUM

Nordic Market Context: Utility operations teams work standard hours (08:00-17:00). Real-time visibility enables remote monitoring and reduces after-hours escalations.

Acceptance Criteria:

Dependencies:

• Batch metadata updates from all workers
• Real-time statistics calculation (incremental updates)
• Blob storage access for metadata reads
• API caching strategy for frequently-polled batches

Risks & Mitigation:

2.7 BR-007: Security & Access Control

Requirement: The system shall implement OAuth 2.0 authentication with Microsoft Entra ID, role-based access control with 6 distinct roles, organization-level data isolation, and comprehensive audit logging compliant with Swedish and EU security standards.

Business Value:

• Ensures GDPR Article 32 compliance (security of processing)
• Prevents unauthorized data access and potential €20M GDPR fines
• Enables customer trust and enterprise sales (security requirements in tenders)
• Supports SOC 2 Type II compliance for future certification

Priority: CRITICAL

Nordic Market Context: Swedish utilities handle sensitive customer data (personnummer, consumption patterns). GDPR fines can reach 4% of annual turnover. Enterprise security is non-negotiable.

Acceptance Criteria:

Dependencies:

• Microsoft Entra ID tenant configuration
• PostgreSQL schema for users, roles, user_organization_roles
• Azure Key Vault for secrets management
• Audit logging infrastructure
• MFA provider integration

Risks & Mitigation (Nordic/EU Context):

2.8 BR-008: GDPR & Swedish Data Protection Compliance

Requirement: The system shall comply with GDPR and Swedish Data Protection Law including all data subject rights, lawful processing basis, 7-year retention for invoices, data minimization, and Nordic data residency.

Business Value:

• Avoids GDPR fines (up to €20M or 4% of annual turnover)
• Enables enterprise sales (GDPR compliance is tender requirement)
• Builds customer trust and brand reputation
• Supports Swedish utility regulatory requirements (Energimarknadsinspektionen)

Priority: CRITICAL

Nordic Market Context: Swedish Datainspektionen actively enforces GDPR. Recent fines in telecom/energy sector for inadequate security. Data residency within EU required for many public utility contracts.

Acceptance Criteria:

Dependencies:

• Legal review of GDPR compliance approach
• Data anonymization procedures and testing
• Azure Blob lifecycle policies for retention
• Data Processing Agreement (DPA) with Azure
• Privacy Impact Assessment (PIA) completion

Risks & Mitigation (Swedish/EU Context):

2.9 BR-009: Operational Monitoring & Observability

Requirement: The system shall provide comprehensive monitoring through Application Insights, structured logging with Serilog, real-time dashboards, and automated alerting to enable 24/7 operational visibility and proactive issue resolution.

Business Value:

• Reduces mean time to detection (MTTD) from hours to minutes
• Enables proactive issue resolution before customer impact
• Supports SLA compliance and reporting
• Reduces on-call burden through automated diagnostics

Priority: HIGH

Nordic Market Context: Swedish customers expect high service quality. Many utilities have SLA commitments (99.9% uptime). Winter heating season requires 24/7 monitoring.

Acceptance Criteria:

Required Dashboards:

1. Operations Dashboard: Active batches, queue depths, worker counts, error rate, health status
2. Performance Dashboard: API latency, processing times, PDF generation, delivery latency
3. Business Dashboard: Invoices processed, delivery breakdown, top organizations
4. Vendor Dashboard: Batches by format, parsing success rates

Dependencies:

• Application Insights workspace
• Alert action groups (email, SMS)
• Dashboard configuration and permissions
• On-call rotation schedule

Risks & Mitigation (Nordic Context):

2.10 BR-010: Test Data Strategy (GDPR Compliance)

Requirement: The system shall use only synthetic, non-sensitive test data in all non-production environments, with zero copying of production data to staging, to ensure GDPR compliance and prevent data breaches.

Business Value:

• Ensures GDPR Article 5(1)(b) compliance (purpose limitation)
• Prevents catastrophic data breach from non-production environments
• Reduces storage and transfer costs (no production data duplication)
• Enables offshore development team participation (India)

Priority: CRITICAL

Nordic Market Context: Swedish Datainspektionen prohibits production data in test environments. Indian development team cannot access personnummer data. European team must lead production debugging.

Acceptance Criteria:

Dependencies:

• Synthetic data generation tool (Swedish personnummer, addresses, etc.)
• Staging environment completely isolated from production
• Network policies restricting production access
• Documentation of production issue workflow

Risks & Mitigation (EU/India Context):

2.11 BR-011: Invoice Download API

Requirement: Users shall be able to download generated invoices (PDF and HTML) through authenticated API endpoints with access control and audit logging.

Business Value:

• Enables customer service to retrieve invoices for disputes
• Supports reprint requests without reprocessing
• Facilitates regulatory compliance (invoice provision upon request)
• Enables future customer portal integration

Priority: HIGH

Acceptance Criteria:

Dependencies:

• Blob storage SAS token generation
• Access control middleware
• Audit logging service

Risks & Mitigation:

2.12 BR-012: Batch History & Search

Requirement: Users shall be able to search, filter, and list historical batches for their organization with support for date ranges, status filters, and vendor format filtering.

Business Value:

• Enables troubleshooting and root cause analysis
• Supports operational reporting and SLA tracking
• Facilitates audit compliance
• Improves user experience with search capabilities

Priority: MEDIUM

Acceptance Criteria:

Dependencies:

• Batch metadata indexing strategy
• Query performance optimization
• Blob storage metadata queries or search index

Risks & Mitigation:

2.13 BR-013: Notification System

Requirement: The system shall send email notifications to designated organization contacts when batch processing completes successfully or fails, including summary statistics and error reports.

Business Value:

• Reduces manual status checking effort by 80%
• Enables proactive issue resolution
• Improves customer satisfaction with timely updates
• Supports SLA monitoring and reporting

Priority: MEDIUM

Acceptance Criteria:

Dependencies:

• Email service (SendGrid or Azure Communication Services)
• Email templates (HTML)
• Organization configuration for recipients

Risks & Mitigation:

...