EG Flow Phase 1 - Requirements Analysis Document

Document Information

Approval Required From:

Document Purpose

This Requirements Analysis Document serves as the single source of truth for EG Flow Phase 1 development. All requirements documented herein must be reviewed and approved by stakeholders before development begins.

Document Scope:

• Business requirements with clear acceptance criteria and business value
• Functional requirements with complete technical specifications
• Non-functional requirements (performance, security, scalability, reliability)
• Complete data flow diagrams and processing pipelines
• Comprehensive error handling and validation rules
• Success criteria and validation methods

Out of Scope for Phase 1:

• Kivra digital mailbox integration (planned for Phase 2)
• e-Faktura/PEPPOL electronic invoicing (planned for Phase 2)
• Customer self-service portal (planned for Phase 2)
• Payment processing and reconciliation (future phase)
• Invoice amendments and credit notes (future phase)
• Advanced analytics and business intelligence (future phase)
• SMS distribution via Wiraya (future phase)

Documentation Standards:

• All technical diagrams created using Draw.io VSCode extension
• Diagrams include source XML for version control
• All findings documented in Confluence (link above)
• Visual structures for flows and relationships
• Searchable, structured format for all technical details

Table of Contents

1. Project Overview
2. Business Requirements
3. Functional Requirements
4. Non-Functional Requirements
5. Data Flow Diagrams
6. API Specifications
7. Error Handling & Validation
8. Glossary
9. Appendices

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:

3. Functional Requirements

3.1 FR-001: Batch File Upload

Requirement: Users shall upload batch invoice files through a RESTful API with automatic vendor format detection, file validation, and storage in organization-specific blob containers with month/day hierarchy.

Priority: HIGH

API Endpoint: POST /organizations/{organizationId}/batches

Request Format:

POST /v1/organizations/123e4567-e89b-12d3-a456-426614174000/batches HTTP/1.1
Host: api.egflow.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary

------WebKitFormBoundary
Content-Disposition: form-data; name="file"; filename="invoices_nov.xml"
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8"?>
<InvoiceBatch xmlns="urn:ediel:se:electricity:invoice:1.0">
  ...
</InvoiceBatch>
------WebKitFormBoundary
Content-Disposition: form-data; name="metadata"
Content-Type: application/json

{
  "batchName": "Invoice_November_2025",
  "priority": "normal"
}
------WebKitFormBoundary--

Response Format (201 Created):

{
  "success": true,
  "data": {
    "batchId": "550e8400-e29b-41d4-a716-446655440000",
    "organizationId": "123e4567-e89b-12d3-a456-426614174000",
    "status": "uploaded",
    "uploadedAt": "2025-11-21T10:30:00Z",
    "fileInfo": {
      "fileName": "invoices_nov.xml",
      "fileSize": 15728640,
      "checksum": "sha256:a3d5e7f9b2c4d6e8...",
      "detectedFormat": "GASEL"
    },
    "blobPath": "acme-batches-2025/11/21/550e8400.../source.xml"
  },
  "metadata": {
    "timestamp": "2025-11-21T10:30:00Z",
    "requestId": "req-abc-123",
    "apiVersion": "1.0"
  }
}

Blob Storage Path Pattern (Updated per Nov 21 decision):

{org-id}-batches-{year}/{month}/{day}/{batch-id}/source.xml

Acceptance Criteria:

Validation Rules:

Error Scenarios:

3.2 FR-002: Batch Processing Initiation

Requirement: Users shall initiate batch processing through API, which enqueues the batch to batch-upload-queue for asynchronous processing by ParserService.

Priority: HIGH

API Endpoint: POST /organizations/{organizationId}/batches/{batchId}/start

Request Format:

POST /v1/organizations/{orgId}/batches/{batchId}/start HTTP/1.1
Authorization: Bearer {token}
Content-Type: application/json

{
  "validationMode": "strict"
}

Response Format (202 Accepted):

{
  "success": true,
  "data": {
    "batchId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "queued",
    "queuedAt": "2025-11-21T10:35:00Z",
    "estimatedProcessingTime": "15-30 minutes",
    "queuePosition": 2,
    "queueName": "batch-upload-queue"
  }
}

Processing Flow:

1. Validate batch exists and status is "uploaded"
2. Create message in batch-upload-queue with batch metadata
3. Update batch status to "queued" in blob metadata
4. Return 202 Accepted with queue position
5. ParserService picks up message asynchronously

Acceptance Criteria:

Validation Rules:

Error Scenarios:

3.3 FR-003: Parser Service (XML → JSON Transformation)

Requirement: The ParserService shall listen to batch-upload-queue, download batch XML from blob storage, detect vendor format, validate against XSD schema, parse to individual invoices, transform to canonical JSON format, and enqueue to batch-items-queue in groups of 32.

Priority: CRITICAL

Service Specifications:

Trigger: Message in batch-upload-queue
Input: Batch ID from queue message
Output: Individual JSON files in blob + messages in batch-items-queue

Processing Steps:

1. Dequeue message from batch-upload-queue
2. Download batch XML from blob: {org}-batches-{year}/{month}/{day}/{batch-id}/source.xml
3. Detect vendor format (namespace + structure analysis):
   - urn:ediel → GASEL
   - oio.dk → XELLENT
   - Zynergy → ZYNERGY
4. Load vendor-specific schema mapping from: {org}-data/schemas/{vendor}-mapping.json
5. Validate XML against vendor XSD schema
6. Parse XML using XPath expressions from mapping
7. Transform each invoice to canonical JSON format
8. Store individual JSON files: {org}-invoices-{year}/{month}/{day}/{invoice-id}.json
9. Group invoices into batches of 32
10. Enqueue each 32-item batch to batch-items-queue
11. Update batch metadata: totalItems, vendor info, status="processing"
12. Delete message from batch-upload-queue (on success)
13. On error: Retry (3x with backoff) or move to poison queue

Canonical JSON Schema (Output Format):

{
  "invoiceId": "uuid",
  "invoiceNumber": "2025-11-001",
  "invoiceDate": "2025-11-06",
  "dueDate": "2025-11-20",
  "currency": "SEK",
  "periodStart": "2025-10-01",
  "periodEnd": "2025-10-31",
  
  "customer": {
    "customerId": "020624-2380",
    "fullName": "Medeni Schröder",
    "firstName": null,
    "lastName": null,
    "email": "muntaser.af@zavann.net",
    "phone": "09193538799",
    "address": {
      "street": "Strandbo 63B",
      "houseNumber": null,
      "apartment": null,
      "city": "Växjö",
      "postalCode": "352 58",
      "country": "SE"
    },
    "taxIdentifier": "020624-2380",
    "customerType": "private"
  },
  
  "invoiceDetails": {
    "subTotal": 599.42,
    "taxAmount": 149.86,
    "totalAmount": 749.28,
    "lineItems": [
      {
        "lineNumber": 1,
        "description": "Elförbrukning - Fast pris",
        "quantity": 420,
        "unit": "KWH",
        "unitPrice": 1.026,
        "lineAmount": 430.92,
        "taxRate": 25.0,
        "taxAmount": 107.73,
        "category": "electricity"
      },
      {
        "lineNumber": 2,
        "description": "Månadsavgift",
        "quantity": 1,
        "unit": "MON",
        "unitPrice": 15.20,
        "lineAmount": 15.20,
        "taxRate": 25.0,
        "taxAmount": 3.80,
        "category": "fee"
      }
    ]
  },
  
  "delivery": {
    "meteringPointId": "735999756427205424",
    "gridArea": "SE4",
    "gridOwner": "Växjö Energi Elnät AB",
    "previousReading": {
      "date": "2025-09-30",
      "value": 10580,
      "type": "Actual"
    },
    "currentReading": {
      "date": "2025-10-31",
      "value": 11000,
      "type": "Actual"
    },
    "consumption": 420,
    "consumptionUnit": "kWh"
  },
  
  "payment": {
    "paymentId": "202511001",
    "paymentMethod": "Bankgiro",
    "bankAccount": "168-6039",
    "dueDate": "2025-11-20"
  },
  
  "sourceMetadata": {
    "vendorCode": "GASEL",
    "vendorVersion": "1.0",
    "originalBatchId": "BATCH2025110600001",
    "originalInvoiceId": "2025-11-001",
    "contractReference": "CON-2024-001",
    "customFields": {
      "productCode": "telinet_fixed",
      "productName": "Fast Pris Vintersäkra",
      "taxClassification": "Normal"
    },
    "parsedAt": "2025-11-21T10:35:45Z"
  }
}

