Tutorial Overview
- Type: Interactive Case Study
- Level: All Levels
- Read Time: ~35 minutes
- Case: Sri Lanka Fuel Pass Re-Launch
Tech Lead Note
"This tutorial is structured so junior developers learn the 'why', and tech leads get reusable architectural frameworks."
What You'll Learn
- Formal Gap Analysis Frameworks
- Lifecycle Management Module Design
- Three Dimensions of Scalability
- Pre-launch Readiness Checklists
The Problem
On 15 March 2026, the Sri Lankan QR Fuel Pass was re-activated. Within hours, it was failing—not by "crashing", but by systematically locking out thousands of legitimate users.
Core Symptoms
- • Identity lockouts for 2022 registrants
- • Incompatible ownership data states
- • Hotline capacity collapse
I. Understand the Failure
1A. The 2026 Resumption
Systems archived in 2023 were reactivated for 2026 without data reconciliation. The system attempted to solve a 2026 problem using a 2023 snapshot of the world.
1B. Root Cause Matrix
II. Business Analysis: Gap Analysis
Gap Analysis Template
| Category | Current (Snapshot) | Target (Live) | Severity |
|---|---|---|---|
| Data | 2022 Phone Numbers | Live Carrier Data | BLOCKER |
| Functional | Single Owner Flow | Transfer Flow Required | BLOCKER |
| Integration | API v1.2 | API v2.4 (Current) | HIGH |
Hands-On Exercise 1
Document 6 gaps across Data and Functional categories for the 2026 re-launch.
III. Architecture: Lifecycle Management
3A. State Transitions
[Registered] -> [Active] -> [Transferred] -> [Archived]3B. Bi-temporal Data Model
CREATE TABLE vehicle_owner (
id UUID PRIMARY KEY,
status VARCHAR(20) NOT NULL, -- active, suspended, transferred
valid_from TIMESTAMPTZ NOT NULL,
valid_to TIMESTAMPTZ -- NULL means currently active
);IV. System Design: Scalability
Infrastructure
Scaling compute resources (Auto-scaling, CDNs).
Functional
Modular service boundaries and config-over-code.
Operational
Support triaging and automated exception handling.
4B. Spike-Resilient Architecture
[Users] -> [Load Balancer] -> [Queue] -> [Async Worker Pool] -> [Primary DB]V. READINESS CHECKLIST
Business Analysis
- Formal Gap Analysis
- Requirements Refresh
Architecture
- Lifecycle Module
- Bi-temporal Model
QA & System
- Spike Load Testing
- Exception Pipeline
Applying Common Habits
The Analysis Habit
Run a Gap Analysis even informally. Ask: 'What has changed?'
Entity Lifecycles
Map how real-world things change. Ensure systems handle them.
Technical Glossary
Enterprise Resilience
Architecture is about decisions made before code is written. By applying these frameworks, you ensure your systems thrive in real-world complexity.
