Page History

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

...