Acceptance Criteria:

Vendor-Specific Parsing Rules:

GASEL Format:

Required Elements (validation fails if missing):
- BatchHeader/InterchangeID
- BatchHeader/TotalInvoiceCount
- SupplierParty/PartyName
- Invoice/InvoiceHeader/InvoiceNumber
- Invoice/CustomerParty/PartyName
- Invoice/MonetarySummary/PayableAmount

Optional Elements (null if missing):
- Invoice/DeliveryLocation/MeteringPointID
- Invoice/ContractDetails/ContractID
- Invoice/CustomerParty/Contact/ElectronicMail
- Invoice/CustomerParty/Contact/Telephone

Date Format: ISO 8601 (YYYY-MM-DD)
Amount Format: Decimal with 2 places, period as separator
Namespace: urn:ediel:se:electricity:invoice:1.0

XELLENT Format:

Required Elements:
- BatchHeader/BatchID
- com:ID (invoice number)
- com:IssueDate
- com:BuyerParty/com:PartyName/com:Name
- com:LegalTotals/com:ToBePaidTotalAmount

Optional Elements:
- com:BuyerParty/com:ContactInformation/@E-Mail
- com:BuyerParty/com:Address

Special Handling:
- Multiple namespaces (com:, main:, fsv:)
- Amount format: "1 245,00" (space separator, comma decimal)
- Must normalize to standard decimal format

Namespace: http://rep.oio.dk/ubl/xml/schemas/0p71/pie/

ZYNERGY Format:

Required Elements:
- BatchHeader/BatchId
- InvoiceData/InvoiceNumber
- Customer/ReadOnlyFullName
- InvoiceData/InvoiceAmount

Optional Elements:
- Customer/FirstName and LastName (if ReadOnlyFullName empty)
- InvoiceAddress/EmailAddress
- VAT details

Special Handling:
- Nested structure (Invoice > Customer, InvoiceData, InvoiceAddress, VAT)
- Multiple company references (CompaniesId throughout)
- InvoiceAmount vs InvoiceBalance distinction

Namespace: http://eg.dk/Zynergy/1.0/invoice.xsd

Dependencies:

• Azure Storage Queue: batch-upload-queue
• Vendor schema mappings in blob storage
• XSD schema files for validation
• Canonical JSON schema definition
• Error handling and retry infrastructure

Risks & Mitigation:

3.4 FR-004: Document Generator Service (JSON → HTML → PDF)

Requirement: The DocumentGeneratorService (based on existing zyn-DocumentGenerator) shall listen to batch-items-queue, load Handlebars templates, render HTML with invoice data, generate PDFs using Playwright, and store documents in blob storage with month/day hierarchy.

Priority: CRITICAL

Service Specifications:

Trigger: Message in batch-items-queue (contains 32 invoice references)
Input: Batch of 32 invoice IDs and organization ID
Output: PDF + HTML files in blob storage, messages in distribution routing queues

Processing Steps (per 32-item batch):

1. Dequeue message from batch-items-queue
2. Acquire blob lease: {org}-batches-{year}/{month}/{day}/{batch-id}/locks/{worker-id}.lock
3. For each of 32 invoices:
   a. Download JSON: {org}-invoices-{year}/{month}/{day}/{invoice-id}.json
   b. Load organization config: {org}-data/organization.json
   c. Determine template category from distribution type
   d. Load Handlebars template: {org}-data/templates/{category}/active.html
   e. Load organization branding (logo from blob URL, colors, fonts)
   f. Compile Handlebars template (cache compiled version)
   g. Render HTML with invoice data + branding
   h. Generate PDF from HTML using Playwright (headless Chromium)
   i. Store HTML: {org}-invoices-{year}/{month}/{day}/{invoice-id}.html
   j. Store PDF: {org}-invoices-{year}/{month}/{day}/{invoice-id}.pdf
   k. Update invoice JSON metadata with file paths and render timestamp
   l. Determine distribution method from invoice data
   m. Enqueue to appropriate queue:
      - Mail (postal) → postal-bulk-queue (processed in bulk)
      - Email → email-queue
      - SMS (future) → sms-queue
      - Kivra (future) → kivra-queue
      - E-faktura (future) → efaktura-queue
4. Release blob lease
5. Update batch metadata: processedItems += 32
6. Delete message from batch-items-queue
7. On error: Retry (3x) or poison queue

Acceptance Criteria:

Handlebars Template Example:

<!DOCTYPE html>
<html lang="sv">
<head>
    <meta charset="UTF-8">
    <title>Faktura {{invoiceNumber}}</title>
    <style>
        body { font-family: {{organization.fontFamily}}; }
        .header { background-color: {{organization.primaryColor}}; color: white; padding: 20px; }
        .logo { max-width: 200px; }
    </style>
