ConvergeX Platform Architecture & Enterprise Integration Guide

1. Overview

ConvergeX is a multi-tenant SaaS Access Service Provider (ASP) for Oman Fawtara / OTA e-invoicing on a PEPPOL-aligned foundation. Enterprise clients integrate via a secured REST API (or portal / bulk channels). ConvergeX validates business payloads, applies field-level encryption, persists durable records, generates UBL 2.1 evidence, and submits through the accredited Oxalis Access Point to the Oman Tax Authority network — returning structured acceptance / rejection artefacts to the caller.

2. Business & regulatory context

Oman’s national e-invoicing programme (Fawtara), administered by the Oman Tax Authority (OTA), requires structured electronic invoices. ConvergeX implements PEPPOL-aligned profiles (including PINT OM) and produces UBL 2.1 artefacts while submitting operational payloads through the accredited Access Point.

3. High-level solution architecture

Modular, service-oriented SaaS with clear separation of client, edge, application, processing, data, and external connectivity planes.

4. Oman / regional data-centre posture

ConvergeX production for Oman Fawtara customers is engineered as an enterprise-grade regional SaaS footprint: hardened edge, multi-AZ application and data tiers, continuous security monitoring, and operational controls expected by bank and insurer technology risk committees.

4.1 Control & observability stack

Platform operations align with the public ConvergeX trust pages and AWS-class monitoring services (CloudTrail, CloudWatch, GuardDuty, Config, Security Hub, WAF) for continuous detection and response — see also Security monitoring, encryption in transit, and encryption at rest.

5. Logical components & technology stack

5.1 Authentication planes

6. Multi-tenant data model

All business data is scoped to a Company (tenant). Large organisations may operate one or more tenants (legal entities / brands) with strict segregation enforced in ORM queries and API auth.

6.1 Traceability identifiers

• Invoice number — unique per company
• Invoice UUID — platform primary key
• Tracking / processed references — assigned during processing
• Government submission ID — OTA / Oxalis transaction or acceptance identifier
• X-Correlation-Id / X-Idempotency-Key — outbound HTTP correlation to Oxalis

7. Multi-application integration within one organisation

Banks, insurers, and conglomerates rarely have a single billing system. ConvergeX is designed so multiple upstream applications can integrate safely under one (or more) tenants.

7.1 Recommended patterns

7.2 Identity of source systems

Integrators should pass stable ERP identifiers (for example customer erp_uuid, invoice numbers unique per company) so ConvergeX can support idempotent upserts, reconciliation, and Customer Master reuse across applications that share counterparties.

8. API layer — how third parties integrate

Machine clients call ConvergeX over HTTPS. Authenticate with company client credentials, optionally exchange for JWT access/refresh tokens, then invoke resource APIs with Authorization: Bearer … or API-key headers as documented in the authenticated API documentation pack.

8.1 Primary surfaces

8.2 Sync vs async create

8.3 Environments

9. Field mapping (ERP → ConvergeX ASP → PEPPOL / OTA)

ConvergeX exposes a PEPPOL-oriented JSON model. Enterprise middleware maps ERP/CBS columns into these fields. Optional per-tenant FieldMapping records can further normalise partner-specific payloads. Seller defaults may be derived from the company profile when omitted.

9.1 Representative mapping catalogue

9.2 Mapping flow

ERP / CBS / Core record
   │  (middleware transform + enrichment)
   ▼
ConvergeX REST JSON  ──validate──►  encrypt sensitive fields  ──►  Invoice (+ lines/tax)
   │
   ├── generate UBL 2.1 (compliance evidence)
   └── on submit: build OTA outbound JSON ──POST──► Oxalis AP → OTA

10. Async intake, messaging & queue processing

High-volume ERP traffic must not block on full validation and persistence. ConvergeX uses a durable outbox (IntegrationJob) plus Celery/Redis workers, with Beat-driven retries for failed jobs.

10.1 Other asynchronous processors

• Email queue — DB-backed outbox; Celery Beat and/or in-process processor; SMTP over TLS
• Inbound document sync — background daemon polls Oxalis/OTA inbound documents (advisory-locked)
• OTA submit — synchronous HTTPS on submit API with structured error capture (durable outbound pipeline on roadmap)

11. Invoice lifecycle & processing engine

12. ConvergeX → Oxalis Access Point → OTA

Government submission is performed by ConvergeX on behalf of the tenant. Per-company PeppolNetworkConfig stores the OTA base URL, API key, and participant identity. On submit, ConvergeX builds an OTA outbound payload and POSTs to the appropriate Oxalis path (invoice / credit-note / debit-note / self-billing variants).

12.1 Security of the AP call

• TLS to Oxalis base URL (tenant-configured)
• Header X-API-Key from Peppol network configuration
• X-Correlation-Id and X-Idempotency-Key for safe retries and tracing
• Timeouts and structured error capture into invoice government response

13. Response recording & return path

Oxalis/OTA outcomes are first-class invoice data — not ephemeral logs only.

14. Inbound documents (buyer / supplier side)

For documents addressed to the tenant as buyer, ConvergeX runs an inbound sync processor that polls the Oxalis/OTA inbound documents API, persists InboundDocument records, and surfaces them in the supplier incoming documents experience — complementing outbound sales-invoice flows.

• Periodic poll (configurable; typically on the order of minutes)
• PostgreSQL advisory lock to prevent duplicate workers
• Cursor-based fetch against Peppol network configuration

15. Security layers — monitoring, encryption, access control

ConvergeX applies defence-in-depth across edge, application, data, and operations planes. Sections 16–18 expand the controls typically reviewed in bank / insurer application-security questionnaires (secure coding, OWASP API Top 10, SDLC & SIEM readiness).

