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

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)

3. Idempotent Operations:

// Safe to retry without duplicates
public async Task ProcessInvoiceAsync(string invoiceId)
{
    // Check if already processed
    var metadata = await TryGetInvoiceMetadataAsync(invoiceId);
    if (metadata?.Status == "delivered")
    {
        _logger.LogInformation("Invoice {InvoiceId} already processed, skipping", invoiceId);
        return; // Idempotent: safe to skip
    }
    
    // Process invoice (creates new blobs, doesn't update existing)
    await RenderInvoiceAsync(invoiceId);
    await GeneratePdfAsync(invoiceId);
    await EnqueueForDeliveryAsync(invoiceId);
}

Acceptance Criteria:

Dependencies:

• Azure Blob Storage lease API
• ETag support in blob operations
• Retry logic with idempotency checks
• Worker coordination mechanisms

4.9 NFR-009: Multi-Region Data Residency (Nordic Compliance)

Requirement: The system shall enforce data residency requirements for Nordic countries, ensuring Swedish/Danish data stays in West Europe and Norwegian/Finnish data stays in North Europe, with no cross-border transfers except encrypted backups.

Priority: HIGH

Data Residency Rules:

Traffic Routing Logic:

public class RegionRoutingService
{
    public string GetProcessingRegion(string organizationId)
    {
        var org = await _orgService.GetOrganizationAsync(organizationId);
        
        // Route based on organization's country
        return org.CountryCode switch
        {
            "SE" => "westeurope",    // Sweden → West Europe
            "DK" => "westeurope",    // Denmark → West Europe
            "NO" => "northeurope",   // Norway → North Europe
            "FI" => "northeurope",   // Finland → North Europe
            _ => "westeurope"        // Default: West Europe
        };
    }
    
    public async Task<bool> ValidateDataResidencyAsync(string organizationId, string requestRegion)
    {
        var requiredRegion = GetProcessingRegion(organizationId);
        
        if (requestRegion != requiredRegion)
        {
            _logger.LogWarning(
                "Data residency violation attempted. Org: {OrgId}, Required: {Required}, Attempted: {Attempted}",
                organizationId, requiredRegion, requestRegion);
            
            return false;
        }
        
        return true;
    }
}

Organization Configuration:

{
  "organizationId": "uuid",
  "organizationCode": "VATTENFALL-SE",
  "countryCode": "SE",
  "dataResidency": {
    "primaryRegion": "westeurope",
    "allowedRegions": ["westeurope"],
    "backupRegions": ["northeurope"],
    "crossRegionProcessing": false,
    "crossRegionBackup": true
  }
}

Acceptance Criteria:

Dependencies:

• Azure Traffic Manager with geographic routing
• Blob storage geo-redundant replication
• Organization configuration enforcement
• Multi-region deployment automation

Risks & Mitigation (Nordic Legal Context):

4.10 NFR-010: Maintainability & Code Quality

Requirement: The system shall be designed for long-term maintainability with clear code standards, comprehensive documentation, high test coverage, and adherence to .NET best practices.

Priority: MEDIUM

Code Quality Standards:

Project Structure (Updated per Oct 27 decision):

EGU.Flow/
├── EGU.Flow.AppHost/                    # .NET Aspire orchestration
│   └── Program.cs
│
├── EGU.Flow.Core/                       # Shared contracts, DTOs, interfaces
│   ├── DTOs/
│   │   ├── BatchUploadRequest.cs
│   │   ├── CanonicalInvoice.cs
│   │   └── DeliveryRequest.cs
│   ├── Enums/
│   │   ├── BatchStatus.cs
│   │   ├── DeliveryChannel.cs
│   │   └── VendorCode.cs
│   ├── Interfaces/
│   │   ├── IXmlParserService.cs
│   │   ├── ITemplateRenderingService.cs
│   │   └── IDeliveryService.cs
│   └── Common/
│       ├── Constants.cs
│       └── ErrorCodes.cs
│
├── EGU.Flow.Domain/                     # Domain models and business logic
│   ├── Models/
│   │   ├── Organization.cs
│   │   ├── Batch.cs
│   │   ├── BatchItem.cs
│   │   ├── Template.cs
│   │   └── TemplateCategory.cs
│   └── DomainServices/
│       ├── VendorDetectionService.cs
│       └── DistributionRoutingService.cs
│
├── EGU.Flow.BusinessLogic/              # Business services
│   ├── Services/
│   │   ├── BatchService.cs
│   │   ├── OrganizationService.cs
│   │   ├── TemplateService.cs
│   │   └── SchemaRegistryService.cs
│   └── Mappers/
│       ├── GaselMapper.cs
│       ├── XellentMapper.cs
│       └── ZynergyMapper.cs
│
├── EGU.Flow.CoreApiService/             # ASP.NET Core REST API
│   ├── Controllers/
│   │   ├── BatchController.cs
│   │   ├── OrganizationController.cs
│   │   ├── TemplateController.cs
│   │   └── SchemaController.cs
│   ├── Middleware/
│   │   ├── OrganizationContextMiddleware.cs
│   │   ├── ErrorHandlingMiddleware.cs
│   │   └── RequestLoggingMiddleware.cs
│   └── Program.cs
│
├── EGU.Flow.ParserService/              # Console app: XML → JSON
│   ├── Workers/
│   │   └── BatchParserWorker.cs
│   ├── Parsers/
│   │   ├── GaselParser.cs
│   │   ├── XellentParser.cs
│   │   └── ZynergyParser.cs
│   └── Program.cs
│
├── EGU.Flow.DocumentGenerator/          # Console app: JSON → PDF
│   ├── Workers/
│   │   └── DocumentGeneratorWorker.cs
│   ├── Services/
│   │   ├── HandlebarsRenderingService.cs
│   │   └── PlaywrightPdfService.cs
│   └── Program.cs
│
├── EGU.Flow.EmailService/               # Console app: Email delivery
│   ├── Workers/
│   │   └── EmailDeliveryWorker.cs
│   └── Program.cs
│
├── EGU.Flow.PostalService/              # Console app: 21G integration
│   ├── Workers/
│   │   └── PostalBulkProcessor.cs
│   ├── Services/
│   │   ├── SftpService.cs
│   │   └── ZipArchiveService.cs
│   └── Program.cs
│
├── EGU.Flow.Web/                        # Future: Blazor UI
│   └── (Phase 2)
│
└── EGU.Flow.Tests/                      # Test projects
    ├── EGU.Flow.UnitTests/
    ├── EGU.Flow.IntegrationTests/
    └── EGU.Flow.LoadTests/

