View Source

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

Revenue Model: Enables SaaS subscription model across Nordic markets
Cost Efficiency: Shared infrastructure reduces per-customer cost by 60-70%
Market Penetration: Faster onboarding enables rapid customer acquisition
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

#	Criterion	Measurement Method	Target
1	Concurrent organizations supported	Load test with 50 orgs	All batches process successfully
2	Data isolation enforcement	Cross-org access attempts	100% blocked (403 Forbidden)
3	Organization-specific blob containers	Verify storage paths	Pattern: `{org-id}-{type}-{year}/`
4	User organization boundary enforcement	API calls with wrong org context	All rejected
5	Independent branding per organization	Upload logo, verify rendering	Branding applied correctly
6	Configurable delivery channels	Set priority [email, postal]	Order respected

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

Risk	Likelihood	Impact	Mitigation
Data leakage between orgs	LOW	CRITICAL	Middleware enforcement, automated testing, penetration testing
Performance degradation (50+ tenants)	MEDIUM	HIGH	Blob auto-scaling, connection pooling, indexed queries
Swedish data residency requirements	LOW	HIGH	West Europe primary, no cross-border transfer

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

Market Coverage: Supports 70% of Swedish utilities market
Zero Custom Development: No per-vendor integration coding required
Faster Onboarding: 80% reduction in integration time
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

#	Criterion	Measurement Method	Target
1	GASEL format detection	50 sample files	100% accuracy
2	XELLENT format detection	50 sample files	100% accuracy
3	ZYNERGY format detection	50 sample files	100% accuracy
4	Canonical JSON transformation	Schema validation	All fields present
5	XSD schema validation	Vendor-specific XSD	Pass validation
6	Unsupported format handling	Unknown XML upload	415 error with vendor list
7	Detection performance	100MB file	< 1 second

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

Risk	Likelihood	Impact	Mitigation
Vendor schema changes without notice	MEDIUM	HIGH	Version all schemas, support multiple versions, 3-month deprecation notice
EDIEL standard evolution	MEDIUM	MEDIUM	Monitor Ediel.org, participate in Nordic working groups, backward compatibility
Complex namespace handling (OIOXML)	LOW	MEDIUM	XmlNamespaceManager, extensive unit testing per vendor
Incomplete field mappings	MEDIUM	MEDIUM	Comprehensive validation, custom fields dictionary, lenient parsing mode

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

High-Volume Support: Typical Swedish utility has 50K-200K customers
Time Efficiency: 95% reduction in manual processing effort
Customer Satisfaction: Days → hours delivery time
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

#	Criterion	Measurement Method	Target
1	Single batch capacity	Upload 100K invoices	All processed
2	Asynchronous processing	API response time	< 500ms (202 Accepted)
3	Real-time progress tracking	Poll during processing	Updates every 30 seconds
4	Failed item isolation	10 errors in 1000-item batch	990 succeed independently
5	Retry mechanism	Force temporary failure	3 retries then poison queue
6	Processing time SLA	100K invoice batch	≤ 120 minutes
7	Format support (Phase 1)	Upload XML, JSON, CSV	XML fully supported

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

Risk	Likelihood	Impact	Mitigation
Processing timeout during heating season	MEDIUM	HIGH	Pre-warm workers 1st/last week, priority queue, off-peak scheduling
Memory constraints (large XML >50MB)	MEDIUM	MEDIUM	Stream-based parsing, chunk processing, 100MB hard limit
Disk space exhaustion	LOW	MEDIUM	Ephemeral storage cleanup, blob-only persistence
Queue 64KB message limit	MEDIUM	MEDIUM	Store data in blob, queue references only

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

Brand Consistency: Professional appearance across all communications
Regulatory Compliance: Swedish Energy Markets Inspectorate requirements
Flexibility: Per-organization customization without code changes
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

#	Criterion	Measurement Method	Target
1	Custom template upload	Upload via API/blob	Stored successfully
2	Dynamic data binding	Test with invoice data	All fields populated
3	PDF generation	HTML → PDF	A4 format, readable
4	Template versioning	Create v2.0.0	Old batches use v1.0.0
5	In-flight batch isolation	Update template during processing	In-flight uses old version
6	Template validation	Missing variable upload	Validation error returned
7	Organization branding	Logo, colors, fonts	Visible in rendered PDF
8	Swedish regulatory fields	Verify required elements	All present

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

Risk	Likelihood	Impact	Mitigation
Template rendering bottleneck	HIGH	HIGH	Compiled template caching (24h), parallel rendering (32 items), POC: 10K in <5 min
PDF generation quality (Swedish chars)	MEDIUM	MEDIUM	UTF-8 encoding, font embedding (åäö), visual regression testing
Swedish regulatory compliance	LOW	CRITICAL	Legal review, required fields checklist, annual update review
Template injection attacks	LOW	CRITICAL	Sandboxed execution, no eval/exec helpers, sanitization, security review

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

Delivery Success: >98% vs ~92% email-only
Cost Reduction: Reduced returned mail costs
Customer Preference: Digital-first with postal backup
Legal Compliance: Swedish "rätt till pappersfaktura" (right to paper invoice)
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