</head>
<body>
    <div class="header">
        <img src="{{organization.logoUrl}}" alt="{{organization.displayName}}" class="logo" />
        <h1>Faktura {{invoiceNumber}}</h1>
    </div>
    
    <div class="customer-info">
        <h2>Kund</h2>
        <p><strong>{{customer.fullName}}</strong></p>
        <p>{{customer.address.street}}</p>
        <p>{{customer.address.postalCode}} {{customer.address.city}}</p>
    </div>
    
    <div class="invoice-details">
        <p><strong>Fakturadatum:</strong> {{invoiceDate}}</p>
        <p><strong>Förfallodatum:</strong> {{dueDate}}</p>
        <p><strong>Period:</strong> {{periodStart}} - {{periodEnd}}</p>
        {{#if delivery.meteringPointId}}
        <p><strong>Mätpunkt:</strong> {{delivery.meteringPointId}}</p>
        <p><strong>Elområde:</strong> {{delivery.gridArea}}</p>
        <p><strong>Förbrukning:</strong> {{delivery.consumption}} {{delivery.consumptionUnit}}</p>
        {{/if}}
    </div>
    
    <table>
        <thead>
            <tr>
                <th>Beskrivning</th>
                <th>Antal</th>
                <th>Enhet</th>
                <th>Pris</th>
                <th>Belopp</th>
            </tr>
        </thead>
        <tbody>
            {{#each invoiceDetails.lineItems}}
            <tr>
                <td>{{this.description}}</td>
                <td>{{formatNumber this.quantity decimals=2}}</td>
                <td>{{this.unit}}</td>
                <td>{{formatCurrency this.unitPrice}}</td>
                <td>{{formatCurrency this.lineAmount}}</td>
            </tr>
            {{/each}}
            <tr class="total-row">
                <td colspan="4"><strong>Delsumma:</strong></td>
                <td><strong>{{formatCurrency invoiceDetails.subTotal}}</strong></td>
            </tr>
            <tr>
                <td colspan="4"><strong>Moms (25%):</strong></td>
                <td><strong>{{formatCurrency invoiceDetails.taxAmount}}</strong></td>
            </tr>
            <tr class="total-row">
                <td colspan="4"><strong>Att betala:</strong></td>
                <td><strong>{{formatCurrency invoiceDetails.totalAmount}} {{currency}}</strong></td>
            </tr>
        </tbody>
    </table>
    
    {{#if payment.paymentId}}
    <div class="payment-info">
        <h3>Betalningsinformation</h3>
        <p><strong>OCR-nummer:</strong> {{payment.paymentId}}</p>
        <p><strong>Bankgiro:</strong> {{payment.bankAccount}}</p>
        <p><strong>Förfallodatum:</strong> {{payment.dueDate}}</p>
    </div>
    {{/if}}
</body>
</html>

Dependencies:

• Handlebars.Net library for template rendering
• Playwright library for PDF generation
• Azure Storage Queue: batch-items-queue
• Blob storage for templates, JSON, PDF, HTML
• Organization configuration in blob
• Custom Handlebars helpers (formatCurrency, formatNumber, formatDate)

Risks & Mitigation:

3.5 FR-005: Email Delivery Service

Requirement: The EmailDeliveryService shall listen to email-queue, download PDF from blob storage, send via SendGrid with Swedish-localized email template, track delivery status, and retry on transient failures with fallback to postal queue.

Priority: HIGH

Service Specifications:

Trigger: Message in email-queue
Input: Invoice ID, recipient email, organization ID
Output: Email sent via SendGrid, delivery status updated

Processing Steps:

1. Dequeue message from email-queue
2. Download PDF: {org}-invoices-{year}/{month}/{day}/{invoice-id}.pdf
3. Load organization email configuration
4. Load email template (Swedish)
5. Create SendGrid message:
   - From: noreply@{org-domain}.com
   - To: {customer-email}
   - Subject: "Faktura {invoiceNumber} från {orgName}"
   - Body: HTML template with invoice summary
   - Attachment: invoice-{invoiceNumber}.pdf
6. Send via SendGrid API
7. Handle response:
   - Success (2xx): Update invoice status="delivered", log messageId
   - Rate limit (429): Re-queue with Retry-After delay
   - Transient error (5xx): Retry with exponential backoff (3x)
   - Permanent error (4xx): Move to postal-bulk-queue (fallback)
8. Update invoice metadata with delivery attempt
9. Delete from email-queue (on success or permanent failure)

Email Template (Swedish):

<!DOCTYPE html>
<html lang="sv">
<head>
    <meta charset="UTF-8">
    <title>Faktura</title>
</head>
<body style="font-family: Arial, sans-serif; max-width: 600px; margin: 0 auto;">
    <div style="background: #0066CC; color: white; padding: 20px; text-align: center;">
        <h1>Faktura från {{organizationName}}</h1>
    </div>
    
    <div style="padding: 20px;">
        <p>Hej {{customerName}},</p>
        
        <p>Din faktura för perioden {{periodStart}} till {{periodEnd}} är nu tillgänglig.</p>
        
        <table style="width: 100%; margin: 20px 0; border-collapse: collapse;">
            <tr style="background: #f5f5f5;">
                <td style="padding: 10px; border: 1px solid #ddd;"><strong>Fakturanummer:</strong></td>
                <td style="padding: 10px; border: 1px solid #ddd;">{{invoiceNumber}}</td>
            </tr>
            <tr>
                <td style="padding: 10px; border: 1px solid #ddd;"><strong>Förfallodatum:</strong></td>
                <td style="padding: 10px; border: 1px solid #ddd;">{{dueDate}}</td>
            </tr>
            <tr style="background: #f5f5f5;">
                <td style="padding: 10px; border: 1px solid #ddd;"><strong>Att betala:</strong></td>
                <td style="padding: 10px; border: 1px solid #ddd;"><strong>{{totalAmount}} SEK</strong></td>
            </tr>
        </table>
        
        <p><strong>Betalningsinformation:</strong></p>
        <p>Bankgiro: {{bankAccount}}<br>
        OCR-nummer: {{ocrNumber}}</p>
        
        <p>Din faktura finns bifogad som PDF.</p>
        
        <p>Vid frågor, kontakta oss på {{supportEmail}} eller {{supportPhone}}.</p>
        
        <p>Med vänlig hälsning,<br>
        {{organizationName}}</p>
    </div>
    
    <div style="background: #f5f5f5; padding: 15px; text-align: center; font-size: 12px; color: #666;">
        <p>Detta är ett automatiskt meddelande. Svara inte på detta e-postmeddelande.</p>
    </div>
</body>
</html>

Acceptance Criteria:

SendGrid Configuration:

{
  "sendgrid": {
    "apiKey": "{{from-azure-keyvault}}",
    "fromEmail": "noreply@{org-domain}.com",
    "fromName": "{organizationName}",
    "replyTo": "support@{org-domain}.com",
    "tracking": {
      "clickTracking": false,
      "openTracking": true,
      "subscriptionTracking": false
    },
    "mailSettings": {
      "sandboxMode": false,
      "spamCheck": {
        "enable": true,
        "threshold": 5
      }
    }
  }
}

Dependencies:

• SendGrid account with Nordic IP reputation
• Azure Storage Queue: email-queue
• Email templates in Swedish (+ future: Norwegian, Danish, Finnish)
• Organization email configuration in blob
• Fallback queue routing to postal

Risks & Mitigation (Nordic Email Deliverability):

3.6 FR-006: Postal Delivery Service (21G Bulk Integration)

Requirement: The PostalDeliveryService shall listen to postal-bulk-queue, collect invoices for bulk processing, create ZIP archive with PDFs and XML metadata in 21G format, upload to 21G SFTP server at scheduled times (12:00 and 20:00 Swedish time), and track delivery confirmations.

Priority: HIGH

Service Specifications:

Trigger: Scheduled execution (12:00 and 20:00 CET/CEST)
Input: All messages in postal-bulk-queue accumulated since last run
Output: ZIP file uploaded to 21G SFTP, delivery confirmations tracked

Processing Steps:

1. Scheduled trigger (12:00 and 20:00 Swedish time)
2. Fetch all messages from postal-bulk-queue (batch retrieval)
3. For each invoice in queue:
   a. Download PDF: {org}-invoices-{year}/{month}/{day}/{invoice-id}.pdf
   b. Download invoice JSON for metadata
   c. Validate recipient address is complete
   d. Add to 21G batch collection
4. Group by organization (21G requires org-specific batches)
5. For each organization batch:
   a. Create 21G XML metadata file with all invoice details
   b. Create ZIP archive: {org-code}_{date}_{sequence}.zip
      - Contains: invoice1.pdf, invoice2.pdf, ..., metadata.xml
   c. Upload ZIP to 21G SFTP: /incoming/{org-code}/
   d. Verify upload success
   e. Update all invoice statuses: status="postal_sent"
   f. Delete messages from postal-bulk-queue
6. Log bulk send statistics to Application Insights
7. Send notification email to organization (bulk send report)

21G ZIP Structure:

ACME_20251121_001.zip
├── metadata.xml (21G format)
├── invoice_001.pdf
├── invoice_002.pdf
├── invoice_003.pdf
└── ...

21G Metadata XML Format:

<?xml version="1.0" encoding="UTF-8"?>
<PrintBatch xmlns="urn:21g:print:batch:1.0">
  <BatchHeader>
    <BatchId>ACME_20251121_001</BatchId>
    <OrganizationCode>ACME</OrganizationCode>
    <CreationDate>2025-11-21T12:00:00</CreationDate>
    <TotalDocuments>150</TotalDocuments>
    <ServiceLevel>Economy</ServiceLevel>
  </BatchHeader>
  <Documents>
    <Document>
      <DocumentId>invoice_001.pdf</DocumentId>
      <DocumentType>Invoice</DocumentType>
      <Recipient>
        <Name>Medeni Schröder</Name>
        <Street>Strandbo 63B</Street>
        <PostalCode>352 58</PostalCode>
        <City>Växjö</City>
        <Country>SE</Country>
      </Recipient>
      <PrintOptions>
        <Format>A4</Format>
        <Color>false</Color>
        <Duplex>false</Duplex>
      </PrintOptions>
    </Document>
    <!-- ... more documents -->
  </Documents>
</PrintBatch>

Acceptance Criteria:

21G Integration Specifications:

SFTP Connection:

• Host: sftp.21g.se (or provider-specific)
• Port: 22
• Authentication: SSH key (stored in Azure Key Vault)
• Directory structure: /incoming/{org-code}/
• File naming: {org-code}{YYYYMMDD}{sequence}.zip

21G SLA:

• Processing time: 24-48 hours
• Confirmation: Email notification when processed
• Tracking: Available via 21G portal

Dependencies:

• 21G SFTP account and credentials
• Azure Storage Queue: postal-bulk-queue
• Scheduled worker (Azure Container Apps with CRON)
• ZIP file creation library
• 21G XML schema compliance
• Email notification service

Risks & Mitigation (Nordic Postal Context):

3.7 FR-007: Distribution Routing Logic

Requirement: The system shall determine the appropriate distribution queue for each invoice based on organization configuration, customer preferences, and distribution type (invoice vs document) following Swedish regulatory requirements.

Priority: HIGH

Routing Decision Tree:

Invoice Distribution Routing
│
├─ Check customer preference (if available)
│  ├─ Preference = "digital" → email-queue (or kivra-queue in future)
│  └─ Preference = "postal" → postal-bulk-queue
│
├─ Check organization default channels (from config)
│  ├─ Priority 1: email
│  │  └─ Has valid email? → email-queue
│  ├─ Priority 2: kivra (Phase 2)
│  │  └─ Kivra user? → kivra-queue
│  └─ Priority 3: postal
│     └─ postal-bulk-queue
│
├─ Document type consideration
│  ├─ Invoice (faktura) → All channels available
│  └─ Confirmation letter → Email/postal only
│
└─ Swedish regulatory compliance
   └─ Customer always has right to postal ("rätt till pappersfaktura")

Queue Selection Logic:

public async Task<string> DetermineDistributionQueueAsync(
    InvoiceDistribution distribution,
    OrganizationConfig config)
{
    // Customer preference overrides (if explicitly set)
    if (distribution.CustomerPreference == "postal")
        return "postal-bulk-queue";
    
    // Try channels in priority order
    var priorities = config.DeliveryChannels.ChannelPriority
        .OrderBy(p => p.Priority);
    
    foreach (var channel in priorities)
    {
        switch (channel.Channel)
        {
            case "email":
                if (!string.IsNullOrEmpty(distribution.CustomerEmail) &&
                    IsValidEmail(distribution.CustomerEmail))
                {
                    return "email-queue";
                }
                break;
                
            case "kivra": // Phase 2
                if (await IsKivraUserAsync(distribution.CustomerPersonnummer))
                {
                    return "kivra-queue";
                }
                break;
                
            case "efaktura": // Phase 2 (B2B only)
                if (distribution.CustomerType == "business" &&
                    !string.IsNullOrEmpty(distribution.OrganizationNumber))
                {
                    return "efaktura-queue";
                }
                break;
                
            case "postal":
                if (distribution.IsCompleteAddress())
                {
                    return "postal-bulk-queue";
                }
                break;
        }
    }
    
    // Ultimate fallback: postal (Swedish law requires paper option)
    return "postal-bulk-queue";
}

Acceptance Criteria:

Dependencies:

• Organization delivery configuration
• Customer preference storage (future)
• Email validation library
• Address validation library (Swedish postal codes)
• Kivra user lookup API (Phase 2)

Risks & Mitigation:

3.8 FR-008: Blob Concurrency Control (Note: Read-Only, No Concurrent Updates)

Requirement: The system shall use blob leases to ensure exclusive access during batch processing, preventing concurrent worker instances from processing the same 32-item batch.

Priority: HIGH

Clarification: Based on your feedback, there are no concurrent updates to files - workers only read invoice JSON files. The blob lease is used to ensure only one worker processes a given 32-item batch from the queue.

Lease Implementation:

public async Task ProcessBatchItemsAsync(BatchItemsMessage message)
{
    var lockBlobPath = $"{message.OrganizationId}-batches-{year}/{month}/{day}/{message.BatchId}/locks/{message.MessageId}.lock";
    BlobLease lease = null;
    
    try
    {
        // Acquire lease (5-minute duration)
        lease = await _blobLockService.AcquireLockAsync(
            containerName: $"{message.OrganizationId}-batches-{year}",
            blobName: lockBlobPath,
            leaseDuration: TimeSpan.FromMinutes(5));
        
        // Process 32 invoices (read-only operations)
        foreach (var invoiceId in message.InvoiceIds)
        {
            // Read invoice JSON from blob (no updates to JSON)
            var invoiceJson = await _blobStorage.DownloadJsonAsync(invoiceId);
            
            // Render and generate (creates new HTML/PDF blobs)
            await RenderAndGenerateAsync(invoiceJson);
            
            // No concurrent update risk - creating new blobs only
        }
        
        // Update batch metadata (ETag-based optimistic concurrency)
        await UpdateBatchMetadataAsync(message.BatchId, meta =>
        {
            meta.Statistics.ProcessedItems += message.InvoiceIds.Count;
        });
    }
    finally
    {
        if (lease != null)
        {
            await _blobLockService.ReleaseLockAsync(lease);
        }
    }
}

Acceptance Criteria:

Dependencies:

• Azure Blob Storage lease API
• ETag-based optimistic concurrency for metadata updates
• Retry logic for lease acquisition conflicts

3.9 FR-009: Queue Message Handling

Requirement: The system shall process queue messages with proper visibility timeouts, automatic retry on failure, poison queue handling, and message deduplication.

Priority: HIGH

Queue Configuration:

Message Format Standard:

{
  "messageId": "uuid",
  "messageType": "batch.upload|batch.items|email.delivery|postal.delivery",
  "version": "1.0",
  "timestamp": "2025-11-21T10:30:00Z",
  "data": {
    // Message-specific payload
  },
  "metadata": {
    "correlationId": "uuid",
    "organizationId": "uuid",
    "retryCount": 0,
    "enqueuedAt": "2025-11-21T10:30:00Z"
  }
}

Retry Policy (Exponential Backoff):

Acceptance Criteria:

Poison Queue Handling:

{
  "messageId": "uuid",
  "originalMessageType": "batch.items",
  "failedAt": "2025-11-21T10:50:00Z",
  "retryCount": 3,
  "lastError": {
    "code": "TEMPLATE_RENDERING_FAILED",
    "message": "Required variable 'customer.address.street' not found in template",
    "stackTrace": "...",
    "attemptTimestamps": [
      "2025-11-21T10:35:00Z",
      "2025-11-21T10:36:00Z",
      "2025-11-21T10:41:00Z",
      "2025-11-21T10:56:00Z"
    ]
  },
  "originalMessage": {
    // Full original message for debugging
  },
  "metadata": {
    "correlationId": "uuid",
    "alertSent": true,
    "alertRecipients": ["support@egflow.com"],
    "manualReviewRequired": true
  }
}

Dependencies:

• Azure Storage Queues with dead-letter queue support
• Alert service for poison queue notifications
• Monitoring dashboard for poison queue depth

3.10 FR-010: Health Check Endpoints

Requirement: All services shall expose health check endpoints that verify connectivity to dependencies (database, blob storage, queues) and return health status for Azure Traffic Manager and monitoring.

Priority: HIGH

API Endpoint: GET /health

Response Format (Healthy):

{
  "status": "Healthy",
  "timestamp": "2025-11-21T10:30:00Z",
  "version": "1.0.0",
  "checks": {
    "blobStorage": {
      "status": "Healthy",
      "responseTime": "45ms",
      "lastChecked": "2025-11-21T10:30:00Z"
    },
    "storageQueue": {
      "status": "Healthy",
      "responseTime": "32ms",
      "queueDepth": 150
    },
    "postgresql": {
      "status": "Healthy",
      "responseTime": "12ms",
      "activeConnections": 8
    },
    "keyVault": {
      "status": "Healthy",
      "responseTime": "67ms"
    }
  },
  "environment": "production",
  "region": "westeurope"
}

Response Format (Unhealthy):

{
  "status": "Unhealthy",
  "timestamp": "2025-11-21T10:30:00Z",
  "checks": {
    "blobStorage": {
      "status": "Unhealthy",
      "error": "Connection timeout after 5000ms",
      "lastChecked": "2025-11-21T10:30:00Z"
    },
    "postgresql": {
      "status": "Healthy",
      "responseTime": "15ms"
    }
  }
}

Acceptance Criteria:

Dependencies:

• Health check library (ASP.NET Core HealthChecks)
• Azure Traffic Manager configuration
• Monitoring integration

3.11 FR-011: Template Category Management

Requirement: The system shall support template categories (e.g., "Invoice", "Confirmation Letter", "Reminder") to group related templates and enable dynamic template selection based on document type.

Priority: MEDIUM

API Endpoint: GET /organizations/{organizationId}/template-categories

Response Format:

{
  "success": true,
  "data": {
    "categories": [
      {
        "categoryId": "uuid",
        "categoryName": "invoice",
        "displayName": "Faktura",
        "description": "Standard invoice template",
        "activeTemplateId": "uuid",
        "activeTemplateVersion": "2.1.0",
        "templateCount": 3
      },
      {
        "categoryId": "uuid",
        "categoryName": "confirmation",
        "displayName": "Bekräftelsebrev",
        "description": "Contract confirmation letter",
        "activeTemplateId": "uuid",
        "activeTemplateVersion": "1.0.0",
        "templateCount": 1
      },
      {
        "categoryId": "uuid",
        "categoryName": "reminder",
        "displayName": "Påminnelse",
        "description": "Payment reminder",
        "activeTemplateId": null,
        "templateCount": 0
      }
    ]
  }
}

Template Category Determination Logic:

Document Type → Template Category Mapping:

Invoice (faktura) → "invoice" template
Confirmation letter (bekräftelsebrev) → "confirmation" template
Payment reminder (påminnelse) → "reminder" template
Termination notice (uppsägning) → "termination" template
Contract change (avtalsändring) → "contract_change" template

Default: If category not found → use "invoice" template

Acceptance Criteria:

3.12 FR-012: Git Branching Strategy (Development Workflow)

Requirement: The development team shall follow a structured Git branching strategy with development, staging, and main branches, following industry best practices for continuous integration and deployment.

Priority: HIGH

Branch Structure (Updated per Nov 20 decision):

main (production)
  ↑
  └── staging (acceptance testing)
       ↑
       └── development (integration testing)
            ↑
            └── feature/* (short-lived branches)

Branch Policies:

Deployment Flow:

Developer → feature/GAS-12345-batch-upload
   ↓
   PR to development
   ↓
CI/CD: Build, Test, Deploy to Dev
   ↓
Integration testing in Dev
   ↓
   PR to staging (approved by Product Owner)
   ↓
CI/CD: Build, Test, Deploy to Staging
   ↓
UAT testing in Staging (European team only)
   ↓
   PR to main (approved by Product Owner + Architect + Ops)
   ↓
CI/CD: Build, Security Scan, Deploy to Prod (West Europe)
   ↓
Deploy to Prod (North Europe) - manual approval

Acceptance Criteria:

Dependencies:

• Azure DevOps or GitHub repository
• CI/CD pipeline configuration
• Branch protection policies
• Code review requirements

3.13 FR-013: Synthetic Test Data Generation (GDPR Compliance)

Requirement: The system shall provide a synthetic data generation tool that creates realistic but fake Swedish invoice data (personnummer, addresses, names) for use in staging and development environments, with zero production data copying.

Priority: CRITICAL

Synthetic Data Requirements:

Swedish Personnummer Generation:

Format: YYMMDD-XXXX
- YY: Year (00-99)
- MM: Month (01-12)
- DD: Day (01-31)
- XXXX: Last 4 digits with Luhn checksum

Generation Rules:
- Must pass Luhn algorithm validation
- Must NOT match any real personnummer
- Use test ranges: 19000101-19991231 (obviously fake dates)
- Flag as test: personnummer starts with "19"

Swedish Address Generation:

Street names: Random from Swedish street database
- Storgatan, Kungsgatan, Vasagatan, Drottninggatan...
- House numbers: 1-150
- Apartment: A-Z (optional)

Cities: Top 50 Swedish cities
- Stockholm, Göteborg, Malmö, Uppsala, Västerås...

Postal codes: Valid format (XXX XX) but non-existent ranges
- Use: 00X XX range (invalid but correct format)

Examples:
- Storgatan 45, 001 23 Stockholm
- Vasagatan 12 A, 002 45 Göteborg

Synthetic Invoice Data:

Invoice numbers: Test prefix "TEST-" + sequential
Amounts: Random between 100-5000 SEK
Consumption: Random 100-2000 kWh (residential realistic)
Metering points: Test range 735999999999999XXX
Email addresses: {firstname}.{lastname}@example-test.se
Phone numbers: +46701234XXX (test range)

Acceptance Criteria:

Dependencies:

• Swedish personnummer validation library
• Swedish postal code database (for validation, not generation)
• Random data generation library

Risks & Mitigation:

4. Non-Functional Requirements

4.1 NFR-001: Performance Targets

Requirement: The system shall meet specified performance targets for processing throughput, API latency, and rendering speed to support high-volume Nordic utilities operations.

Priority: HIGH

Performance Targets:

Load Testing Scenarios:

Scenario 1: Steady State (Normal Month)

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

Scenario 2: Peak Load (Heating Season)

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

Scenario 3: Spike Test

• Duration: 30 minutes
• Load: Sudden 10 batch uploads (50K invoices)
• Expected: System auto-scales, processes without degradation

Acceptance Criteria:

Dependencies:

• Azure Container Apps auto-scaling configuration
• Application Insights performance monitoring
• Load testing tool (NBomber, k6, or JMeter)
• Blob storage premium tier for high IOPS

Risks & Mitigation (Nordic Peak Season):

4.2 NFR-002: Scalability & Auto-Scaling

Requirement: The system shall scale horizontally without manual intervention to handle peak loads during Nordic heating season (October-March) and monthly invoice cycles.

Priority: HIGH

Scaling Configuration:

Peak Load Capacity:

Normal Load (non-heating season, 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 (95% of monthly volume)
• 314K invoices/day
• 20+ concurrent batches
• Worker instances: 80-100 total

Scaling Calculation:

Peak Day: 314,000 invoices
Processing time per invoice: 10 seconds (parse + render + PDF + deliver)
Total processing time: 314,000 × 10s = 872 hours
Target completion: 8 hours
Required workers: 872 / 8 = 109 workers
With 32 items/worker: 109 × 32 = 3,488 items processing simultaneously

Acceptance Criteria:

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 pre-warm levels
- Day 1-7: Pre-warm to 80 instances
- Day 24-31: Pre-warm to 80 instances

Dependencies:

• Azure Container Apps with KEDA (Kubernetes Event-Driven Autoscaling)
• Queue depth monitoring
• Historical load data for pre-warming schedule

Risks & Mitigation:

4.3 NFR-003: Availability & Reliability (Nordic 24/7 Operations)

Requirement: The system shall maintain 99.9% uptime with automatic failover, multi-region deployment, and recovery procedures to support Nordic utilities' 24/7 invoice delivery operations.

Priority: HIGH

Availability Targets:

Multi-Region Deployment:

Primary Region: West Europe (Azure westeurope)
- Sweden: Primary processing
- Denmark: Primary processing

Secondary Region: North Europe (Azure northeurope)
- Norway: Primary processing
- Finland: Primary processing
- Failover for Sweden/Denmark

Traffic Routing:
- Azure Traffic Manager with Performance routing
- Health check: /health endpoint every 30 seconds
- Auto-failover on 3 consecutive failed health checks
- Failover time: < 2 minutes

Recovery Time Objectives:

Backup & Recovery Strategy:

Blob Storage:

Replication: Geo-Redundant Storage (GRS)
  - Primary: West Europe
  - Secondary: North Europe
  - Automatic replication

Soft Delete: 7 days retention
  - Recover accidentally deleted blobs within 7 days

Blob Versioning: 30 days retention
  - Previous versions accessible
  - Rollback capability

Point-in-Time Restore: Not needed (blob versioning sufficient)

PostgreSQL:

Backup Schedule: Daily automated backups
Retention: 35 days
Backup Window: 02:00-04:00 CET (low traffic period)
Point-in-Time Restore: 7 days
Geo-Redundant: Enabled
Read Replica: North Europe (for failover)

Acceptance Criteria:

Dependencies:

• Azure Traffic Manager configuration
• Multi-region resource deployment
• Database replication setup
• Automated failover testing procedures
• Incident response runbook

Risks & Mitigation (Nordic Context):

4.4 NFR-004: Security Requirements

Requirement: The system shall implement comprehensive security controls including OAuth 2.0 authentication, role-based access control, encryption, audit logging, and protection against OWASP Top 10 vulnerabilities.

Priority: CRITICAL

4.4.1 Authentication & Authorization

OAuth 2.0 Implementation:

Grant Type: Client Credentials Flow (machine-to-machine)
Token Provider: Microsoft Entra ID
Token Lifetime: 1 hour
Refresh Token: 90 days
Token Format: JWT (JSON Web Token)
Algorithm: RS256 (RSA signature with SHA-256)

Required Claims in JWT:

{
  "aud": "api://eg-flow-api",
  "iss": "https://login.microsoftonline.com/{tenant}/v2.0",
  "sub": "user-object-id",
  "roles": ["Batch.Operator"],
  "organization_id": "123e4567-e89b-12d3-a456-426614174000",
  "exp": 1700226000,
  "nbf": 1700222400
}

Role Definitions & Permissions:

Acceptance Criteria:

4.4.2 Data Protection

Encryption Standards:

In Transit:
- TLS 1.3 minimum (TLS 1.2 acceptable)
- Cipher suites: AES-256-GCM, ChaCha20-Poly1305
- Certificate: Wildcard cert for *.egflow.com
- HSTS: max-age=31536000; includeSubDomains

At Rest:
- Azure Blob Storage: AES-256 (Microsoft-managed keys)
- PostgreSQL: AES-256 (Microsoft-managed keys)
- Backups: AES-256 encryption
- Customer-managed keys (CMK): Phase 2 option

Sensitive Data Fields (extra protection):
- Personnummer: Encrypted column in database (if stored)
- API keys: Azure Key Vault only
- Email passwords: Never stored
- Customer addresses: Standard blob encryption sufficient

Acceptance Criteria:

4.4.3 Application Security (OWASP Top 10)

Security Measures:

Input Validation:

// Example: Batch upload validation with FluentValidation
public class BatchUploadValidator : AbstractValidator<BatchUploadRequest>
{
    public BatchUploadValidator()
    {
        RuleFor(x => x.File)
            .NotNull().WithMessage("File is required")
            .Must(BeValidXml).WithMessage("File must be valid XML")
            .Must(BeLessThan100MB).WithMessage("File must be less than 100MB");
        
        RuleFor(x => x.Metadata.BatchName)
            .NotEmpty().WithMessage("Batch name is required")
            .Length(1, 255).WithMessage("Batch name must be 1-255 characters")
            .Must(NotContainPathSeparators).WithMessage("Batch name cannot contain / or \\")
            .Must(NoSQLInjectionPatterns).WithMessage("Invalid characters in batch name");
        
        RuleFor(x => x.Metadata.Priority)
            .Must(x => x == "normal" || x == "high")
            .WithMessage("Priority must be 'normal' or 'high'");
    }
    
    private bool NoSQLInjectionPatterns(string input)
    {
        var sqlPatterns = new[] { "--", "/*", "*/", "xp_", "sp_", "';", "\";" };
        return !sqlPatterns.Any(p => input.Contains(p, StringComparison.OrdinalIgnoreCase));
    }
}

Acceptance Criteria:

4.4.4 Network Security

Acceptance Criteria:

Dependencies:

• FluentValidation library
• OWASP dependency check tools
• Penetration testing (external vendor)
• Security code review process

Risks & Mitigation (Nordic/EU Security Context):

4.5 NFR-005: Data Retention & Lifecycle Management

Requirement: The system shall manage data retention according to Swedish accounting law (7-year invoice retention) with automated lifecycle policies for cost optimization.

Priority: HIGH

Retention Policies:

Azure Blob Lifecycle Policy:

{
  "rules": [
    {
      "enabled": true,
      "name": "invoice-lifecycle",
      "type": "Lifecycle",
      "definition": {
        "filters": {
          "blobTypes": ["blockBlob"],
          "prefixMatch": ["invoices-"]
        },
        "actions": {
          "baseBlob": {
            "tierToCool": {
              "daysAfterModificationGreaterThan": 365
            },
            "tierToArchive": {
              "daysAfterModificationGreaterThan": 2555
            },
            "delete": {
              "daysAfterModificationGreaterThan": 2920
            }
          }
        }
      }
    },
    {
      "enabled": true,
      "name": "batch-source-cleanup",
      "type": "Lifecycle",
      "definition": {
        "filters": {
          "blobTypes": ["blockBlob"],
          "prefixMatch": ["batches-"]
        },
        "actions": {
          "baseBlob": {
            "tierToCool": {
              "daysAfterModificationGreaterThan": 30
            },
            "delete": {
              "daysAfterModificationGreaterThan": 90
            }
          }
        }
      }
    }
  ]
}

Storage Growth Projection:

Assumptions:

• 10M invoices/month
• 85KB per invoice (50KB PDF + 30KB HTML + 5KB JSON)
• 7-year retention

Growth Over Time:

Storage Tier Pricing Impact:

With lifecycle policies (Hot → Cool → Archive):

• Year 1-2: Manageable with hot storage
• Year 3-7: Significant savings with tiering (estimated 85% reduction vs all-hot)

Acceptance Criteria:

Legal Hold Functionality:

{
  "invoiceId": "uuid",
  "legalHold": {
    "enabled": true,
    "reason": "Customer dispute - case #12345",
    "appliedBy": "user-uuid",
    "appliedAt": "2025-11-21T10:00:00Z",
    "expiresAt": null
  }
}

Dependencies:

• Azure Blob lifecycle management
• Legal hold tagging mechanism
• Retention compliance monitoring
• Archive tier data retrieval procedures

Risks & Mitigation (Swedish Legal Context):

4.6 NFR-006: Monitoring, Logging & Observability

Requirement: The system shall provide comprehensive monitoring through Application Insights, structured logging with Serilog, real-time dashboards with 5-minute refresh, and automated alerting with escalation procedures.

Priority: HIGH

4.6.1 Structured Logging Standards

Serilog Configuration:

Log.Logger = new LoggerConfiguration()
    .MinimumLevel.Information()
    .MinimumLevel.Override("Microsoft", LogEventLevel.Warning)
    .MinimumLevel.Override("Microsoft.AspNetCore", LogEventLevel.Warning)
    .Enrich.FromLogContext()
    .Enrich.WithProperty("Application", "EGU.Flow")
    .Enrich.WithProperty("Environment", environment)
    .Enrich.WithProperty("Region", azureRegion)
    .Enrich.WithMachineName()
    .Enrich.WithThreadId()
    .WriteTo.ApplicationInsights(
        connectionString,
        TelemetryConverter.Traces,
        LogEventLevel.Information)
    .WriteTo.Console(new CompactJsonFormatter())
    .CreateLogger();

Log Entry Structure:

{
  "timestamp": "2025-11-21T10:30:00.123Z",
  "level": "Information",
  "messageTemplate": "Batch {BatchId} processing started for organization {OrganizationId}. Items: {ItemCount}",
  "message": "Batch 550e8400... processing started for organization 123e4567.... Items: 5000",
  "properties": {
    "BatchId": "550e8400-e29b-41d4-a716-446655440000",
    "OrganizationId": "123e4567-e89b-12d3-a456-426614174000",
    "ItemCount": 5000,
    "CorrelationId": "corr-abc-123",
    "Application": "EGU.Flow",
    "Environment": "Production",
    "Region": "westeurope",
    "MachineName": "worker-001"
  }
}

PII Masking Rules:

NEVER log:
- Personnummer (Swedish social security numbers)
- Full customer names (log customer ID only)
- Email addresses (log domain only: user@***@example.se)
- Phone numbers (log prefix only: +4670****)
- Street addresses (log city only)
- Bank account numbers
- API keys or tokens

SAFE to log:
- Organization IDs (UUIDs)
- Batch IDs (UUIDs)
- Invoice IDs (UUIDs)
- Invoice numbers (business references)
- Processing statistics
- Error codes and messages
- Performance metrics

4.6.2 Application Insights Dashboards

Dashboard 1: Operations (Real-Time)

Refresh: Every 5 minutes

Metrics:

• Active batches count (gauge)
• Queue depths (4 queues, time series chart)
• Worker instance counts per service (bar chart)
• Processing throughput (items/minute, time series)
• Error rate (percentage, last hour vs last 24h)
• System health status (green/yellow/red indicators)
• Current API request rate (RPS)

Dashboard 2: Performance

Refresh: Every 5 minutes

Metrics:

• API response times (p50, p95, p99 - line chart)
• Batch processing duration (histogram)
• PDF generation times (p50, p95, p99)
• Handlebars rendering times (p50, p95, p99)
• Delivery latency by channel (email vs postal)
• Worker CPU/memory utilization
• Database query performance (slow query tracking)

Dashboard 3: Business

Refresh: Hourly

Metrics:

• Invoices processed (today, this week, this month - counters)
• Delivery channel breakdown (pie chart: email/postal)
• Failed deliveries by reason (bar chart)
• Top 10 organizations by volume (bar chart)
• Processing trends (daily invoice count, 30-day chart)
• Monthly invoice volumes (seasonal view)

Dashboard 4: Vendor Formats

Refresh: Hourly

Metrics:

• Batches by vendor format (pie chart: GASEL/XELLENT/ZYNERGY)
• Parsing success rate by vendor (percentage gauges)
• Average batch size by vendor
• Parsing duration by vendor
• Validation errors by vendor format

4.6.3 Alert Rules & Escalation

Critical Alerts (5-minute evaluation window):

Alert Delivery:

• Primary: Email to ops team distribution list
• Secondary: SMS to on-call engineer
• Escalation: PagerDuty incident creation
• Integration: Create Jira ticket automatically

On-Call Rotation:

• European team: 24/7 coverage (Swedish, Danish time zones)
• Shift schedule: Week-long rotations
• Handoff procedure: Thursday 09:00 CET

Acceptance Criteria:

Custom Metrics Tracked:

public class MetricsService
{
    private readonly TelemetryClient _telemetry;
    
    public void TrackBatchProcessing(BatchMetadata batch)
    {
        _telemetry.TrackMetric("Batch.TotalItems", 
            batch.Statistics.TotalItems,
            new Dictionary<string, string> {
                ["OrganizationId"] = batch.OrganizationId,
                ["VendorCode"] = batch.VendorInfo.VendorCode
            });
        
        _telemetry.TrackMetric("Batch.Duration", 
            (batch.Timestamps.CompletedAt - batch.Timestamps.StartedAt)?.TotalMinutes ?? 0);
        
        _telemetry.TrackMetric("Batch.SuccessRate", 
            (double)batch.Statistics.SuccessfulItems / batch.Statistics.TotalItems * 100);
    }
    
    public void TrackDelivery(string channel, bool success, string organizationId)
    {
        _telemetry.TrackMetric($"Delivery.{channel}.Success",
            success ? 1 : 0,
            new Dictionary<string, string> {
                ["OrganizationId"] = organizationId,
                ["Channel"] = channel
            });
    }
    
    public void TrackQueueDepth(string queueName, int depth)
    {
        _telemetry.TrackMetric("Queue.Depth", depth,
            new Dictionary<string, string> {
                ["QueueName"] = queueName
            });
    }
    
    public void TrackVendorParsing(string vendorCode, bool success, long durationMs)
    {
        _telemetry.TrackMetric("Parser.Duration", durationMs,
            new Dictionary<string, string> {
                ["VendorCode"] = vendorCode,
                ["Success"] = success.ToString()
            });
    }
}

Kusto Queries for Common Operations:

Query 1: Failed Batches (Last 24 Hours)

traces
| where timestamp > ago(24h)
| where customDimensions.BatchId != ""
| where severityLevel >= 3
| summarize 
    ErrorCount = count(),
    FirstError = min(timestamp),
    LastError = max(timestamp)
    by 
    BatchId = tostring(customDimensions.BatchId),
    OrganizationId = tostring(customDimensions.OrganizationId),
    ErrorMessage = message
| order by ErrorCount desc
| take 50

Query 2: Queue Depth Trending

customMetrics
| where name == "Queue.Depth"
| where timestamp > ago(24h)
| extend QueueName = tostring(customDimensions.QueueName)
| summarize 
    AvgDepth = avg(value),
    MaxDepth = max(value),
    MinDepth = min(value)
    by QueueName, bin(timestamp, 5m)
| render timechart

Query 3: Vendor Format Performance

customMetrics
| where name == "Parser.Duration"
| where timestamp > ago(7d)
| extend VendorCode = tostring(customDimensions.VendorCode)
| summarize 
    p50 = percentile(value, 50),
    p95 = percentile(value, 95),
    p99 = percentile(value, 99),
    BatchCount = count()
    by VendorCode
| order by p95 desc

Dependencies:

• Application Insights workspace (90-day retention)
• Serilog sinks for Application Insights and Console
• Alert action groups configured
• Dashboard permissions configured
• PagerDuty or similar on-call system

4.7 NFR-007: Disaster Recovery & Business Continuity

Requirement: The system shall have documented disaster recovery procedures with defined RTO/RPO targets, tested quarterly, to ensure business continuity for Nordic utility customers.

Priority: HIGH

Disaster Recovery Scenarios:

Scenario 1: Worker Instance Crash

Trigger: DocumentGenerator worker crashes during 32-item batch processing

Detection: Worker stops sending heartbeats, Azure Container Apps detects unhealthy instance

Recovery Procedure:

1. Azure Container Apps automatically starts new instance (2 min)
2. Queue message visibility timeout expires (5 min)
3. Message becomes visible in batch-items-queue again
4. New worker instance picks up message
5. Worker checks for already-processed invoices (idempotency)
6. Skips completed invoices, processes remaining items
7. Blob lease ensures no concurrent processing

RTO: < 5 minutes (automatic)
RPO: 0 (no data loss, idempotent operations)
Responsible: Automatic + Operations Manager (monitoring)

Scenario 2: PostgreSQL Database Failure

Trigger: Primary PostgreSQL instance becomes unresponsive

Detection: Health check failures, connection timeout errors in logs

Recovery Procedure:

1. Azure detects primary failure via health probes (30 seconds)
2. Auto-failover to read replica in secondary region (5 min)
3. DNS updated to point to new primary
4. Application reconnects automatically (connection retry logic)
5. Verify data integrity post-failover
6. Notify stakeholders of failover event
7. Investigate root cause

RTO: < 15 minutes
RPO: < 5 minutes (replication lag)
Responsible: Operations Manager (monitoring), DBA (verification)

Scenario 3: Azure Region Failure (West Europe)

Trigger: Complete West Europe region outage

Detection: Traffic Manager health checks fail for all West Europe endpoints

Recovery Procedure:

1. Traffic Manager detects 3 consecutive health check failures (90 seconds)
2. Traffic Manager routes all traffic to North Europe (2 min)
3. North Europe region activates read replica database as primary
4. North Europe workers process queues (messages replicated via GRS)
5. Verify system operational in North Europe
6. Communicate to customers about region failover
7. Monitor for West Europe recovery
8. Plan failback when West Europe restored

RTO: < 30 minutes
RPO: < 15 minutes (blob replication lag)
Responsible: Operations Manager (execution), CTO (decision), Communications (customer notification)

Scenario 4: Blob Storage Corruption

Trigger: Critical blob (organization config, template) becomes corrupted or accidentally deleted

Detection: Blob read errors, validation failures, user reports

Recovery Procedure:

1. Identify corrupted blob path and organization
2. Check soft delete (7-day retention):
   - If within 7 days: Undelete blob immediately
3. If soft delete expired, check blob versions:
   - Restore from previous version
4. If no versions, restore from geo-redundant copy:
   - Access secondary region blob storage
   - Copy to primary region
5. Verify restored blob integrity
6. Test with sample batch
7. Root cause analysis

RTO: < 1 hour
RPO: < 1 hour (version interval)
Responsible: Operations Manager (execution), Technical Architect (verification)

Scenario 5: Complete Data Loss (Catastrophic)

Trigger: Theoretical scenario - both regions and all backups lost

Detection: N/A (highly unlikely with Azure GRS)

Recovery Procedure:

1. Declare disaster
2. Restore PostgreSQL from geo-redundant backup (35-day retention)
3. Organizations re-upload batch files (source systems have copies)
4. Customers re-notified about invoices
5. Incident post-mortem and Azure investigation

RTO: < 4 hours
RPO: < 24 hours (last backup)
Responsible: CTO (declaration), All teams (execution)

Note: This scenario has probability < 0.001% given Azure GRS + geo-redundant backups + multi-region deployment.

Disaster Recovery Testing:

Acceptance Criteria:

4.8 NFR-008: Data Consistency (Eventual Consistency Model)

Requirement: The system shall maintain data consistency using blob leases for exclusive access, ETag-based optimistic concurrency for metadata updates, and idempotent operations for safe retries.

Priority: HIGH

Consistency Guarantees:

Strong Consistency (Within Single Operation):

• Blob lease acquisition: One worker per 32-item batch
• PostgreSQL transactions: User/role operations ACID
• Queue message delivery: At-least-once delivery

Eventual Consistency (Across System):

• Batch statistics: Updated within 30 seconds
• Invoice status: Updated within 1 minute
• Dashboard metrics: Updated within 5 minutes
• Audit logs: Written asynchronously

Consistency Mechanisms:

1. Blob Lease for Exclusive Access:

// Ensures only one worker processes 32-item batch
var lease = await AcquireBlobLeaseAsync(
    container: "{org}-batches-{year}",
    blob: "locks/{batch-id}/{message-id}.lock",
    duration: TimeSpan.FromMinutes(5));

try {
    // Process 32 invoices exclusively
    await ProcessBatchItemsAsync(message);
}
finally {
    await ReleaseBlobLeaseAsync(lease);
}

2. ETag-Based Optimistic Concurrency:

// Prevents lost updates to batch metadata
var download = await blobClient.DownloadContentAsync();
var etag = download.Value.Details.ETag;
var metadata = JsonSerializer.Deserialize<BatchMetadata>(download.Value.Content);

// Update metadata
metadata.Statistics.ProcessedItems += 32;
metadata.Metadata.UpdatedAt = DateTime.UtcNow;
metadata.Metadata.Version++;

// Upload with ETag condition
await blobClient.UploadAsync(content, new BlobUploadOptions {
    Conditions = new BlobRequestConditions { IfMatch = etag }
});
// Throws if ETag doesn't match (another worker updated)