Coding Standards:

• Style: Follow Microsoft C# coding conventions
• Naming: PascalCase for public members, camelCase for private
• Comments: XML documentation on all public APIs
• Async: Always use async/await, never .Result or .Wait()
• Logging: Structured logging with Serilog, correlation IDs
• Exceptions: Custom exception types, never swallow exceptions
• Null safety: Use nullable reference types (C# 12)

Acceptance Criteria:

Documentation Requirements:

Dependencies:

• EditorConfig file in repository
• Roslyn analyzer NuGet packages
• SonarQube or similar code quality tool
• Documentation review in PR process

4.11 NFR-011: Usability & Developer Experience

Requirement: The API shall be intuitive, well-documented, easy to integrate, with clear error messages, code samples, and Postman collections.

Priority: MEDIUM

API Design Principles:

RESTful Standards:

• Resource-based URLs: /organizations/{id}/batches
• HTTP verbs: GET (read), POST (create), PUT (update), DELETE (not used Phase 1)
• Status codes: 200 OK, 201 Created, 202 Accepted, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict, 422 Unprocessable Entity, 429 Too Many Requests, 500 Internal Error, 503 Service Unavailable
• Consistent JSON response envelope
• Pagination for list endpoints
• Filtering and sorting support

Error Message Quality:

Bad Example:

{
  "error": "Invalid input"
}

Good Example:

{
  "success": false,
  "errors": [
    {
      "code": "INVALID_XML",
      "message": "XML file is not well-formed",
      "field": "file",
      "details": {
        "line": 142,
        "column": 23,
        "error": "Unexpected end tag: </Invoice>. Expected: </InvoiceHeader>",
        "suggestion": "Check that all opening tags have matching closing tags in the correct order",
        "documentationUrl": "https://docs.egflow.com/errors/INVALID_XML"
      }
    }
  ]
}

Acceptance Criteria:

Postman Collection Contents:

EG Flow API Collection/
├── Authentication/
│   └── Get Access Token
├── Batch Management/
│   ├── Upload Batch
│   ├── Start Batch Processing
│   ├── Get Batch Status
│   ├── List Batch Items
│   └── Get Batch Item Details
├── Organization/
│   ├── Get Organization
│   └── Update Organization Config
├── Templates/
│   ├── List Templates
│   ├── Get Template
│   └── List Template Categories
└── Schema Management/
    ├── List Supported Formats
    └── Validate XML

Dependencies:

• OpenAPI/Swagger generator
• Postman collection export
• Documentation website/portal
• Code sample generation

4.12 NFR-012: Internationalization (Nordic Languages)

Requirement: The system shall support Swedish language for invoices, email notifications, error messages, and UI elements, with foundation for future Norwegian, Danish, and Finnish support.

Priority: MEDIUM

Localization Requirements:

Phase 1: Swedish Only

• Invoice templates: Swedish text
• Email notifications: Swedish
• Error messages: Swedish (with English fallback in details)
• Date formats: YYYY-MM-DD (ISO 8601, universal)
• Number formats: Space as thousand separator, comma as decimal (Swedish standard)
  • Example: 1 234 567,89 kr
• Currency: SEK (Swedish Krona)
• Time zone: CET/CEST (Europe/Stockholm)

Phase 2: Multi-Language (Future)

• Norwegian (Bokmål): For Norwegian utilities
• Danish: For Danish utilities
• Finnish: For Finnish utilities
• Language detection based on organization country

Swedish-Specific Formatting:

Dates:
- Invoice date: "2025-11-21" (ISO format, universal)
- Display: "21 november 2025" (Swedish long format)

Numbers:
- Amount: 1 234,56 (space separator, comma decimal)
- Percentage: 25,0% (comma decimal)
- Quantity: 1 234 (integer, space separator)

Currency:
- Symbol: "kr" or "SEK"
- Position: After amount "1 234,56 kr"

Swedish Terms:
- Faktura (Invoice)
- Förfallodatum (Due date)
- Mätpunkt (Metering point)
- Elförbrukning (Electricity consumption)
- Att betala (Amount to pay)
- Moms (VAT)

Handlebars Helpers for Swedish Formatting:

{{!-- Swedish number formatting --}}
{{formatNumber amount decimals=2}}
→ "1 234,56"

{{!-- Swedish currency --}}
{{formatCurrency amount}}
→ "1 234,56 kr"

{{!-- Swedish date --}}
{{formatDate date format="long"}}
→ "21 november 2025"

{{!-- Swedish percentage --}}
{{formatPercent rate}}
→ "25,0%"

Acceptance Criteria:

Dependencies:

• Swedish localization resources
• Handlebars custom helpers
• PDF font with Swedish character support
• Future: i18n library for multi-language

4.13 NFR-013: API Backward Compatibility

Requirement: API versions shall maintain backward compatibility for minimum 12 months after new version release, with clear deprecation warnings and migration guides.

Priority: HIGH

Versioning Strategy:

URL Path Versioning:

Current: https://api.egflow.com/v1/organizations/{id}/batches
Future: https://api.egflow.com/v2/organizations/{id}/batches

Both versions run simultaneously during transition period

Version Lifecycle:

v1.0 Released: January 2026
  ↓
v2.0 Released: January 2027
  ↓ (v1 deprecation announced)
v1 Supported: Until January 2028 (12 months)
  ↓
v1 Sunset: January 2028

Deprecation Warning (HTTP Header):

HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 31 Jan 2028 23:59:59 GMT
Link: <https://docs.egflow.com/api/v2/migration>; rel="successor-version"

Acceptance Criteria:

5. Data Flow Diagrams

5.1 High-Level System Data Flow

┌─────────────────────────────────────────────────────────────────┐
│                     EG Flow Complete Data Flow                   │
└─────────────────────────────────────────────────────────────────┘

External System                    EG Flow System (Azure)
(Utility Billing)                                    
      │                                              
      │  1. Generate monthly                         
      │     invoice batch (XML)                      
      │                                              
      ├──────────────────────────────────────────>  
      │     POST /batches                    ┌──────────────┐
      │     (GASEL/XELLENT/ZYNERGY XML)      │  Core API    │
      │                                      │  Service     │
      │                                      │              │
      │                                      │ • Auth check │
      │                                      │ • Validate   │
      │                                      │ • Store blob │
      │                                      └──────┬───────┘
      │                                             │
      │  2. Return Batch ID                         │
      │<────────────────────────────────────────────┤
      │     {batchId, status: "uploaded"}           │
      │                                             │
      │  3. Start Processing                        │
      ├──────────────────────────────────────────> │
      │     POST /batches/{id}/start                │
      │                                             │
      │                                      ┌──────▼───────┐
      │                                      │  Blob        │
      │                                      │  Storage     │
      │                                      │              │
      │                                      │ {org}-batches│
      │                                      │ /2025/11/21/ │
      │                                      └──────┬───────┘
      │                                             │
      │  4. 202 Accepted (queued)                   │
      │<────────────────────────────────────────────┤
      │                                             │
      │                                      ┌──────▼────────┐
      │                                      │  Storage      │
      │                                      │  Queues       │
      │                                      │               │
      │                                      │ • batch-upload│
      │                                      │ • batch-items │
      │                                      │ • email       │
      │                                      │ • postal-bulk │
      │                                      └───────┬───────┘
      │                                              │
      │                              ┌───────────────┼──────────────┐
      │                              │               │              │
      │                       ┌──────▼─────┐  ┌─────▼──────┐ ┌─────▼──────┐
      │                       │  Parser    │  │ Document   │ │  Email     │
      │                       │  Service   │  │ Generator  │ │  Service   │
      │                       │            │  │            │ │            │
      │                       │ • Detect   │  │ • Render   │ │ • SendGrid │
      │                       │ • Validate │  │ • PDF gen  │ │ • Retry    │
      │                       │ • Parse    │  │ • Store    │ │ • Fallback │
      │                       │ • Transform│  │            │ │            │
      │                       └──────┬─────┘  └─────┬──────┘ └─────┬──────┘
      │                              │              │              │
      │                       Creates 157    Creates PDFs    Sends emails
      │                       JSON files    & queues         │
      │                       (5000/32)     delivery         │
      │                              │              │              │
      │                              ▼              ▼              ▼
      │                       ┌──────────────────────────────────────┐
      │                       │         Blob Storage                 │
      │                       │                                      │
      │                       │ {org}-invoices-2025/11/21/          │
      │                       │ ├── {id}.json (canonical data)      │
      │                       │ ├── {id}.html (rendered)            │
      │                       │ └── {id}.pdf (final invoice)        │
      │                       └──────────────────────────────────────┘
      │                                              │
      │  5. Poll Status                              │
      │     GET /batches/{id}                        │
      ├──────────────────────────────────────────> │
      │                                             │
      │  6. Status Response                         │
      │<────────────────────────────────────────────┤
      │     {status: "processing",                  │
      │      processedItems: 3200/5000}             │
      │                                             │
      │  7. Status: Completed                       │
      │<────────────────────────────────────────────┤
      │     {status: "completed",                   │
      │      successfulItems: 4950,                 │
      │      failedItems: 50}                       │
      │                                             │
      │                                      ┌──────▼─────┐
      │                                      │  Postal    │
      │                                      │  Service   │
      │                                      │            │
      │                                      │ • Collect  │
      │                                      │ • Create ZIP│
      │                                      │ • 21G SFTP │
      │                                      └──────┬─────┘
      │                                             │
End Customer                                        │
      │                                             │
      │  8a. Receive Email                          │
      │<────────────────────────────────────────────┤
      │      (PDF attachment)                       │
      │                                             │
      │  8b. Receive Postal                         │
      │<────────────────────────────────────────────┤
      │      (via 21G print partner)                │

5.2 Batch Upload Flow

┌─────────────────────────────────────────────────────────────┐
│                    Batch Upload Data Flow                    │
└─────────────────────────────────────────────────────────────┘

Client                 API Gateway           Core API              Blob Storage
  │                         │                    │                      │
  ├─ POST /batches ────────>│                    │                      │
  │  (XML file)             │                    │                      │
  │                         ├─ Authenticate ────>│                      │
  │                         │  (Entra ID)        │                      │
  │                         │<─ JWT Valid ───────┤                      │
  │                         │                    │                      │
  │                         ├─ Authorize ───────>│                      │
  │                         │  (Check role)      │                      │
  │                         │<─ Access OK ───────┤                      │
  │                         │                    │                      │
  │                         ├─ Upload File ─────>│                      │
  │                         │                    ├─ Generate UUID ─────>│
  │                         │                    │  (Batch ID)          │
  │                         │                    │                      │
  │                         │                    ├─ Store XML ─────────>│
  │                         │                    │  {org}-batches-2025/ │
  │                         │                    │  11/21/{id}/source.xml│
  │                         │                    │<─ Stored ────────────┤
  │                         │                    │                      │
  │                         │                    ├─ Quick Detect ───────>│
  │                         │                    │  (Namespace peek)    │
  │                         │                    │<─ Format: GASEL ─────┤
  │                         │                    │                      │
  │                         │                    ├─ Create Metadata ───>│
  │                         │                    │  metadata.json       │
  │                         │                    │<─ Created ───────────┤
  │                         │                    │                      │
  │                         │<─ 201 Created ─────┤                      │
  │                         │  {batchId}         │                      │
  │<─ 201 Created ──────────┤                    │                      │
  │  {batchId, status}      │                    │                      │

5.3 Parser Service Detailed Flow (XML → JSON)

┌──────────────────────────────────────────────────────────────┐
│           Parser Service: XML → Canonical JSON Flow          │
└──────────────────────────────────────────────────────────────┘

Queue Message         Parser Service              Blob Storage
      │                     │                          │
      ├─ {batchId} ────────>│                          │
      │                     │                          │
      │                     ├─ Download XML ──────────>│
      │                     │  GET {org}-batches-2025/ │
      │                     │      11/21/{id}/source.xml│
      │                     │<─ XML Content ───────────┤
      │                     │                          │
      │                     ├─ Parse Root Namespace   │
      │                     │  xmlns="urn:ediel:..."   │
      │                     │  → Detected: GASEL       │
      │                     │                          │
      │                     ├─ Load Schema ───────────>│
      │                     │  GET {org}-data/schemas/ │
      │                     │      gasel-mapping.json  │
      │                     │<─ Mapping Config ────────┤
      │                     │                          │
      │                     ├─ Load XSD ──────────────>│
      │                     │  GET {org}-data/schemas/ │
      │                     │      gasel-v1.0.xsd      │
      │                     │<─ XSD Content ───────────┤
      │                     │                          │
      │                     ├─ Validate XML            │
      │                     │  Against XSD             │
      │                     │  Result: VALID           │
      │                     │                          │
      │                     ├─ Parse XML (XPath)       │
      │                     │  Extract Invoice[1]:     │
      │                     │   InvoiceNumber =        │
      │                     │     "2025-11-001"        │
      │                     │   CustomerName =         │
      │                     │     "Medeni Schröder"    │
      │                     │   TotalAmount = 749.28   │
      │                     │  ... (all fields)        │
      │                     │                          │
      │                     ├─ Transform to Canonical  │
      │                     │  {                       │
      │                     │    invoiceNumber,        │
      │                     │    invoiceDate,          │
      │                     │    customer: {...},      │
      │                     │    invoiceDetails: {...},│
      │                     │    delivery: {...},      │
      │                     │    sourceMetadata: {     │
      │                     │      vendorCode: "GASEL" │
      │                     │    }                     │
      │                     │  }                       │
      │                     │                          │
      │                     ├─ LOOP: All 5000 invoices│
      │                     │                          │
      │                     ├─ Store JSON (5000×) ───>│
      │                     │  PUT {org}-invoices-2025/│
      │                     │      11/21/{inv-id}.json │
      │                     │<─ Stored (5000×) ────────┤
      │                     │                          │
      │                     ├─ Group into 32-batches  │
      │                     │  5000 ÷ 32 = 157 batches │
      │                     │                          │
      │                     ├─ Enqueue 157 Messages   │
      │                     │  TO batch-items-queue    │
      │                     │  Each: 32 invoice IDs    │
      │                     │                          │
      │                     ├─ Update Batch Metadata ─>│
      │                     │  PUT {org}-batches-2025/ │
      │                     │      11/21/{id}/         │
      │                     │      metadata.json       │
      │                     │  {                       │
      │                     │    totalItems: 5000,     │
      │                     │    vendorCode: "GASEL",  │
      │                     │    status: "processing"  │
      │                     │  }                       │
      │                     │<─ Updated ───────────────┤
      │                     │                          │
      │<─ ACK (delete msg)──┤                          │
      │                     │                          │

5.4 Document Generator Flow (JSON → HTML → PDF)

┌──────────────────────────────────────────────────────────────┐
│        Document Generator: JSON → HTML → PDF Flow            │
└──────────────────────────────────────────────────────────────┘

Queue Message         Document Generator         Blob Storage
      │                     │                          │
      ├─ 32 Invoice IDs ───>│                          │
      │                     │                          │
      │                     ├─ Acquire Blob Lease ────>│
      │                     │  Lease: {batch}/locks/   │
      │                     │         {worker-id}.lock │
      │                     │<─ Lease Acquired ────────┤
      │                     │  (5 min duration)        │
      │                     │                          │
      │                     ├─ LOOP: 32 invoices      │
      │                     │                          │
      │                     ├─ Download JSON ─────────>│
      │                     │  GET {org}-invoices-2025/│
      │                     │      11/21/{id}.json     │
      │                     │<─ Canonical Invoice ─────┤
      │                     │                          │
      │                     ├─ Load Org Config ───────>│
      │                     │  GET {org}-data/         │
      │                     │      organization.json   │
      │                     │<─ Branding, Settings ────┤
      │                     │                          │
      │                     ├─ Determine Template      │
      │                     │  Category (invoice type) │
      │                     │  → "invoice"             │
      │                     │                          │
      │                     ├─ Load Template ─────────>│
      │                     │  GET {org}-data/         │
      │                     │      templates/invoice/  │
      │                     │      active.html         │
      │                     │<─ Handlebars Template ───┤
      │                     │                          │
      │                     ├─ Compile Template        │
      │                     │  (cache 24h if not cached)│
      │                     │  Handlebars.Compile()    │
      │                     │                          │
      │                     ├─ Render HTML             │
      │                     │  Apply invoice data      │
      │                     │  + organization branding │
      │                     │  Output: HTML string     │
      │                     │  Duration: ~1-2 seconds  │
      │                     │                          │
      │                     ├─ Generate PDF            │
      │                     │  Playwright.NewPage()    │
      │                     │  SetContentAsync(html)   │
      │                     │  PdfAsync(A4, margins)   │
      │                     │  Duration: ~3-5 seconds  │
      │                     │                          │
      │                     ├─ Store HTML ────────────>│
      │                     │  PUT {org}-invoices-2025/│
      │                     │      11/21/{id}.html     │
      │                     │<─ Stored ────────────────┤
      │                     │                          │
      │                     ├─ Store PDF ─────────────>│
      │                     │  PUT {org}-invoices-2025/│
      │                     │      11/21/{id}.pdf      │
      │                     │<─ Stored ────────────────┤
      │                     │                          │
      │                     ├─ Update Invoice JSON ───>│
      │                     │  Add fileReferences,     │
      │                     │  templateInfo, timestamp │
      │                     │<─ Updated ───────────────┤
      │                     │                          │
      │                     ├─ Determine Distribution  │
      │                     │  Has email? → email-queue│
      │                     │  Else → postal-bulk-queue│
      │                     │                          │
      │                     ├─ Enqueue Delivery        │
      │                     │  TO email-queue OR       │
      │                     │  TO postal-bulk-queue    │
      │                     │                          │
      │                     │  (END OF 32 ITEMS LOOP)  │
      │                     │                          │
      │                     ├─ Release Blob Lease ────>│
      │                     │<─ Lease Released ────────┤
      │                     │                          │
      │                     ├─ Update Batch Stats ────>│
      │                     │  (ETag concurrency)      │
      │                     │  processedItems += 32    │
      │                     │<─ Updated ───────────────┤
      │                     │                          │
      │<─ ACK (delete msg)──┤                          │

5.5 Email Delivery Flow

┌──────────────────────────────────────────────────────────┐
│              Email Delivery Service Flow                  │
└──────────────────────────────────────────────────────────┘

email-queue      Email Service      SendGrid API      Blob Storage
      │                │                  │                │
      ├─ {invoiceId} ─>│                  │                │
      │                │                  │                │
      │                ├─ Download PDF ──────────────────>│
      │                │  GET {org}-invoices-2025/11/21/  │
      │                │      {invoice-id}.pdf            │
      │                │<─ PDF Bytes ────────────────────┤
      │                │                  │                │
      │                ├─ Load Org Config ───────────────>│
      │                │  GET {org}-data/organization.json│
      │                │<─ Email settings ───────────────┤
      │                │                  │                │
      │                ├─ Create Email    │                │
      │                │  From: noreply@org.se           │
      │                │  To: customer@example.se        │
      │                │  Subject: "Faktura XXX"         │
      │                │  Attach: PDF                    │
      │                │                  │                │
      │                ├─ Send Email ────>│                │
      │                │  POST /v3/mail/send             │
      │                │                  │                │
      │                │                  ├─ Process       │
      │                │                  │  (SendGrid)    │
      │                │                  │                │
      │                │<─ 202 Accepted ──┤                │
      │                │  {messageId}     │                │
      │                │                  │                │
      │                ├─ Update Metadata ───────────────>│
      │                │  deliveryAttempts.push({        │
      │                │    channel: "email",            │
      │                │    status: "delivered",         │
      │                │    messageId,                   │
      │                │    timestamp                    │
      │                │  })                             │
      │                │<─ Updated ──────────────────────┤
      │                │                  │                │
      │<─ ACK (delete)─┤                  │                │
      │                │                  │                │
      │                                                    │
      │  IF SENDGRID FAILS (429 Rate Limit):              │
      │                │                  │                │
      │                │<─ 429 Too Many ──┤                │
      │                │  Retry-After: 60s│                │
      │                │                  │                │
      │                ├─ Re-queue Message                │
      │<─ Re-enqueue ──┤  visibilityTimeout=60s           │
      │  (retry)       │                  │                │
      │                                                    │
      │  IF ALL RETRIES FAIL → FALLBACK TO POSTAL:        │
      │                │                  │                │
      │                ├─ Enqueue to postal-bulk-queue    │
      │                │  (fallback delivery)              │

5.6 Postal Bulk Processing Flow (21G Integration)

┌──────────────────────────────────────────────────────────┐
│      Postal Bulk Service: 21G Integration Flow           │
└──────────────────────────────────────────────────────────┘

Scheduled Trigger    Postal Service       21G SFTP         Blob Storage
(12:00, 20:00 CET)         │                  │                │
      │                    │                  │                │
      ├─ CRON Trigger ────>│                  │                │
      │                    │                  │                │
      │                    ├─ Fetch All Messages from         │
      │                    │  postal-bulk-queue               │
      │                    │  (batch retrieval)               │
      │                    │  Result: 150 invoices            │
      │                    │                  │                │
      │                    ├─ Group by Organization          │
      │                    │  Org A: 100 invoices            │
      │                    │  Org B: 50 invoices             │
      │                    │                  │                │
      │                    ├─ FOR Org A:      │                │
      │                    │                  │                │
      │                    ├─ Download 100 PDFs ────────────>│
      │                    │  GET {org-a}-invoices-2025/     │
      │                    │      11/21/{id}.pdf             │
      │                    │<─ PDF Bytes (100×) ─────────────┤
      │                    │                  │                │
      │                    ├─ Create 21G XML Metadata       │
      │                    │  <PrintBatch>                   │
      │                    │    <TotalDocuments>100          │
      │                    │    <Documents>                  │
      │                    │      <Document>                 │
      │                    │        <DocumentId>001.pdf      │
      │                    │        <Recipient>              │
      │                    │          <Name>...</Name>       │
      │                    │          <Address>...</Address>  │
      │                    │                  │                │
      │                    ├─ Create ZIP Archive            │
      │                    │  ORGA_20251121_001.zip          │
      │                    │  ├── metadata.xml               │
      │                    │  ├── invoice_001.pdf            │
      │                    │  ├── invoice_002.pdf            │
      │                    │  └── ... (100 PDFs)             │
      │                    │                  │                │
      │                    ├─ Upload to 21G ─>│                │
      │                    │  SFTP PUT        │                │
      │                    │  /incoming/ORGA/ │                │
      │                    │  ORGA_20251121_  │                │
      │                    │  001.zip         │                │
      │                    │<─ Upload Success ┤                │
      │                    │                  │                │
      │                    ├─ Update Invoice Statuses ──────>│
      │                    │  (100 invoices)                 │
      │                    │  status="postal_sent"           │
      │                    │<─ Updated (100×) ───────────────┤
      │                    │                  │                │
      │                    ├─ Delete Queue Messages          │
      │                    │  (100 messages from queue)      │
      │                    │                  │                │
      │                    ├─ Send Notification Email       │
      │                    │  To: ops@org-a.com              │
      │                    │  Subject: "21G Batch Sent"      │
      │                    │  Body: "100 invoices"           │
      │                    │                  │                │
      │                    ├─ Log to App Insights            │
      │                    │  Metric: Postal.BatchSize=100   │

5.7 Error Handling & Retry Flow

┌─────────────────────────────────────────────────────────┐
│          Error Handling & Retry Flow Diagram            │
└─────────────────────────────────────────────────────────┘

Processing      Error Occurs       Retry Logic        Final State
    │                │                  │                  │
    ├─ Render HTML   │                  │                  │
    │                X                  │                  │
    │           Template error          │                  │
    │           (missing variable)      │                  │
    │                │                  │                  │
    │                ├─ Log Error ─────>│                  │
    │                │  Application     │                  │
    │                │  Insights        │                  │
    │                │  Level: Error    │                  │
    │                │  CorrelationId   │                  │
    │                │                  │                  │
    │                ├─ Increment ─────>│                  │
    │                │  retryCount=1    │                  │
    │                │                  │                  │
    │                ├─ Retry Attempt 1 │                  │
    │                │  Wait: 60 seconds│                  │
    │                X Still fails      │                  │
    │                │                  │                  │
    │                ├─ Increment ─────>│                  │
    │                │  retryCount=2    │                  │
    │                │                  │                  │
    │                ├─ Retry Attempt 2 │                  │
    │                │  Wait: 5 minutes │                  │
    │                X Still fails      │                  │
    │                │                  │                  │
    │                ├─ Increment ─────>│                  │
    │                │  retryCount=3    │                  │
    │                │                  │                  │
    │                ├─ Retry Attempt 3 │                  │
    │                │  Wait: 15 minutes│                  │
    │                X Still fails      │                  │
    │                │                  │                  │
    │                ├─ Max Retries ───────────────────────>│
    │                │  Exceeded        │           poison-queue
    │                │                  │                  │
    │                ├─ Create Poison ─────────────────────>│
    │                │  Message with:   │           {      │
    │                │  • Original msg  │    retryCount: 3 │
    │                │  • All errors    │    lastError     │
    │                │  • Timestamps    │    alertSent     │
    │                │                  │   }              │
    │                │                  │                  │
    │                ├─ Send Alert ────────────────────────>│
    │                │  Email to:       │    support@egflow.com
    │                │  support team    │    Subject: "Poison Queue"
    │                │                  │                  │
    │                ├─ Update Batch ──────────────────────>│
    │                │  failedItems++   │    Batch metadata
    │                │  errors.push()   │    updated
      │                │                  │                  │
      │<─ Delete from ─┤                  │                  │
      │   main queue   │                  │                  │

5.8 Multi-Vendor Transformation Flow

┌──────────────────────────────────────────────────────────┐
│     Multi-Vendor XML → Canonical JSON Transformation     │
└──────────────────────────────────────────────────────────┘

GASEL XML                     Parser                  Canonical JSON
    │                            │                          │
<InvoiceBatch                     │                          │
 xmlns="urn:ediel:...">           │                          │
  <Invoice>                       │                          │
    <InvoiceHeader>               │                          │
      <InvoiceNumber>             │                          │
        2025-11-001               │                          │
      </InvoiceNumber>            │                          │
    <CustomerParty>               │                          │
      <PartyName>                 │                          │
        Medeni Schröder           │                          │
      </PartyName>                │                          │
    <MonetarySummary>             │                          │
      <PayableAmount>             │                          │
        749.28                    │                          │
      </PayableAmount>            │                          │
    ├────────────────────────────>│                          │
    │                            ├─ Detect: GASEL           │
    │                            │  (namespace match)       │
    │                            │                          │
    │                            ├─ Load Mapping ──────────>│
    │                            │  gasel-mapping.json      │
    │                            │                          │
    │                            ├─ Extract via XPath:     │
    │                            │  invoiceNumber =         │
    │                            │    "InvoiceHeader/       │
    │                            │     InvoiceNumber"       │
    │                            │  customerName =          │
    │                            │    "CustomerParty/       │
    │                            │     PartyName"           │
    │                            │                          │
    │                            ├─ Transform ─────────────>│
    │                            │                  {       │
    │                            │    "invoiceNumber": "2025-11-001",
    │                            │    "customer": {
    │                            │      "fullName": "Medeni Schröder"
    │                            │    },
    │                            │    "invoiceDetails": {
    │                            │      "totalAmount": 749.28
    │                            │    },
    │                            │    "sourceMetadata": {
    │                            │      "vendorCode": "GASEL"
    │                            │    }
    │                            │  }

XELLENT XML                   Parser                  Canonical JSON
    │                            │                          │
<InvoiceBatch                     │                          │
 xmlns="http://oio.dk..."         │                          │
 xmlns:com="...common">           │                          │
  <Invoice>                       │                          │
    <com:ID>                      │                          │
      5002061556                  │                          │
    </com:ID>                    │                          │
    <com:BuyerParty>             │                          │
      <com:PartyName>            │                          │
        <com:Name>               │                          │
          Erik Svensson          │                          │
        </com:Name>              │                          │
    <com:LegalTotals>            │                          │
      <com:ToBePaidTotalAmount>  │                          │
        2 567,00                 │                          │
    ├────────────────────────────>│                          │
    │                            ├─ Detect: XELLENT        │
    │                            │  (oio.dk namespace)      │
    │                            │                          │
    │                            ├─ Load Mapping           │
    │                            │  xellent-mapping.json    │
    │                            │                          │
    │                            ├─ Handle Namespaces      │
    │                            │  (com:, main: prefixes)  │
    │                            │                          │
    │                            ├─ Extract via XPath:     │
    │                            │  invoiceNumber = "com:ID"│
    │                            │  customerName =          │
    │                            │    "com:BuyerParty/      │
    │                            │     com:PartyName/       │
    │                            │     com:Name"            │
    │                            │                          │
    │                            ├─ Normalize Amount:      │
    │                            │  "2 567,00" → 2567.00    │
    │                            │                          │
    │                            ├─ Transform ─────────────>│
    │                            │                  {       │
    │                            │    "invoiceNumber": "5002061556",
    │                            │    "customer": {
    │                            │      "fullName": "Erik Svensson"
    │                            │    },
    │                            │    "invoiceDetails": {
    │                            │      "totalAmount": 2567.00
    │                            │    },
    │                            │    "sourceMetadata": {
    │                            │      "vendorCode": "XELLENT"
    │                            │    }
    │                            │  }

ZYNERGY XML                   Parser                  Canonical JSON
    │                            │                          │
<InvoiceBatch                     │                          │
 xmlns="http://eg.dk/Zynergy">    │                          │
  <Invoice>                       │                          │
    <InvoiceData>                 │                          │
      <InvoiceNumber>             │                          │
        100000                    │                          │
      </InvoiceNumber>            │                          │
    <Customer>                    │                          │
      <ReadOnlyFullName>          │                          │
        Alfred Asplund            │                          │
      </ReadOnlyFullName>         │                          │
    <InvoiceData>                 │                          │
      <InvoiceAmount>             │                          │
        1056.00                   │                          │
    ├────────────────────────────>│                          │
    │                            ├─ Detect: ZYNERGY        │
    │                            │  (Zynergy namespace)     │
    │                            │                          │
    │                            ├─ Load Mapping           │
    │                            │  zynergy-mapping.json    │
    │                            │                          │
    │                            ├─ Extract via XPath:     │
    │                            │  invoiceNumber =         │
    │                            │    "InvoiceData/         │
    │                            │     InvoiceNumber"       │
    │                            │  customerName =          │
    │                            │    "Customer/            │
    │                            │     ReadOnlyFullName"    │
    │                            │                          │
    │                            ├─ Transform ─────────────>│
    │                            │                  {       │
    │                            │    "invoiceNumber": "100000",
    │                            │    "customer": {
    │                            │      "fullName": "Alfred Asplund"
    │                            │    },
    │                            │    "invoiceDetails": {
    │                            │      "totalAmount": 1056.00
    │                            │    },
    │                            │    "sourceMetadata": {
    │                            │      "vendorCode": "ZYNERGY"
    │                            │    }
    │                            │  }
                                 │                          │
                            All 3 formats           Single standard
                            produce same      ───>   canonical JSON
                            structure                for downstream

5.9 Distribution Routing Decision Flow

┌─────────────────────────────────────────────────────────┐
│         Distribution Channel Routing Logic              │
└─────────────────────────────────────────────────────────┘

Invoice Data          Routing Logic             Queue Selection
      │                     │                          │
      ├─ Check Customer    │                          │
      │  Preference         │                          │
      │                     │                          │
      │  preference=        │                          │
      │  "postal"? ─────────┤                          │
      │                     ├─ YES ───────────────────>│
      │                     │                   postal-bulk-queue
      │                     │                          │
      │                     ├─ NO                      │
      │                     │  Continue...             │
      │                     │                          │
      ├─ Load Org          │                          │
      │  Channel Priority   │                          │
      │  [email, postal]    │                          │
      │                     │                          │
      │                     ├─ TRY Priority 1: email  │
      │                     │                          │
      ├─ Has email         │                          │
      │  address?           │                          │
      │                     │                          │
      │  email != null? ────┤                          │
      │                     ├─ YES                     │
      │                     │  Validate email format   │
      │                     │                          │
      │  valid email? ──────┤                          │
      │                     ├─ YES ───────────────────>│
      │                     │                   email-queue
      │                     │                          │
      │                     ├─ NO (invalid/missing)    │
      │                     │  Try next channel...     │
      │                     │                          │
      │                     ├─ TRY Priority 2: postal │
      │                     │                          │
      ├─ Complete          │                          │
      │  address?           │                          │
      │                     │                          │
      │  address valid? ────┤                          │
      │                     ├─ YES ───────────────────>│
      │                     │                   postal-bulk-queue
      │                     │                          │
      │                     ├─ NO (incomplete)         │
      │                     │  Log error               │
      │                     │  Skip invoice            │
      │                     │  Alert organization      │
      │                     │                          │
      │  Swedish Law:       │                          │
      │  "Rätt till         │                          │
      │  pappersfaktura"    │                          │
      │  Always ensure      │                          │
      │  postal available ──┤                          │

6. API Specifications

6.1 API Design Principles

Standards:

• RESTful design with resource-based URLs
• JSON request/response bodies
• HTTP status codes per RFC 7231
• OAuth 2.0 Bearer token authentication
• URL path versioning (/v1, /v2)
• Consistent error response envelope
• HATEOAS links for related resources (optional)

Base URL: https://api.egflow.com/v1

Response Envelope (All Responses):

{
  "success": true|false,
  "data": { },
  "metadata": {
    "timestamp": "ISO8601",
    "requestId": "uuid",
    "apiVersion": "1.0"
  },
  "errors": null|[]
}

6.2 Complete API Endpoint Catalog

6.2.1 Batch Management APIs

6.2.2 Organization APIs

6.2.3 Template APIs

6.2.4 Schema Management APIs

6.2.5 Invoice APIs

6.2.6 System APIs

6.3 Detailed API Specifications

6.3.1 POST /organizations/{orgId}/batches (Batch Upload)

Purpose: Upload batch invoice XML file for processing

Request Headers:

Authorization: Bearer {jwt-token}
Content-Type: multipart/form-data

Request Body:

file: [XML file binary]
metadata: {
  "batchName": "Invoice_November_2025",
  "priority": "normal"
}

Success Response (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:a3d5e7f9...",
      "detectedFormat": "GASEL"
    },
    "blobPath": "acme-batches-2025/11/21/550e8400.../source.xml"
  }
}

