Platform Overview

The middleware is a Spring Boot application that bridges Micros POS systems (Taxint API format) to the Chrilan Smart API for ZRA fiscal compliance, built for Pedro's Chicken multi-store operations and deployed at server.zra.co.zm/pckzra.

The core idea

Fiscal compliance should be invisible to cashiers and automatic for the business. A cashier rings up a sale exactly as before; the middleware makes that sale legal in the eyes of ZRA by registering it, and hands back everything the receipt printer needs — receipt number, QR code, SDC ID, digital signature and tax breakdown.

Platform capabilities

Capability	Description
Invoice fiscalisation	Taxint → Chrilan translation, ZRA registration, response translation back to Taxint with all fiscal identifiers
Credit notes	Automatic original-invoice lookup from the local `fiscal_invoices` table; refunds linked to original receipt number and SDC ID as ZRA requires
Per-store isolation	Every store has its own TPIN, Chrilan API key, menu path and notification settings. No shared or fallback key exists
Menu synchronization	Oracle Simphony menus and tax definitions synced to Chrilan every 60 seconds, per store
Complete audit trail	Full request/response logging, conversion logging and fiscal invoice persistence in MariaDB
Admin portal	Store management, dashboard and reports, protected by email/password + WhatsApp OTP
Reporting API	Statistics, failures, conversion history and per-store volume over REST
API documentation	Interactive Swagger UI and OpenAPI 3 spec

The five integrated systems

System	Direction	Role
Oracle Simphony (Micros POS)	Inbound	Sends Taxint invoices; receives fiscal responses. Authenticates with Oracle IDM JWT.
Chrilan Smart API (ZRA)	Outbound	Registers invoices, assigns receipt numbers and QR codes. Authenticates with per-store API keys.
Oracle STS API	Outbound	Provides menu items and tax definitions for sync. Authenticates via OAuth2 + PKCE.
Whapi (WhatsApp)	Outbound	Delivers OTP codes for admin portal sign-in.
MariaDB	Internal	Stores logs, conversions, fiscal invoices, store registrations and users.

Full detail per system: Integrated Systems.

Design philosophy

1. Fail fast, fail loud

The codebase follows a strict one path per function rule: no silent fallbacks, no default values for missing data, no partial results. A missing field, a failed validation or an unreachable API throws immediately with a clear error returned to the POS.

Why this is deliberate For fiscal compliance it is far better to reject an invoice (the cashier retries) than to submit incorrect data to ZRA. Ambiguity is the enemy of auditability.

2. Per-store isolation, no fallbacks

Every invoice submission requires a database lookup of that specific store's API key. If the store is missing or inactive: HTTP 403, full stop. This guarantees store-level fiscal device registration as ZRA expects.

3. Complete audit trail

Every request, response, conversion and error is persisted. Transaction IDs flow through the whole lifecycle, so any receipt can be traced from POS payload to ZRA response and back.

Architecture at a glance

                        ┌──────────────────┐
                        │   Oracle IDM     │
                        │  (JWKS / PKCE)   │
                        └────────┬─────────┘
                                 │
┌──────────────┐  Taxint JSON ┌──▼───────────────┐ Chrilan JSON ┌──────────────┐
│   Oracle      │────────────▶│                  │─────────────▶│  Chrilan     │
│   Simphony   │  /pos/upload │   Middleware     │ /invoice/    │  Smart API   │
│  (Micros POS)│◀────────────│   (Spring Boot)  │◀─────────────│   (ZRA)      │
└──────────────┘  fiscal resp │                  │ fiscal resp  └──────────────┘
                              │  ┌────────────┐  │
┌──────────────┐  menu+taxes  │  │  MariaDB   │  │  products    ┌──────────────┐
│  Oracle STS  │─────────────▶│  │ logs,stores│  │─────────────▶│  Chrilan     │
└──────────────┘              │  └────────────┘  │ /createBulk  │  catalog     │
                              │  ┌────────────┐  │              └──────────────┘
                              │  │   Whapi    │◀─┘ OTP via WhatsApp
                              │  └────────────┘  │
                              └──────────────────┘

Tech stack summary

Layer	Technology
Runtime	Java 21, Spring Boot 3.5.4, embedded Tomcat
Data	MariaDB 10.6+, Hibernate JPA, Flyway migrations (V001–V008), HikariCP
Security	Spring Security (dual filter chains), JJWT 0.12.6, Oracle IDM JWKS
Web portal	Thymeleaf server-rendered pages
Docs	springdoc-openapi (Swagger UI)
Packaging	Maven WAR, deployed on port 8181 with context path `/pckzra` behind Nginx SSL

Deeper: System architecture · Invoice flow · Security