15.1 Encryption in transit

• HTTPS only in production (HSTS, secure cookies, TLS-terminated load balancer)
• TLS 1.2 minimum (TLS 1.3 preferred); legacy protocols and weak ciphers disabled
• PostgreSQL connections with TLS (sslmode=verify-full + CA verification in production)
• S3 over SSL; SMTP STARTTLS for email; Oxalis/OTA calls over HTTPS with certificate validation

15.2 Encryption at rest

• Field-level Fernet encryption for sensitive party/PII attributes on company, profile, customer master, and invoices
• Key material derived via PBKDF2-HMAC-SHA256 from environment secrets (keys separated from application data)
• Decrypt-on-read for presentation and OTA payload construction
• Document objects stored in encrypted cloud object storage; managed database encryption where configured

15.3 Access control, API hygiene & audit

Certifications posture (ISO 27001 / 9001 / 22301 / PEPPOL) is summarised on the Certifications page.

16. Application security controls (OWASP-aligned)

Enterprise InfoSec teams commonly assess ASP platforms against OWASP-aligned secure coding requirements (input validation, authentication, session, access control, cryptography, logging, data protection, communication security, configuration, database, file handling, and SDLC). ConvergeX addresses these themes as follows.

16.1 Input validation & output encoding

• Server-side validation is authoritative (DRF serializers / model constraints) — never trust the client alone
• Allow-lists for types, ranges, lengths, and canonical formats (UTF-8); invalid input is rejected
• Hazardous sequences (path traversal, null bytes, CRLF) are blocked or neutralised at trusted boundaries
• Template escaping and context-aware encoding at the output boundary; parameterized DB access (ORM) to prevent injection
• Outbound HTTP (e.g. Oxalis) is restricted to approved HTTPS destinations — SSRF controls against internal/metadata ranges

16.2 Authentication & password management

16.3 Session management

• Framework session / JWT controls — cryptographically strong identifiers; no custom session schemes in URLs
• Cookie attributes: Secure, HttpOnly, scoped domain/path, SameSite
• Logout fully invalidates server-side session; idle and absolute timeout policies
• Session regeneration on privilege change / re-authentication where applicable
• CSRF protection on state-changing portal requests; anti-automation on sensitive flows

16.4 Access control (deny by default)

• Authorization decisions use trusted server-side identity (tenant Company, roles, API scopes) — never client claims alone
• Object-level checks on every invoice / master-data access (tenant isolation / BOLA prevention)
• Least privilege for service accounts connecting to DB, Redis, S3, and Oxalis
• Admin functions segregated from day-to-day company user functions
• CORS configured restrictively; no wildcard origins on authenticated endpoints
• Account disable / session termination supported when authorization ceases

16.5 Cryptography, data protection & communications

16.6 Error handling & security logging

• Fail securely — generic client messages; stack traces never returned to browsers or API consumers
• Structured server logs for auth failures, access denials, validation failures, admin actions, TLS/integration errors
• No passwords, tokens, or full sensitive payloads in logs
• Logs are access-restricted and SIEM-ready for enterprise correlation (see §18)
• Authoritative time (NTP) for correlatable timestamps

16.7 System configuration, database & file handling

17. API security controls (OWASP API Top 10)

ConvergeX exposes and consumes REST APIs. The following maps platform controls to the OWASP API Security Top 10 (2023) themes used in enterprise API security checklists.

17.1 Cross-cutting API logging & detection

• Auth attempts, authorization failures, validation rejects, and admin/integration events captured without sensitive payloads
• Anomaly-oriented monitoring via cloud security services and operational dashboards
• Ready for enterprise SIEM / IDS-IPS correlation where customers require log forwarding under contract

18. Secure SDLC, testing & enterprise security integrations

18.1 Secure development lifecycle

• Source in access-controlled version control with branch protection and peer review
• Change control and release gates for production
• Dependency / SCA awareness (SBOM-oriented practices) and secrets scanning in pipelines
• No secrets in repositories or build artefacts
• Idempotency and concurrency controls for shared state (integration jobs, invoice uniqueness)

18.2 Security testing & assurance

18.3 Integration with enterprise security controls

For large institutions, ConvergeX can expose standards-based operational interfaces so customer security stacks remain in control of monitoring and identity governance:

19. Autoscaling, high availability & disaster recovery

Enterprise clients require more than a single-node web app. ConvergeX production is operated as a resilient regional service with capacity elasticity and recovery objectives suitable for regulated industries.

19.1 Operational monitoring

• Application and queue health metrics / alerting
• API error-rate and latency observation
• Security event detection with operations response workflows
• Invoice status dashboards for customer operations teams

20. Recommended enterprise integration sequence

21. Appendix

A. Key API surfaces (summary)

/api/auth/token/                      → client credentials → JWT
/api/auth/token/refresh/              → refresh access token
/api/invoices/create/                 → create (sync)
/api/invoices/create/?mode=async      → 202 + job_id
/api/integration/jobs/{job_id}/       → poll async job
/api/invoices/{id}/submit/            → Oxalis/OTA submit
/api/invoices/{id}/compliance/        → compliance evidence
/api/invoices/{id}/tdd-report/        → technical design report artefact
/api/invoices/{id}/ota-preview/       → outbound preview

B. Glossary

C. Related ConvergeX materials

• PEPPOL 5-corner flow chart
• Security overview · monitoring · encryption pages
• ISO & PEPPOL certifications
• Authenticated customer portal: API documentation, Postman packs, OTA ERP guide
• Enterprise InfoSec: mapped responses to Application Security & API Security questionnaires (on request)