...

• 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

1. Project Overview

1.1 Executive Summary

EG Flow is a cloud-based multi-tenant system designed for Nordic utility companies to automate invoice processing, rendering, and multi-channel delivery. The system supports multiple vendor XML formats from existing billing systems and delivers invoices through various channels including postal mail, email, and future digital mailboxes.

Strategic Context - Nordic Utilities Market:

The Nordic electricity and district heating market is characterized by:

• High digitalization: 95%+ of Swedish households have internet access
• Regulatory complexity: GDPR, Swedish Data Protection Law, energy market regulations
• Seasonal peaks: Invoice volumes concentrate in heating season (Oct-Mar)
• Multi-vendor landscape: Utilities use diverse billing systems (Telinet, Karlskoga, Zynergy, etc.)
• Print partner ecosystem: Established relationships with 21G and other postal services
• Customer expectations: Fast delivery, digital options, environmental consciousness

Primary Business Goals:

1. Reduce time-to-market for new utility company onboarding (weeks → days)
2. Automate invoice processing from batch upload to delivery (days → hours)
3. Support multi-vendor integration without custom development per client
4. Enable flexible delivery channels with automatic fallback mechanisms
5. Ensure regulatory compliance (GDPR, data residency, audit requirements)
6. Provide operational visibility with real-time batch status and metrics

Target Users:

• Primary: Utility companies (electricity, water, district heating, gas)
• Secondary: End customers receiving invoices
• Tertiary: EG system administrators and support staff
• Tertiary: Print partners (21G) receiving bulk distribution files

1.2 Project Scope

In Scope for Phase 1

✅ Multi-tenant batch invoice processing with organization data isolation
✅ Multi-vendor XML support: GASEL (Telinet), XELLENT (Karlskoga), ZYNERGY (EG Software)
✅ Template-based rendering: Handlebars templates → HTML → PDF
✅ Email delivery: SendGrid integration with retry logic
✅ Postal delivery: 21G bulk integration with SFTP file drop
✅ RESTful API: Batch management, status tracking, template management
✅ Role-based access control: 6 distinct roles with organization boundaries
✅ Real-time status tracking: Batch and invoice-level progress monitoring
✅ Application monitoring: Application Insights with structured logging (Serilog)
✅ Multi-region deployment: West Europe (Sweden/Denmark), North Europe (Norway/Finland)
✅ GDPR compliance: Data subject rights, 7-year retention, audit logging
✅ Test data strategy: Synthetic data for staging, no production data copying

Out of Scope for Phase 1

❌ Kivra digital mailbox integration (Phase 2)
❌ e-Faktura/PEPPOL electronic invoicing (Phase 2)
❌ SMS distribution via Wiraya (Phase 2)
❌ Customer self-service portal (Phase 2)
❌ Payment processing

1.3 Success Metrics

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";
}