#	Criterion	Measurement Method	Target
1	Email delivery (SendGrid)	1000 test invoices	>95% delivered
2	Postal delivery (21G SFTP)	Create ZIP, upload	File accepted by 21G
3	Channel priority configuration	Set [email, postal]	Email attempted first
4	Automatic fallback	Force email failure	Postal triggered auto
5	Delivery status tracking	Check invoice metadata	Status + timestamps recorded
6	Retry logic (transient failures)	Simulate SendGrid 429	Retries with backoff
7	Delivery confirmation logging	Verify audit log	All deliveries logged
8	21G bulk processing schedule	Verify postal queue	12:00 and 20:00 CET

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

Risk	Likelihood	Impact	Mitigation
SendGrid Nordic deliverability issues	MEDIUM	HIGH	Dedicated IP, SPF/DKIM/DMARC, sender reputation monitoring, backup: Azure Communication Services
21G SFTP connectivity issues	LOW	HIGH	Retry logic, dual credentials, alert on failure, 21G SLA monitoring, manual upload procedure
Postal delivery delays (Swedish postal)	MEDIUM	MEDIUM	Set expectations (5-7 days), track confirmations, escalation for >10 days
Email spam filtering (Swedish ISPs)	MEDIUM	MEDIUM	IP warmup, monitor bounce rates, ISP whitelist requests (Telia, Tele2, Telenor)

Non-Functional Requirements

NFR-001: Performance Targets

Priority: HIGH
Owner: Technical Architect

Performance Metrics

Metric	Target	Measurement	Test Scenario
Monthly throughput	10M invoices	Application Insights	Production monitoring
100K batch processing	< 2 hours	Timestamp diff	Load test TC-200
API response (p50)	< 200ms	Application Insights	Load test TC-201
API response (p95)	< 500ms	Application Insights	Load test TC-202
API response (p99)	< 1000ms	Application Insights	Load test TC-203
PDF generation (p95)	< 5 seconds/invoice	Custom metric	Render test TC-204
Handlebars render (p95)	< 2 seconds/invoice	Custom metric	Render test TC-205
Queue processing lag	< 5 minutes	Queue depth / throughput	Queue monitoring
Database query (p95)	< 100ms	PostgreSQL slow query log	Query analysis
ParserService (10K batch)	< 2 minutes	Parse duration	Parser test TC-206

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

#	Criterion	Validation	Target
1	100K batch completion	End-to-end test	≤ 2 hours
2	API latency under load	1000 RPS test	p95 ≤ 500ms
3	10M monthly capacity	Production monitoring	≥ 10M in peak month
4	50-org performance	50 concurrent uploads	All SLAs met
5	Worker auto-scaling	Monitor queue during peaks	Lag ≤ 5 min
6	PDF generation performance	1000 PDFs	p95 ≤ 5 seconds

NFR-002: Scalability & Auto-Scaling

Priority: HIGH
Owner: Technical Architect

Scaling Configuration

Component	Min	Max	Trigger	Threshold	Scale Up	Scale Down
CoreApiService	5	20	CPU OR Request Rate	70% OR 1000 RPS	2 min	10 min
ParserService	2	10	Queue Length	>0	1 min	5 min
DocumentGenerator	2	100	Queue Length	>32	1 min	5 min
EmailService	5	50	Queue Length	>50	1 min	5 min
PostalService	1	3	Scheduled	12:00, 20:00 CET	N/A	After completion

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

Metric	Target	Allowed Downtime	Measurement
System Uptime	99.9%	43 min/month	Azure Monitor
Batch Success Rate	>99.5%	50 failures per 10K	Processing logs
Delivery Success Rate	>98%	200 failures per 10K	Delivery tracking
API Availability	99.9%	43 min/month	Health checks
MTTR	<30 minutes	N/A	Incident timestamps
MTBF	>720 hours	N/A	Incident tracking

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:

Super Admin (global)
Organization Admin (single org)
Template Admin (single org)
Batch Operator (single org)
Read-Only User (single org)
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

Data Type	Retention	Storage Tier Transitions
Invoices (PDF/HTML/JSON)	7 years	Day 0-365: Hot Day 366-2555: Cool Day 2556+: Archive
Batch Source (XML)	90 days	Day 0-30: Hot Day 31-90: Cool Day 91+: Delete
Audit Logs	7 years	Year 0-1: PostgreSQL Year 1-7: Blob (compressed)
Application Logs	90 days	Application Insights

Approval Section

Stakeholder Sign-Off

Stakeholder Role	Name	Signature	Date	Status
Product Owner				☐ PENDING
Technical Architect				☐ PENDING

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:

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

Version History

Version	Date	Author	Changes	Release Target
1.0	2025-11-20	Product Owner	Initial draft	egflow-1.0.0
1.1	2025-11-21	Product Owner	Added FR-003 details, updated acceptance criteria	egflow-1.0.0
1.2	2025-11-27	Product Owner	Updated versioning strategy to match Gasell model	egflow-1.0.0 "Corny Flamingo"

End of Business Requirements Document