Error Responses:

// 400 Bad Request - Invalid XML
{
  "success": false,
  "errors": [{
    "code": "INVALID_XML",
    "message": "XML file is not well-formed",
    "field": "file",
    "details": {
      "line": 142,
      "column": 23,
      "error": "Unexpected end tag: </Invoice>",
      "suggestion": "Check that all opening tags have matching closing tags",
      "documentationUrl": "https://docs.egflow.com/errors/INVALID_XML"
    }
  }]
}

// 413 Payload Too Large
{
  "success": false,
  "errors": [{
    "code": "FILE_TOO_LARGE",
    "message": "File exceeds 100MB limit",
    "details": {
      "fileSize": 105906176,
      "limit": 104857600,
      "suggestion": "Split large batches into multiple files"
    }
  }]
}

// 415 Unsupported Media Type
{
  "success": false,
  "errors": [{
    "code": "UNSUPPORTED_FORMAT",
    "message": "Cannot detect vendor format",
    "details": {
      "detectedNamespace": "http://unknown.com/schema",
      "supportedFormats": ["GASEL", "XELLENT", "ZYNERGY"],
      "suggestion": "Ensure XML uses one of the supported vendor formats",
      "documentationUrl": "https://docs.egflow.com/vendor-formats"
    }
  }]
}

