The Napkin Architecture
The Napkin Architecture — Teaching Notes
Objective: Help students visualize a digital fix by drawing a simple architecture on a napkin (boxes + arrows). No code. Focus on components, data flows, and real-world constraints in African contexts.
1) Quick framing
“We’ll solve a root cause with the simplest possible architecture — draw boxes for each component and arrows for data/interaction. Keep it pragmatic: what runs on the phone, where the logic lives, where data is kept, and how things talk.”
Learning outcomes:
- Students can sketch a minimal working system.
- Students can evaluate if it works offline, for low-end phones, and without trust in banks.
- Students can produce 3 quick napkin architectures for different scenarios.
2) The canonical boxes (explain + draw)
Make a single napkin template first — draw these four labeled boxes and arrows between them:
[ Interface ] <---> [ Brain ] <---> [ Memory ]
| ^
| |
v |
[ Connection / Gateway ] ----Explain each:
- The Interface — Where the user interacts. Examples: Mobile app, SMS/USSD bot, Progressive Web App (PWA), voice/IVR, kiosk, admin web dashboard. Draw it at the left/top.
- The Brain — Where the business logic runs. Could be server-side API, edge function, serverless, or logic baked into the app (offline-first). Label whether it’s “trusted” (central server) or “edge” (on device).
- The Memory — Where data is stored. Options: local DB on device (SQLite), remote DB (Postgres, NoSQL), mobile-money ledger at operator, or a hybrid sync store.
- The Connection / Gateway — How Interface & Brain talk. Examples: Internet (HTTP/REST, WebSocket), GSM (SMS, USSD), Bluetooth / Wi-Fi Direct, or store-and-forward via SMS-to-HTTP gateway.
Always draw arrows showing: user → interface → connection → brain → memory and back. Also show device-local cache arrows between Interface and Memory for offline-first options.
3) The African-Context Constraint Check (walkthrough)
For every napkin sketch, ask these four checks and annotate the sketch with YES/NO and mitigation strategies:
Does it work if the user has no data?
- YES if you include SMS/USSD/IVR, offline app with sync, or store-and-forward.
- Mitigate by: providing USSD/SMS fallbacks, using an offline-first app with local DB and opportunistic sync (Wi-Fi or cheap cafés), and concise payloads.
Does it work if the user doesn’t trust banks?
- YES if you allow cash-out via agent networks, use mobile money providers, or tokenize value via vouchers redeemable at trusted local agents/merchants.
- Mitigate by: minimal PII collection, transparent audit logs, agent-based cash flows, on-device receipts.
Does it work on a $50 Android phone?
- YES if the app is lightweight: small APK, minimal RAM, avoid heavy libraries, use native simple UI or low-resource PWA.
- Mitigate by: using text-first UI, low-res images, caching, throttling background work, graceful degrade to SMS/USSD.
Other constraints: intermittent power, SIM sharing, multiple languages, literacy levels, intermittent network quality, and data cost sensitivity. Annotate solutions (e.g., audio prompts, icon-driven UI, zero-rating deals).
4) Three sample napkin architectures (draw these on the board / napkin)
A — Use-case: Simple payments between users (mobile-money enabled)
Draw boxes and arrows like:
[Low-end Mobile App / USSD Menu]
| (Internet or GSM)
v
[API Gateway / USSD Gateway] <--> [Business Logic (Payments Service)]
|
v
[Transaction Store / Audit DB]
|
v
[Mobile Money Provider / Agent Network]Key teaching points:
- If no data: USSD or SMS initiates the flow through the mobile operator’s USSD gateway; gateway calls backend.
- If user distrusts banks: use mobile-money provider or agent cash-out. Show agent box connected to Transaction Store.
- Security: short-lived tokens, OTP over SMS, sign transactions locally where possible.
- Offline scenarios: app creates unsigned transaction locally, prompts user to visit agent to finalize.
B — Use-case: Appointment reminders and confirmations (no smartphone assumed)
[SMS/USSD/IVR] <--> [Telecom Gateway / SMS Provider]
|
v
[Reminder Logic (serverless)]
|
v
[Minimal DB: contacts, status]Key points:
- USSD for interactive confirmations; SMS for push reminders; IVR for low-literacy users.
- Keep DB minimal (phone number, last status, next appointment).
- Respect two-way flow: include shortcodes for reply; draw arrows both ways.
- Cost control: batch messaging, prioritize critical reminders.
C — Use-case: Bus tracking + departure alerts (user has cheap Android phone)
[Android App (lightweight, offline cache)]
| (SMS fallback / minimal data)
v
[API / Broker] <--> [Real-time Engine (location processing)]
| |
v v
[Message Service] [Trip DB]
|
v
[Passenger Notifications via Push or SMS]Key points:
- On-device: local mapless UI, route ID, cached schedule.
- If driver cannot use data: driver sends periodic SMS with location or event codes (e.g., STOP_POINT_3).
- Sync strategy: app collects events, syncs when data is available; use delta syncs, compress payloads.
- Battery/cpu: avoid continuous GPS; use coarse updates or driver-triggered check-ins.
5) Design patterns & practical tactics (bullet list)
- Offline-first + sync: Local DB (SQLite/Room), write-ahead log, conflict resolution rules (last-write-wins or server adjudication).
- USSD & SMS fallbacks: Use USSD for interactive sessions (good for menus), SMS for receipts/alerts. Be aware USSD sessions are synchronous & stateful.
- Agent networks: Use physical agents for cash in/out and trust bridging. Represent agents as a small box connected to Transaction Store.
- Edge logic: Put minimal logic on device for responsiveness (validation, small calculations). Brain handles heavy rules and reconciliation.
- Minimal payloads: Use numeric codes, compact JSON, base64 for small binary, and incremental sync.
- Authentication for low-trust users: Device-bound tokens, SIM-based authentication (check MSISDN where possible), human-in-the-loop verification at agents.
- Data privacy: Encrypt sensitive data at rest (on device) and in transit; minimize PII stored centrally.
- Monitoring: Heartbeat pings, failure queues, and retries — draw a small “Monitoring” box linked to Brain.
6) Classroom activity (20–25 minutes)
- Split students into groups of 3–4. Give each group one scenario: payments, health reminders, market pricing feed, bus tracking.
- Task (10 min): Draw a napkin architecture showing Interface, Brain, Memory, Connection. Mark how it meets the three African constraints.
- Present (8 min): Each group shows napkin (2 min), instructor asks one probing question (1–2 min).
- Debrief (2–3 min): Instructor highlights tradeoffs & votes best offline strategy.
Provide prompts:
- “Design for a village with intermittent 2G, cash economy, and low trust in banks.”
- “Prioritize cost for the provider — how does that change your Connection layer?”
Rubric (for quick grading):
- Correct components drawn (Interface/Brain/Memory/Connection): 2 pts
- Clearly annotated offline/USSD fallback: 2 pts
- Trust / cash-out solution shown: 2 pts
- Low-end device considerations shown: 2 pts
- Simple data flow arrows that match described user story: 2 pts
7) Checklist to evaluate a napkin architecture (tick boxes to put beside drawing)
8) Common pitfalls & how to critique them
- Pitfall: Placing all logic on the server (won’t work offline). Fix: Move validations & UX-critical logic to device; server remains source of truth.
- Pitfall: Assuming smartphone-only. Fix: Add SMS/USSD paths and agent workflows.
- Pitfall: Storing PII centrally without need. Fix: Store minimal PII; use hashed identifiers.
- Pitfall: Large media assets. Fix: Use text/icons, lazy-load images, compress assets.
9) Example
“Here’s a napkin architecture pattern I use: five boxes — Interface, Connection/Gateway, Brain, Memory, and Agents/Third-party services. Always draw arrows for the flows and annotate what happens when the phone is offline. For African contexts we must plan for no data (USSD/SMS/IVR fallbacks), low trust in banking (agent cash-out and mobile money), and very low-end phones ($50 Android — so we make the app tiny and provide SMS fallbacks). In practice, the architecture becomes a hybrid: offline-first client, minimal central logic for reconciliation, and GSM gateways to reach everyone.”
10) Bonus: Rapid reference “patterns” cheat-sheet (for students)
- Pattern: Offline-first PWA — Interface: PWA; Brain: serverless; Memory: IndexedDB + server DB; Connection: HTTP with sync queue. Works on cheap phones with browser, minimal install.
- Pattern: USSD + API — Interface: USSD; Brain: stateless server; Memory: minimal DB; Connection: operator USSD gateway. Works without data, low literacy with menu choices.
- Pattern: SMS-driven workflow — Interface: SMS; Brain: workflow engine; Memory: state table; Connection: SMS gateway. Best for alerts & confirmations.
- Pattern: Agent-mediated payments — Interface: app/USSD; Brain: payment coordinator; Memory: ledger + audit; Connection: mobile money APIs + agent ledger. Solves bank distrust.
- Pattern: The Payment Aggregator — Interface: Unified API; Brain: Routing/Failover Logic; Memory: State DB; Connection: Adapters to MTN/Orange/Banks. Solves market fragmentation.
- Pattern: Async “Sidecar” Processing — Interface: Next.js App; Brain: Python Worker; Memory: Queue (Redis/PubSub); Connection: Internal Network. Keeps UI snappy while Python crunches data/AI tasks.
- Pattern: “Burst” Logistics Tracker — Interface: GPS/Sensor; Brain: Micro-buffer; Memory: Local Flash; Connection: GSM (Scheduled Batch Uploads). Saves battery and data costs for supply chains.
Continue Learning: The UML Architectural Diagrams