Priority: CRITICAL
Owner: Product Owner
The system shall support multiple independent utility companies (organizations) with complete data isolation at blob storage, processing, and user access levels.
Total Addressable Market: 700+ potential customers
| # | Criterion | Measurement Method | Target |
|---|---|---|---|
| 1 | Concurrent organizations supported | Load test with 50 orgs | All batches process successfully |
| 2 | Data isolation enforcement | Cross-org access attempts | 100% blocked (403 Forbidden) |
| 3 | Organization-specific blob containers | Verify storage paths | Pattern: {org-id}-{type}-{year}/ |
| 4 | User organization boundary enforcement | API calls with wrong org context | All rejected |
| 5 | Independent branding per organization | Upload logo, verify rendering | Branding applied correctly |
| 6 | Configurable delivery channels | Set priority [email, postal] | Order respected |
user_organization_roles table| Risk | Likelihood | Impact | Mitigation |
|---|---|---|---|
| Data leakage between orgs | LOW | CRITICAL | Middleware enforcement, automated testing, penetration testing |
| Performance degradation (50+ tenants) | MEDIUM | HIGH | Blob auto-scaling, connection pooling, indexed queries |
| Swedish data residency requirements | LOW | HIGH | West Europe primary, no cross-border transfer |
Priority: HIGH
Owner: Product Owner
The system shall process invoice batch files from multiple vendor billing systems (GASEL/Telinet, XELLENT/Karlskoga, ZYNERGY/EG Software) with automatic format detection and transformation to canonical JSON.
Top 3 Billing Systems in Swedish Market:
Combined Coverage: ~70% of addressable market
| # | Criterion | Measurement Method | Target |
|---|---|---|---|
| 1 | GASEL format detection | 50 sample files | 100% accuracy |
| 2 | XELLENT format detection | 50 sample files | 100% accuracy |
| 3 | ZYNERGY format detection | 50 sample files | 100% accuracy |
| 4 | Canonical JSON transformation | Schema validation | All fields present |
| 5 | XSD schema validation | Vendor-specific XSD | Pass validation |
| 6 | Unsupported format handling | Unknown XML upload | 415 error with vendor list |
| 7 | Detection performance | 100MB file | < 1 second |
GASEL (Telinet/EDIEL):
urn:ediel:se:electricity:invoice:1.0XELLENT (Karlskoga/OIOXML):
http://rep.oio.dk/ubl/xml/schemas/0p71/pie/com:, main:, fsv:ZYNERGY (EG Software):
http://eg.dk/Zynergy/1.0/invoice.xsd| Risk | Likelihood | Impact | Mitigation |
|---|---|---|---|
| Vendor schema changes without notice | MEDIUM | HIGH | Version all schemas, support multiple versions, 3-month deprecation notice |
| EDIEL standard evolution | MEDIUM | MEDIUM | Monitor Ediel.org, participate in Nordic working groups, backward compatibility |
| Complex namespace handling (OIOXML) | LOW | MEDIUM | XmlNamespaceManager, extensive unit testing per vendor |
| Incomplete field mappings | MEDIUM | MEDIUM | Comprehensive validation, custom fields dictionary, lenient parsing mode |
Priority: HIGH
Owner: Product Owner
The system shall process batch invoice files containing up to 100,000 invoices with parallel processing, retry logic, and granular status tracking.
Monthly Invoice Patterns:
| # | Criterion | Measurement Method | Target |
|---|---|---|---|
| 1 | Single batch capacity | Upload 100K invoices | All processed |
| 2 | Asynchronous processing | API response time | < 500ms (202 Accepted) |
| 3 | Real-time progress tracking | Poll during processing | Updates every 30 seconds |
| 4 | Failed item isolation | 10 errors in 1000-item batch | 990 succeed independently |
| 5 | Retry mechanism | Force temporary failure | 3 retries then poison queue |
| 6 | Processing time SLA | 100K invoice batch | ≤ 120 minutes |
| 7 | Format support (Phase 1) | Upload XML, JSON, CSV | XML fully supported |
1. API receives batch upload → 201 Created (batch stored)
2. POST /start → 202 Accepted (queued for processing)
3. ParserService picks from batch-upload-queue
4. Parse XML → Individual JSON files (canonical format)
5. Group into 32-item batches → Enqueue to batch-items-queue
6. DocumentGenerator renders 32 items in parallel
7. Generate HTML → PDF → Store in blob
8. Route to delivery queue (email or postal)
9. Update batch statistics in real-time
10. Complete when all items processed
| Risk | Likelihood | Impact | Mitigation |
|---|---|---|---|
| Processing timeout during heating season | MEDIUM | HIGH | Pre-warm workers 1st/last week, priority queue, off-peak scheduling |
| Memory constraints (large XML >50MB) | MEDIUM | MEDIUM | Stream-based parsing, chunk processing, 100MB hard limit |
| Disk space exhaustion | LOW | MEDIUM | Ephemeral storage cleanup, blob-only persistence |
| Queue 64KB message limit | MEDIUM | MEDIUM | Store data in blob, queue references only |
Priority: HIGH
Owner: Product Owner
The system shall generate PDF and HTML invoices using organization-specific Handlebars templates with dynamic data binding and brand customization.
Energimarknadsinspektionen (Swedish Energy Markets Inspectorate) mandates:
| # | Criterion | Measurement Method | Target |
|---|---|---|---|
| 1 | Custom template upload | Upload via API/blob | Stored successfully |
| 2 | Dynamic data binding | Test with invoice data | All fields populated |
| 3 | PDF generation | HTML → PDF | A4 format, readable |
| 4 | Template versioning | Create v2.0.0 | Old batches use v1.0.0 |
| 5 | In-flight batch isolation | Update template during processing | In-flight uses old version |
| 6 | Template validation | Missing variable upload | Validation error returned |
| 7 | Organization branding | Logo, colors, fonts | Visible in rendered PDF |
| 8 | Swedish regulatory fields | Verify required elements | All present |
Required Fields (Swedish Regulations):
| Risk | Likelihood | Impact | Mitigation |
|---|---|---|---|
| Template rendering bottleneck | HIGH | HIGH | Compiled template caching (24h), parallel rendering (32 items), POC: 10K in <5 min |
| PDF generation quality (Swedish chars) | MEDIUM | MEDIUM | UTF-8 encoding, font embedding (åäö), visual regression testing |
| Swedish regulatory compliance | LOW | CRITICAL | Legal review, required fields checklist, annual update review |
| Template injection attacks | LOW | CRITICAL | Sandboxed execution, no eval/exec helpers, sanitization, security review |
Priority: HIGH
Owner: Product Owner
The system shall deliver invoices through multiple channels (email, postal, future: Kivra, e-Faktura) with configurable priority, automatic fallback, and integration with Nordic delivery partners.
Legal Requirements:
Delivery Statistics (Industry Average):
| # | Criterion | Measurement Method | Target |
|---|---|---|---|
| 1 | Email delivery (SendGrid) | 1000 test invoices | >95% delivered |
| 2 | Postal delivery (21G SFTP) | Create ZIP, upload | File accepted by 21G |
| 3 | Channel priority configuration | Set [email, postal] | Email attempted first |
| 4 | Automatic fallback | Force email failure | Postal triggered auto |
| 5 | Delivery status tracking | Check invoice metadata | Status + timestamps recorded |
| 6 | Retry logic (transient failures) | Simulate SendGrid 429 | Retries with backoff |
| 7 | Delivery confirmation logging | Verify audit log | All deliveries logged |
| 8 | 21G bulk processing schedule | Verify postal queue | 12:00 and 20:00 CET |
Email (SendGrid):
Postal (21G Bulk SFTP):
/incoming/{org-code}/Phase 2 Channels:
| Risk | Likelihood | Impact | Mitigation |
|---|---|---|---|
| SendGrid Nordic deliverability issues | MEDIUM | HIGH | Dedicated IP, SPF/DKIM/DMARC, sender reputation monitoring, backup: Azure Communication Services |
| 21G SFTP connectivity issues | LOW | HIGH | Retry logic, dual credentials, alert on failure, 21G SLA monitoring, manual upload procedure |
| Postal delivery delays (Swedish postal) | MEDIUM | MEDIUM | Set expectations (5-7 days), track confirmations, escalation for >10 days |
| Email spam filtering (Swedish ISPs) | MEDIUM | MEDIUM | IP warmup, monitor bounce rates, ISP whitelist requests (Telia, Tele2, Telenor) |