// 429 Too Many Requests
{
  "success": false,
  "errors": [{
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many batch uploads",
    "details": {
      "limit": 10,
      "window": "1 hour",
      "retryAfter": "2025-11-21T11:30:00Z"
    }
  }]
}

Response Headers:

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 5
X-RateLimit-Reset: 1700226000
Location: /v1/organizations/{orgId}/batches/{batchId}

6.3.2 POST /organizations/{orgId}/batches/{batchId}/start

Purpose: Start asynchronous processing of uploaded batch

Request:

{
  "validationMode": "strict"
}

Success Response (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
  }
}

Error Responses:

// 409 Conflict - Already Processing
{
  "success": false,
  "errors": [{
    "code": "CONFLICT",
    "message": "Batch is already processing",
    "details": {
      "currentStatus": "processing",
      "startedAt": "2025-11-21T10:00:00Z",
      "estimatedCompletionAt": "2025-11-21T11:30:00Z"
    }
  }]
}

// 503 Service Unavailable - Queue Full
{
  "success": false,
  "errors": [{
    "code": "SERVICE_UNAVAILABLE",
    "message": "System at capacity, retry later",
    "details": {
      "queueDepth": 10500,
      "estimatedWaitTime": "30-60 minutes",
      "retryAfter": "2025-11-21T11:00:00Z",
      "suggestion": "Consider scheduling batch for off-peak hours (22:00-06:00 CET)"
    }
  }]
}

6.3.3 GET /organizations/{orgId}/batches/{batchId}

Purpose: Get current batch status and statistics

Success Response (200 OK):

{
  "success": true,
  "data": {
    "batchId": "550e8400-e29b-41d4-a716-446655440000",
    "organizationId": "123e4567-e89b-12d3-a456-426614174000",
    "batchName": "Invoice_November_2025",
    "status": "processing",
    "priority": "normal",
    "vendorInfo": {
      "vendorCode": "GASEL",
      "vendorName": "Telinet Energi / EDIEL",
      "version": "1.0",
      "detectedNamespace": "urn:ediel:se:electricity:invoice:1.0"
    },
    "statistics": {
      "totalItems": 5000,
      "parsedItems": 5000,
      "queuedItems": 1800,
      "processingItems": 200,
      "completedItems": 3000,
      "failedItems": 0,
      "successRate": 100.0,
      "itemsByStatus": {
        "queued": 1800,
        "rendering": 50,
        "rendered": 100,
        "delivering": 50,
        "delivered": 2900,
        "failed": 0
      },
      "deliveryChannelBreakdown": {
        "email": 2500,
        "postal": 500
      }
    },
    "timestamps": {
      "uploadedAt": "2025-11-21T10:30:00Z",
      "queuedAt": "2025-11-21T10:35:00Z",
      "startedAt": "2025-11-21T10:35:10Z",
      "estimatedCompletionAt": "2025-11-21T11:05:00Z",
      "completedAt": null
    },
    "fileInfo": {
      "fileName": "invoices_nov.xml",
      "fileSize": 15728640,
      "format": "xml"
    }
  }
}