DEV Community: Samuel Owolabi

Designing for Failure: Chaos Engineering Principles in System Design

Samuel Owolabi — Sat, 02 May 2026 15:52:03 +0000

A practical guide to chaos engineering principles that transform fragile architectures into resilient, self-healing systems.

Recently, I wrote an article titled “What if you are to build for one million daily active users?”. In that article, we explored a point where a monolithic system could no longer scale and began to break. We discussed scalability, availability, and observability, and why they become critical as systems grow. This article builds directly on that discussion.
Here, the focus is designing for failure, what exactly is Chaos Engineering, how can we simulate chaos on our system, measure the impacts, and how to handle and mitigate failures on our system.

The reality is that 100% uptime is not something you can realistically promise. What you can design for is fault tolerance and resilient infrastructure. That difference matters.

A simple way to understand this is the idea of a spare tire in your car. You do not expect to have a flat tire every day, but you still keep a spare. You might even check occasionally to make sure it is still inflated. The reason is straightforward. The cost of being unprepared when failure happens, especially in a bad situation like a breakdown on a highway at night, is very high. I have experienced this before on Lekki, Lagos highway, and that night wasn’t funny (LOL).

Netflix famously talked about building Chaos Monkey, a tool that randomly terminates production instances. The goal was to force their systems to survive common types of failures before those failures happened unexpectedly. This is the core mindset behind Chaos Engineering.

To design for failure, we must understand how the system behaves when failure inevitably happens. What is the cost? What is the impact? How do we mitigate it? How do we still maintain over 99% uptime? This requires treating failure as a default state, not an exception.

Core Principles of Chaos Engineering

1. Define What “Normal” Looks Like

The first step is defining steady-state behavior. Without this, there is no baseline to measure against.
Examples include:

P95 latency less than 300 milliseconds
Error rate below 0.5%
Successful payment completion rate above 99.9%

These metrics represent what healthy behavior means for your system.

2. Form a Hypothesis

Once normal behavior is defined, you form a hypothesis.
The idea is simple: if a specific failure happens, the system should still be able to perform a critical function.
For example, if Service X fails, users should still be able to complete checkout within acceptable latency. This keeps chaos experiments intentional and measurable.

3. Introduce Realistic Failures

Next, you introduce failures that closely resemble real-world incidents.
Examples include:

Killing instances or Kubernetes pods
Introducing network latency or packet loss
Brute-forcing APIs to test rate limits
Simulating DDoS-like traffic spikes
Simulating DNS failures or dependency outages
Testing third-party data mismatches or breaking changes

We are ensuring realism, not randomness.

4. Run Experiments in Production

Chaos experiments are most valuable in production. This is where real traffic patterns, real user behavior, and real data shapes exist.
That said, experiments must be controlled.

Start small to limit blast radius.
Run during business hours when teams are available.
Have clear rollback strategies such as feature flags, traffic shifting, or instance replacement.
Ensure strong monitoring and observability before running experiments.

I want you to know that running chaos experiments without observability leads to outages, not learning.

5. Automate and Continuously Improve

Chaos Engineering is not a one-off exercise.
Systems evolve. Dependencies change. Teams rotate.
Experiments should be automated, repeatable, and run continuously, either as scheduled jobs or integrated into CI/CD pipelines. Over time, experiments can be expanded to test higher-impact scenarios.
The feedback loop remains consistent:
Design → Build → Chaos Test → Iterate

Types of Failures to Design For and How to Address Them

Section 1: Single Points of Failure

A single point of failure is any component whose failure can bring down the entire system.

1. Database Failures

Scenario: The primary database goes down.
Solutions:

Primary–standby setup with synchronous replication and automatic failover
Read replicas for distributing read queries (asynchronous replication)

Additional considerations include health checks, failover timing, and data consistency. Strong consistency simplifies reasoning but reduces availability. Eventual consistency improves availability but introduces complexity and potential inconsistency windows.
Trade-offs: Increased cost, operational complexity, and consistency challenges.

2. Cloud Server Outages

Using a single availability zone creates unnecessary risk.
Solutions:

Multi-AZ architecture for high availability
Multi-region architecture for disaster recovery

Trade-offs: Higher latency, data replication complexity, and increased cost.

3. Application and Web Server Failures

Scenario: API servers crash or become unhealthy.
Solutions:

Horizontal scaling using Auto Scaling Groups
Load balancer health checks and automatic deregistration
Stateless application design
External session storage or token-based session management

Trade-offs: More infrastructure and stricter architectural discipline.

4. Message Queue Failures

Common failure modes include broker unavailability and consumer processing timeouts.
Solutions:

Dead-letter queues for failed messages
Temporary fallback storage such as NoSQL databases
Clustered queue setups with replication

Trade-offs: Increased operational overhead and reprocessing complexity.

5. DNS Failures

Relying on a single DNS provider or registrar is a common oversight.
Solutions:

Multiple DNS providers
Secondary DNS configurations
Anycast DNS

6. Third-Party API Failures

Depending on a single third-party API for critical functionality is risky, especially in domains like fintech.
Solutions:

Multiple providers
Cached responses
Graceful fallback data or degraded flows

Trade-offs: Higher integration complexity and reconciliation challenges.

Every solution discussed here introduces trade-offs. Designing for failure is not about eliminating risk entirely. It is about understanding where risk exists and making deliberate decisions about how much of it you are willing to accept.

Section 2: Network Failures

Network failures are unavoidable in distributed systems. Latency spikes, packets get dropped, DNS fails, and sometimes the network splits entirely. Many system outages are not caused by servers crashing, but by slow or unreliable communication between otherwise healthy components.

This is where several of the classic fallacies of distributed computing show up, especially the assumption that the network is reliable and has zero latency.

Common Network Behavior and Risk Pattern we often ignore

1. Are All Network Calls Protected with Timeouts?

Timeouts are one of the most important and most frequently overlooked safeguards in distributed systems.

A slow dependency is often worse than a failed one. Without timeouts, requests pile up, threads get exhausted, and failures spread to otherwise healthy services.
Timeouts should exist at every layer:

Client-side requests
API gateway timeouts
Service-to-service calls
Database query execution
External API requests

A practical rule of thumb is that timeouts should get shorter as requests move deeper into the system.
Example timeout chain:
Client (10s) → Gateway (8s) → Service (6s) → Database (4s)
Timeouts should also be monitored. A sudden increase often indicates upstream degradation long before a full outage occurs.

2. Do We Have Retry Logic with Exponential Backoff?

Retries exist to handle transient failures such as brief network interruptions or temporary service unavailability.
However, retries without limits or delays can make outages worse.
It is important to distinguish between:

Transient failures, which may succeed on retry
Permanent failures, which will not

Exponential backoff helps control retry behavior by increasing the wait time between attempts.

// Basic formula:
wait_time = base_delay × (2 ^ attempt_number)

This reduces pressure on failing services and prevents retry storms. Retry counts should always be capped, and retries should be combined with timeouts and circuit breakers.

3. Are Operations Idempotent?

Idempotency means that performing the same operation multiple times produces the same result.
This becomes critical when retries are involved. If a request is retried due to a timeout, the system must not process it twice in a harmful way.

Common implementation strategies include:

Unique transaction or request IDs
Idempotency keys stored with deduplication windows
Server-side request tracking

Payment systems are a common example where idempotency is mandatory. Charging a user twice because of a retry is unacceptable.

Section 3: Cascading Failures

In complex systems, failures rarely stay isolated. A single degraded service can trigger failures in upstream services, which then overload others. This is how small issues turn into large outages.

1. Are Circuit Breakers in Place?

Circuit breakers prevent repeated calls to failing dependencies.
They typically operate in three states:

Closed: requests flow normally
Open: requests are blocked
Half-open: limited test requests are allowed

Key configuration parameters include:

Failure threshold, such as a 50% error rate
Open-state timeout duration
Number of test requests in half-open state
Visibility into circuit breaker state through monitoring

Circuit breakers protect systems by failing fast and giving dependencies time to recover.

2. Can One Service’s Failure Take Down the Entire System?

This question reveals how tightly coupled a system is.
Important steps include:

Identifying critical path services
Mapping service dependencies
Understanding which failures are acceptable and which are not

Implementation strategies:

Prefer asynchronous communication where possible
Use event-driven patterns to reduce tight coupling
Provide fallback responses when dependencies fail
Serve stale or cached data when appropriate

Chaos experiments are useful here. For example, intentionally disabling a downstream database and observing how the system behaves can reveal hidden coupling and unexpected dependencies.

Section 4: Data Consistency

Distributed systems must make trade-offs between consistency, availability, and partition tolerance. Network partitions are not hypothetical events; they are guaranteed to happen at some point.
This is where understanding consistency models becomes essential. The spectrum ranges from strong consistency, which is easier to reason about but less available, to eventual consistency, which improves availability but requires careful conflict handling.
(This ties directly into the earlier discussion on strong vs eventual consistency. I wrote an article on this here, please check it out, you will gain deeper knowledge on consistency).

Common Risk Pattern: Consistency Mismatch

1. Is the Consistency Model Appropriate for the Use Case?

Different parts of a system often require different consistency guarantees.

Strong consistency means that once a write succeeds, every subsequent read will immediately return that updated value. From the user’s point of view, the system behaves as if there is only one copy of the data. This makes the system easier to reason about, but it usually comes at the cost of higher latency and lower availability, especially during failures or network issues.

Eventual consistency means that after a write, different parts of the system may temporarily see different values, but given enough time and no new updates, all copies will converge to the same state. This model favors availability and performance, but it requires the system and sometimes the application to handle stale data and resolve conflicts.

In practice, strong consistency optimizes for correctness and simplicity, while eventual consistency optimizes for availability and scale. Neither is universally better. The right choice depends on what the data represents and how critical immediate correctness is to the user experience.

Strong consistency is suitable for: Payments, Inventory updates, Account balances
Eventual consistency works well for: Recommendations, Activity feeds, Analytics

Hybrid approaches are common and often necessary.
Examples:

Strong consistency for checkout flows
Eventual consistency for product recommendations
Per-operation consistency levels
Strong guarantees on critical paths, relaxed guarantees elsewhere

2. How Do We Handle Replication Lag?

Replication lag occurs when followers fall behind leaders.
Common causes include:

Network latency
High write throughput
Slower follower nodes

Lag becomes dangerous when users expect read-after-write consistency but do not receive it.
Mitigation strategies include:

Reading from the leader immediately after writes
Client-side caching of recent writes
Versioning and monotonic reads

Replication lag should be measured and monitored. When lag grows beyond acceptable limits, it becomes a correctness issue, not just a performance concern.

Section 5: Recovery

Failures will happen. What matters next is how quickly and safely the system recovers.
This is where recovery metrics become practical tools rather than abstract concepts.
Key metrics include:

RTO (Recovery Time Objective): how long recovery can take
RPO (Recovery Point Objective): how much data loss is acceptable
MTTR (Mean Time to Recovery)

The business cost of downtime

Common Risk Pattern: Slow or Manual Recovery

1. How Quickly Are Failures Detected?

Detection speed directly affects recovery time.
Effective detection relies on:

Well-designed health checks
Monitoring and alerting
Observability across logs, metrics, and traces

Examples include infrastructure and application monitoring tools, both within cloud providers and external platforms. Faster detection leads to faster mitigation.

2. Can the System Heal Itself?

Self-healing reduces reliance on manual intervention.
Examples include:

Auto Scaling Groups replacing failed instances
Kubernetes restarting unhealthy containers
Horizontal Pod Autoscaling
Automated DNS failover

Self-healing does not eliminate the need for humans, but it reduces response time significantly.

3. What Is the Backup and Recovery Strategy?

Backups exist to meet RPO and RTO goals.

RPO (Recovery Point Objective) answers the question:
How much data can we afford to lose?
It defines the maximum acceptable amount of data loss measured in time.
For example, an RPO of 5 minutes means losing up to 5 minutes of data is acceptable if a failure occurs. Anything beyond that is a problem.
RPO directly influences how often you back up data and how replication is designed.

RTO (Recovery Time Objective) answers the question:
How long can the system be down?
It defines the maximum acceptable time it should take to restore the system after a failure.
For example, an RTO of 30 minutes means the system must be back online within 30 minutes of an outage.
RTO affects automation, failover strategies, and disaster recovery architecture.

Key questions:

How much data loss is acceptable?
How fast must recovery occur?

Common strategies include:

Database snapshots
File system backups
Object storage versioning
Backup frequency aligned with RPO requirements

Bonus: Disaster Recovery Strategies

Disaster recovery approaches vary by cost and recovery speed.

Backup and Restore: lowest cost, slowest recovery
Pilot Light: minimal services running, faster recovery
Warm Standby: scaled-down but functional environment
Hot Site / Multi-Site: fastest recovery, highest cost

Choosing a strategy is a business decision informed by technical constraints.

Designing Systems That Expect Reality

Designing for failure is not about pessimism. It is about acknowledging how real systems behave under real conditions.
Each section in this article addresses a different failure category:

Single points of failure
Network unreliability
Failure chain reactions
Data consistency trade-offs
Recovery and self-healing

The common thread is intentional design.
Resilient systems are not accidental. They are built by teams who assume failure will happen, test for it deliberately, and learn continuously.
The goal is not zero failure.
The goal is controlled failure, fast recovery, and minimal impact on users.
That is what designing for failure truly means.

Strong vs Eventual Consistency in System Design

Samuel Owolabi — Sat, 02 May 2026 15:22:10 +0000

Why does this matter in distributed systems and why you should know this?

Modern software systems are rarely contained on a single machine. They are spread across multiple servers and regions to ensure they stay fast and reliable for users everywhere.

This distribution is a powerful tool, but it creates a challenge. When you have multiple copies of your data stored on different servers, you have to decide how to keep those copies in sync. This is the "consistency" problem.

How you handle this determines how your system behaves when things get busy or when the network fails. As a developer or architect, you must choose your consistency model intentionally. If you don't, the system will choose for you, and usually at the most inconvenient time.

What Consistency Really Means

In a distributed system, consistency is about timing. It answers the question: "After I save a piece of data, how soon will everyone else see the update?"

Think of it like a group chat.

Strong Consistency: Everyone in the chat sees every message in the exact same order at the exact same time. No one can reply to a message they haven't seen yet.
Eventual Consistency: Some people might see messages a few seconds later than others. Eventually, everyone sees the same history, but for a moment, the "truth" looks different depending on who you ask.

Choosing between them is not purely technical. It is a business decision with architectural consequences.

This article helps you understand how these models work, what trade-offs they impose, and how to choose intentionally without over-engineering or under-protecting your system.

Note: This is not the same as ACID consistency in single-node databases.
ACID consistency means the database moves from one valid state to another.
Distributed consistency is about when and where changes become visible.

Strong Consistency: The "Single Source of Truth"

Strong consistency guarantees that once you write data, every subsequent read will return that new value. It doesn't matter which server the user connects to. They will always get the latest version.

How It Works

Strongly consistent systems typically rely on:

A leader or primary node that orders writes
Synchronous replication to replicas
Quorums that require majority agreement before success

A write is not considered successful until the system can guarantee that any subsequent read will see it.

This often means:

Writes must wait
Reads may block
Network partitions reduce availability

Correctness is preserved.

Real Use Cases of Strong Consistency

These are places where showing the wrong data even briefly causes real damage.

You send money

Bank transfers, wallet balances, payment confirmations. If your balance is wrong for even a moment, trust is gone.
You buy the last item

E-commerce stock, flash sales, ticket booking. Two people cannot buy the same last seat.
You lose or gain access

Logging in, role changes, permission updates. If access is revoked, it must be revoked everywhere immediately.
You hit a usage limit

API rate limits, subscription caps, quotas. Users must not exceed what they paid for.
You flip a critical switch

Feature flags, kill switches, security toggles. Partial rollout can break production fast.

The Benefits

Predictability: The system behaves exactly like a single-node database.
Safety: You never have to worry about a user seeing an "old" version of their bank balance or a deleted password.

The Trade-offs

Speed: The system is slower because it has to wait for multiple servers to agree.
Availability: If one server is down or the network is lagging, the whole update might fail. The system chooses "Correctness" over "Being Online."

Eventual Consistency: The "High Speed" Approach

Eventual consistency allows different servers to hold different versions of the data for a short window of time. The system promises that "eventually," all copies will be the same, but it doesn't wait for that to happen before finishing your request.

How It Works

When you save data, the system records it on one server and immediately tells you "Success." It then copies that data to other servers in the background. For a few milliseconds, or sometimes seconds, a user on the other side of the world might still see the old data.

Eventual consistency relies on:

Asynchronous replication
Background synchronization
Conflict resolution strategies

The system prioritizes availability, low latency, and partition tolerance.

Stale reads are possible, but the system remains responsive.

Real Use Cases of Eventual Consistency

These are places where being slightly wrong for a while is invisible or acceptable.

You refresh your feed

Social posts, likes, comments. Seeing an update a few seconds late does not matter.
You open an analytics dashboard

Metrics, charts, reports. Near-real-time is good enough.
You get recommendations

Suggested products, videos, content. Stale recommendations rarely cause harm.
You search for something

Search indexes often lag behind writes. Users expect this.
You receive notifications

Emails, push notifications, background jobs. Reliability matters more than immediacy.

The Benefits

Performance: It is incredibly fast because there is no waiting for coordination.
Resilience: Even if half the servers are having trouble communicating, the system can still accept new data and serve users.

The Trade-offs

Confusion: Users might refresh a page and see an old comment or an outdated notification.
Complexity: As a developer, you have to write code that can handle "conflicts" if two people update the same thing at the same time on different servers.

Eventual vs Strong Consistency in Practice with DynamoDB

DynamoDB is eventually consistent by default, meaning reads may return stale data immediately after a write.

You can explicitly request strong consistency on a read to guarantee the latest committed value.

This choice trades lower latency and higher availability for correctness, and you make it per request.

await dynamodb.put({
  TableName: "Users",
  Item: {
    userId: "42",
    email: "new@email.com"
  }
});

The write succeeds, but replicas may not all be updated yet.

Eventual Consistency (Default)

await dynamodb.get({
  TableName: "Users",
  Key: { userId: "42" }
});

You may receive stale data if the read hits a replica that has not applied the latest write.

Strong Consistency

await dynamodb.get({
  TableName: "Users",
  Key: { userId: "42" },
  ConsistentRead: true
});

You are guaranteed to receive the latest committed value, at the cost of higher latency and throughput usage.

Making the Right and Intentional Choice

When you design your next feature, ask yourself: "What is the worst thing that happens if a user sees data that is five seconds old?"

If the answer is "nothing much," choose eventual consistency and enjoy the extra speed. If the answer is "we lose money or trust," stick with strong consistency.

Strong consistency prioritizes correctness over availability.
Eventual consistency prioritizes availability and scale over immediacy.

By being intentional with these trade-offs, you build systems that are not just technically sound, but also aligned with what your users actually need.

What if you are to build for a 1,000,000 daily active users?

Samuel Owolabi — Tue, 20 Jan 2026 11:43:42 +0000

Two years ago, a client approached me to build an end-to-end booking ecosystem. It is a B2B platform for businesses and their customers.

For the Business Dashboard, I built a multi-tenant interface where owners could list their booking packages, manage inventory, manage customers, set booking hours and track their entire operation.

For the Customer Portal, I engineered a seamless flow for real-time booking, Stripe-integrated payment processing, automated daily booking reminders, automated receipt generation, dashboard for customers to view their bookings, reschedule bookings e.t.c.

The initial stack was the standard developer starter pack: a monolithic architecture pushed to GitHub, with Vercel and Railway handling the frontend and backend orchestration.

It was a clean implementation. It performed flawlessly. Businesses are being onboarded and setting up their booking platform, their customers are using their booking platform conveniently, the system works until last year.

When Success Breaks Everything

The platform hit a critical mass that transformed our steady growth into a high-concurrency challenge. We moved from predictable usage to a different league of infrastructure demands where every millisecond of latency translated into lost revenue.

The Shift in Request Volume
We moved from managing users to managing an onslaught. We were hitting millions of API calls and high-frequency I/O operations daily. These weren't just simple reads; they were massive surges in concurrent traffic that ignored any attempt at traditional capacity planning.

The Pressure on System Reliability
There was a much higher expectation for low latency and 99.9% uptime. The SLAs shifted overnight. We started seeing frequent service degradation because the systems were operating under constant resource exhaustion. The infrastructure was gasping for air.

The Complexity of Concurrent Sessions
As the user base grew, we faced challenges with session persistence and shared state. Managing thousands of simultaneous web socket connections for real-time availability updates meant our single-server memory was constantly hitting its ceiling.

Why Traditional Architecture Fails at Scale
When the system started buckling, it became clear that the standard deployment strategy has a ceiling. Growth doesn't just stress your code; it exposes the structural debt in your architecture.

The Catastrophe of Single Points of Failure
Our tight coupling became our biggest vulnerability. I vividly remember when the client called me around 01:00 AM because the entire production environment went down. The culprit was an SMTP timeout. Because the email service was part of the main execution thread, a transient failure in a third-party mail provider caused a deadlock that crashed the entire server.

The Bottleneck of Synchronous Execution
In the original build, everything was synchronous. When a user booked a package, the thread would stay open while processing the payment, updating the DB, and triggering transactional emails. At scale, this created massive overhead, slowing down the response.

The Silent Failures and Data Integrity
At scale, systems rarely just die; they degrade. We started seeing zombie states where a payment went through in Stripe, but the database didn't update because of a timeout. These partial failures are a nightmare for business owners because they create massive manual support work.

The Observability Gap
We are consuming high RAM usage, without evening know what part of the architecture consume that much. We were flying blind because we lacked an observability layer to track CPU Usage, latency, errors, throughput e.t.c

Database Contention Over Compute
We hit the database wall long before we hit compute limits. The primary instance was struggling to manage the lock contention between the heavy analytics queries on the business dashboard and the high-frequency writes from the customer booking portal.

What I did next?

Transitioning to a Distributed Architecture

To resolve these issues, I had to move away from the monolith and design for horizontal scalability. We transitioned the application to run across multiple stateless instances, managed by a Load Balancer and an Auto-Scaling Group (ASG).

Decoupling Data with CQRS and Read Replicas
I separated the Read and Write workloads. We implemented a Primary-Replica configuration where the primary database handles all Write operations, while multiple Read Replicas handle the query traffic. We had to manage Replication Lag to ensure the business and customer dashboard could pull analytics without dragging down the payment engine.

Multi-layer Caching and Edge Delivery
To reduce the load on our origin servers, I implemented a robust caching strategy. We utilized Cloudfront for edge caching of static assets and integrated Redis as a distributed cache for frequently accessed or computationally expensive API queries. Now loads have been reduced on databases and downstream services, and response times improved at high traffic

Asynchronous Event-Driven Architecture
The most critical shift was moving to a Producer-Queue-Consumer model. I offloaded non-critical tasks like emails, push notifications, and analytics processing to background workers using a Message Queue. This decoupled the critical path, allowing the user to receive faster response, while the request is being run as a background job. We have eliminated single points of failure.

Fault Tolerance and Cost Optimization
I deployed instances across multiple Availability Zones (AZs) which eliminated redundancy into every critical path. We set up Database Standbys and automated health checks for automatic failover. Importantly, we used Auto Scaling Groups (ASGs) to automatically scale down during low-traffic hours to ensure we weren't paying for compute we didn't need.

Centralized Logging and Real-time Telemetry
I implemented a centralized logging stack to aggregate data from every distributed instance. This allowed us to query logs across the entire cluster in real-time, making it possible to trace a single user request as it traveled through the load balancer, the API, and the background workers. I set alerts for above usage and user impacting thresholds, monitor trends not just outages. Now we know “what is slow“, “what is failing“, “what has changed“ e.t.c

Takeaway

Building for a million daily active users is less about the tools and more about the discipline of distributed systems. Today, we are managing tens of thousands of active users, but the architecture is now future-proofed to scale to a million and beyond without a total rewrite.

I started simple to prove the business model, but I documented the limits and let real-world telemetry drive our path toward high availability. It’s about being ready for success so that when a million users show up, your system and your sleep schedule can handle it.

Client vs Server-Side Encryption: The Real Meaning of End-to-End Security

Samuel Owolabi — Wed, 08 Oct 2025 21:31:37 +0000

In my early tech journey, I’d always see the phrase “End-to-End Encryption on WhatsApp” and feel a bit skeptical. 🤔 How could WhatsApp not see my messages when their servers were the ones handling them? I honestly thought it was just a clever marketing gimmick.

My curiosity grew when I started learning about crypto wallets. If I lose my seed phrase, why can’t the wallet company just hit a “reset” button and recover it for me? What was happening behind the scenes that made my data so inaccessible, even to the provider?

Later, while working on real projects, I got comfortable implementing security measures like JWT, OAuth, and password hashing with bcrypt. But for a fintech project, I faced a new challenge: encrypting sensitive data moving between our users’ devices and our server. Suddenly, I was working with concepts like AES, data keys, and key management, and it felt fundamentally different from the security tokens I was used to.

The real “aha!” moment came while I was studying for my AWS Certified Developer exam. The course material (Stephane Maarek Udemy Course) finally connected all the dots, giving me a clear picture of how encryption works on both the client’s device and the server. This article is my attempt to share those lessons and clear up the confusion in a simple, beginner-friendly way.

So, What Exactly is Encryption?

At its heart, encryption is the process of taking readable data (plaintext) and scrambling it into an unreadable format (ciphertext) using a special algorithm. The only way to unscramble that data and turn it back into readable plaintext is with the correct decryption key.

Think of it like locking a secret message in a box 📦. Anyone can see the box, but only the person who has the unique key can open it and read the message inside.

Encryption is built on two main approaches:

Symmetric Encryption: Imagine a lockbox that uses the same key to both lock and unlock it. This is great for speed. (e.g., AES).
Asymmetric Encryption: This is like having two different keys. One is a public key that you can give to anyone they can use it to put things in the box and lock it. But only you have the secret private key that can open it. (e.g., RSA).

An Analogy That Made It All Click: The Two Lockboxes

Imagine you want to send a secret letter from Alice to Bob using a courier service. How they handle security is the perfect analogy for client-side vs. server-side encryption.

Scenario 1: Server-Side Encryption (The Courier’s Lockbox)

Alice writes her letter and hands it, unsealed, to the courier. The courier puts the letter into one of their standard company lockboxes and takes it to Bob. The courier company has the master key to all their boxes. They promise not to look, but they technically could if they wanted to. This is super convenient for Alice; she doesn’t have to worry about finding or managing her own lockbox.

Scenario 2: Client-Side Encryption (Alice’s Personal Lockbox)

Alice writes her letter, but before she even calls the courier, she puts it in her own personal lockbox. Only she and Bob have a copy of the key. She then gives the already locked box to the courier. The courier can transport the box, but they have absolutely no way of opening it to see the contents. This is maximum security.

Client-Side Encryption (CSE)

Client-Side Encryption (CSE), also known as end-to-end encryption (E2EE) or zero-knowledge encryption, is the “personal lockbox” approach. The data is encrypted on your device (the client) before it’s sent to the server.

How does it work?

You create something: You type a message or create a file on your phone or computer, or data.
Encrypted on your device: The app you’re using (like WhatsApp or your crypto wallet) uses a key on your device to encrypt this data right then and there.
Scrambled data travels: The unreadable ciphertext is sent over the internet to the server.
Server stores gibberish: The server stores this ciphertext. It has no key and cannot read the data. To the server, it’s just a meaningless blob of information.
Decrypted on the other side: When your friend requests the message, the server sends them the ciphertext. Their app uses its key to decrypt the data back into a readable format on their device.

Use Cases

Social Messaging Apps (WhatsApp, Signal): This finally answered my first question! When you send a message, it’s encrypted on your phone and only decrypted on your friend’s phone. WhatsApp’s servers only pass along the scrambled data. They truly can’t read your messages.
Cryptocurrency Wallets: This solved my second puzzle! Your “seed phrase” is used to create your private key. This key lives only on your device. The wallet provider never sees it. If you lose it, it’s gone forever because they never had a copy to begin with.
Secure Cloud Storage: Services like AWS S3, Tresorit e.t.c allow you to encrypt your files before you upload them. You manage the keys, and the cloud provider simply stores the encrypted blobs.

The Pros of Client Side Encryption

Maximum Privacy & Control: You, and only you (and the recipient), hold the keys. The service provider cannot access your data.
Breach Containment: If the server is hacked, the attackers only get useless ciphertext.
Regulatory Compliance: Helps meet strict data privacy regulations like GDPR and HIPAA, as no unencrypted personal data is processed by the server.

The Cons of Client Side Encryption

Key Management Burden: If the user loses their key, the data is permanently lost. There is no “Forgot Password” option.
Limited Server Functionality: The server can’t search, index, or perform any operations on the data because it can’t read it.
Implementation Complexity: It requires more work on the client-side application.

Server-Side Encryption (SSE)

Encryption happens after data reaches the server. The server manages keys and performs encryption before storage. It is the “delivery company’s lockbox” approach. You send your data to the server, and the server takes on the responsibility of encrypting it.

How does it work?

You send your data: You upload a file or send information to the server. This connection itself is usually encrypted (this is called “in-transit” encryption, thanks to HTTPS), but the server receives the data in its original, readable form.
Server encrypts it: Once your data arrives, the server uses keys that it manages to encrypt it. This is called “encryption at rest.”
Server stores it: The server stores the resulting ciphertext.
Server decrypts for you: When you want your data back, the server fetches the ciphertext, decrypts it using its key, and sends the readable data back to you (again, over a secure connection).

Use Cases

Most Cloud Storage & Databases: When you upload a file to Google Drive, Dropbox, or a standard AWS S3 bucket, this is what’s happening. They encrypt it on their end to protect against someone physically stealing their hard drives.
Backups: When a service backs up its database, it almost always uses SSE to protect that backup file.
Key Management Systems (KMS): This is a more advanced topic, but cloud providers like AWS have services (like KMS) that make it really easy and secure for servers to manage these encryption keys.

The Pros of Server Side Encryption

Convenience: It’s seamless for the user and often simple for the developer to enable. The provider handles all the complexity of key management.
Server Functionality: Since the server can decrypt the data, it can perform useful operations like searching the content of files or indexing database fields.
Easy Recovery: Key management is centralized, so data recovery is possible.

The Cons of Server Side Encryption

The Trust Issue: You must trust the service provider. They have the keys and can technically access your data. This can be a problem if they suffer an internal breach or are compelled by a government to hand over data.
Broader Attack Surface: If an attacker compromises the server and gains access to the key management system, they could potentially decrypt all the data.

A Cool Pro Tip (Bonus): Envelope Encryption

This is a clever technique used by almost all major cloud providers (like AWS KMS) to do SSE really efficiently. Instead of using one super-strong (but slow) key to encrypt huge amounts of data, they do this:

For each file, the system generates a unique, fast key called a Data Key.
The file is quickly encrypted with this Data Key.
Then, a highly protected Master Key is used to encrypt only the tiny Data Key. 4 . The encrypted file and the encrypted Data Key are stored together.

To decrypt, the server first uses the Master Key to unlock the Data Key, and then uses that Data Key to quickly unlock the main file. It’s the best of both worlds: the top-tier security of a master key with the high performance of data keys!

So, Which One Should I Choose for My Project?

Now that we know the difference, the choice becomes a classic trade-off.

Go for Client-Side Encryption (CSE) when…

Your entire product is built on a promise of privacy and trust. You want to be able to look your users in the eye and say, “We cannot see your data, period.” This is essential for secure chat apps, password managers, and services handling extremely sensitive health or legal information.

Go for Server-Side Encryption (SSE) when…

Your priority is user convenience and providing rich features like search and data analytics. SSE is the standard for most applications. It provides a strong security baseline, protects against data center theft, and helps you meet most compliance requirements without putting the burden of key management on your users.

In Conclusion

The debate isn’t about which encryption method is “better,” but which is right for the job. It’s a fundamental choice between giving the user absolute control versus offering centralized convenience.

Understanding this difference locking the box yourself versus letting the courier lock it for you was a huge step in my developer journey. I hope this explanation clears things up for you too and helps you make more informed decisions, both as a developer building secure apps and as a user trusting services with your data.

Deploying a Node.js App to AWS Elastic Beanstalk with GitHub Actions: A Beginner's Guide

Samuel Owolabi — Fri, 08 Aug 2025 11:33:43 +0000

Automating Node.js Deployment to AWS Elastic Beanstalk with GitHub Actions

Automating the deployment of your applications can save you time and streamline your development process. This step-by-step guide will walk you through deploying a Node.js application to AWS Elastic Beanstalk and setting up a CI/CD pipeline using GitHub Actions. By the end, you'll have a fully automated workflow that tests and deploys your code every time you push to your main branch.

This tutorial is designed for beginners with a general familiarity with Git, GitHub, and AWS.

You can find the complete code for this tutorial in this GitHub repository.

What is AWS Elastic Beanstalk?

AWS Elastic Beanstalk is a service that makes it easier to deploy and manage applications in the AWS cloud. You simply upload your application, and Elastic Beanstalk automatically handles the deployment details of capacity provisioning, load balancing, auto-scaling, and application health monitoring.

Why use it?

Simplicity: It abstracts away the complexity of setting up servers, load balancers, and databases.
Scalability: It can automatically scale your application up or down based on demand.
Cost-Effective: With the AWS Free Tier, you can run a simple application like the one in this guide at no cost. You only pay for what you use as your application grows.

What is GitHub Actions?

GitHub Actions is a CI/CD (Continuous Integration/Continuous Deployment) platform that allows you to automate your build, test, and deployment pipeline. You can create workflows that build and test every pull request to your repository or deploy merged pull requests to production.

Our Workflow Structure:

Event: A trigger that starts the workflow, such as a push to a branch.
Jobs: A set of steps that execute on a runner. We will have a test job and a deploy job.
Steps: Individual tasks that run commands in a job.

Why Combine Elastic Beanstalk with GitHub Actions?

Combining these two powerful tools creates a seamless CI/CD pipeline. With every push to your repository, GitHub Actions will automatically test your Node.js application and, if the tests pass, deploy it to your Elastic Beanstalk environment. This automation eliminates manual deployment steps, reduces the risk of human error, and allows you to release new features faster.

Prerequisites

Before we start, make sure you have the following set up:

An AWS Account: You'll need an account with an IAM user that has permissions for Elastic Beanstalk. We'll create the necessary roles during the tutorial.
A GitHub Repository: This is where your Node.js application code will live. For this tutorial, we will be using a pre-configured repository.
Node.js: Ensure you have Node.js (version 18 or higher) installed on your local machine.

Let's Get Started!

Step 1: Set Up Your Node.js Application

To get you started quickly, a simple Node.js application using Express and TypeScript has been prepared.

Clone the Repository: Open your terminal and clone the sample application:

   git clone https://github.com/samowolabi/nodejs-elastic-beanstalk-with-githubactions-app.git
   cd nodejs-elastic-beanstalk-with-githubactions-app

Install Dependencies:

   npm install

This project has a straightforward structure:

.github/workflows/ci.yml: The GitHub Actions workflow file.
src/index.ts: The main application file.
test/app.test.js: A simple test file.
package.json: Defines project scripts and dependencies.
tsconfig.json: The TypeScript configuration file.

Step 2: Set Up AWS Elastic Beanstalk

Now, let's create the environment on AWS where our application will be deployed.

Navigate to Elastic Beanstalk: Log in to your AWS Management Console and go to the Elastic Beanstalk service.

Create a New Environment:
- Click on Create Application.
- Application name: Enter a name, for instance, nodejs-app-eb-gh-app.
- Platform: Select Node.js. For this guide, "Node.js 18" is used.
- Application code: Keep Sample application selected for now.
- Under Presets, select Single instance (which is free-tier eligible).
- Click Next.

Configure Service Access: This screen is crucial for granting Elastic Beanstalk the necessary permissions.

Service role: This role allows Elastic Beanstalk to manage other AWS resources on your behalf.
- If you don't have one, select Create and use new service role.
- A new window will open to create an IAM role. The role will be pre-configured. Simply click Create role.
- Back on the Elastic Beanstalk screen, refresh the dropdown and select the new role (aws-elasticbeanstalk-service-role).
EC2 instance profile: This role grants permissions to the EC2 instances that will run your application.
- Click Create and use new instance profile.
- In the new window, name your role (e.g., aws-elasticbeanstalk-ec2-new-role).
- The necessary policies (AWSElasticBeanstalkWebTier, etc.) will be attached automatically. Click Create role.
- Return to the Elastic Beanstalk screen, refresh, and select the newly created instance profile.

Review and Launch:
- You can skip the networking, database, and tags setup for this simple deployment by clicking Skip to review.
- On the Review page, look over your configurations and click Submit.

AWS will now start building your environment. This process can take a few minutes. Once it's complete, you can access the provided domain, and you will see the default sample application page.

Bonus: Setting Up Environment Variables

Your Node.js application might require environment variables. You can set them up in the Elastic Beanstalk console:

Go to your environment's page.
Click Configuration > Software > Edit.
Under Environment properties, add your key-value pairs (e.g., NODE_ENV = production). Elastic Beanstalk automatically provides the PORT variable.

Step 3: Configure the CI/CD Pipeline with GitHub Actions

Now it's time to connect your GitHub repository to your new Elastic Beanstalk environment.

Get AWS Access Keys: The GitHub Actions workflow needs credentials to deploy to your AWS account.

In the AWS IAM console, navigate to Users and select your IAM user.
Go to the Security credentials tab and click Create access key.
Select Third-party service, acknowledge the recommendation, and proceed.
You will be provided with an Access key ID and a Secret access key. Copy these immediately, as you won't be able to see the secret key again.

Note: Ensure your IAM user has the necessary permissions. For this deployment, the following policies are recommended: elasticbeanstalk:*, s3:*, ec2:*, iam:PassRole, and logs:*.

Add Credentials to GitHub Secrets:
- In your GitHub repository, go to Settings > Secrets and variables > Actions.
- Click New repository secret and add the following:
  - AWS_ACCESS_KEY_ID: Your AWS access key ID.
  - AWS_SECRET_ACCESS_KEY: Your AWS secret access key.

Understand the Workflow File: Open the .github/workflows/ci.yml file in your repository. Let's break down what it does:

   name: CI/CD

   on:
     push:
       branches: [ main, master ]
     pull_request:
       branches: [ main, master ]

   jobs:
     test:
       runs-on: ubuntu-latest

       strategy:
         matrix:
           node-version: [18.x, 20.x]

       steps:
       - name: Checkout code
         uses: actions/checkout@v4

       - name: Setup Node.js ${{ matrix.node-version }}
         uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node-version }}
           cache: 'npm'

       - name: Install dependencies
         run: npm ci

       - name: Run tests
         run: npm test

       - name: Build project
         run: npm run build

     deploy:
       needs: test
       runs-on: ubuntu-latest
       if: github.ref == 'refs/heads/main' && github.event_name == 'push'

       steps:
       - name: Checkout code
         uses: actions/checkout@v4

       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
           node-version: '20.x'
           cache: 'npm'

       - name: Install dependencies
         run: npm ci

       - name: Build project
         run: npm run build

       - name: Generate deployment package
         run: |
           zip -r deploy.zip . -x '*.git*' 'node_modules/.cache/*' 'src/*' 'test/*' '*.md' '.env*'

       - name: Deploy to Elastic Beanstalk
         uses: einaregilsson/beanstalk-deploy@v22
         with:
           aws_access_key: ${{ secrets.AWS_ACCESS_KEY_ID }}
           aws_secret_key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
           application_name: nodejs-app-eb-gh-app
           environment_name: Nodejs-app-eb-gh-app-env
           version_label: ${{ github.sha }}
           region: us-east-1
           deployment_package: deploy.zip

on: This workflow triggers on a push or pull_request to the main or master branches.
jobs:
- test: This job runs on two Node.js versions (18.x and 20.x). It checks out your code, installs dependencies, and runs your tests (npm test) and build script (npm run build).
- deploy: This job depends on the test job succeeding (needs: test). It only runs on a push to the main branch. It performs the build again, zips the necessary files into deploy.zip, and then uses the beanstalk-deploy action to push the package to your Elastic Beanstalk environment.

Important: Update the application_name, environment_name, and region in the deploy job to match your Elastic Beanstalk setup.

Step 4: Deploy the Application

Now for the magic moment!

Push to Main: Commit any changes you've made and push them to your main branch.

   git add .
   git commit -m "feat: setup CI/CD and deploy to Elastic Beanstalk"
   git push origin main

Monitor the Workflow: Go to the Actions tab in your GitHub repository. You will see your workflow running. Click on it to see the test and deploy jobs in action.

Verify Deployment: Once the deploy job is complete, navigate back to your Elastic Beanstalk environment's URL. You should now see the message: "Hello, TypeScript with Express!".

Conclusion and Troubleshooting

Congratulations! You have successfully set up a fully automated CI/CD pipeline. Every time you push a change to your main branch, GitHub Actions will test your code and deploy it to AWS Elastic Beanstalk.

Common Issues:

Deployment Fails: Double-check that your AWS credentials in GitHub Secrets are correct and that the IAM user has the required permissions. Verify that the application and environment names in your ci.yml file match your Elastic Beanstalk setup exactly.
Build/Test Failures: Run npm test and npm run build locally to debug any issues before pushing.
Check Logs: The first place to look for errors is the GitHub Actions log. For environment-specific issues, check the logs in your AWS Elastic Beanstalk console (Logs > Request Logs > Last 100 Lines).

This automated workflow is a fundamental practice in modern web development that will significantly improve your development and release process.

A practical guide by Samuel Owolabi

Don't Reach for Redux Just Yet: Mastering State with React Context, useReducer, and TypeScript

Samuel Owolabi — Tue, 22 Jul 2025 21:03:16 +0000

A practical guide by Samuel Owolabi

What if you don't actually need Zustand, Jotai, or Redux for your next project?

Hear me out. Those are fantastic libraries, but for a huge number of applications, you can build a powerful, scalable, and type-safe state management system using the tools React already gives you. The secret lies in combining React Context with the useReducer hook and wrapping it all in the warm, safe blanket of TypeScript.

The purpose of this guide is to show you exactly how to set up this pattern in a simple, practical way. We'll cover a real-world example to show how flexible this approach is. Don't be overwhelmed! By the end, you'll be able to manage complex state with confidence.

We'll build a state management system for a simple fintech dashboard. This will allow us to handle things like:

User authentication (login/logout)
A theme switcher (dark/light mode)
User's wallet data (adding, removing, and updating wallets)
A global token for API requests
A selected currency for display

Ready? Let's dive in.

The Core Concepts: What Are We Using and Why?

First, let's quickly break down the tools we're bringing together.

What is React Context? 📝

React Context provides a way to pass data through the component tree without having to pass props down manually at every level. This is the perfect tool for sharing "global" data like the current user, theme, or language. It helps us avoid a problem called "prop drilling."

What is the useReducer Hook? ⚙️

useReducer is a React hook that you can, and should, use as an alternative to useState when you have complex state logic. Instead of just updating the state directly, you "dispatch" actions. A "reducer" function then takes the current state and an action and returns the new state. If you've ever used Redux, this pattern will feel very familiar. It helps keep your state transitions predictable and organized.

Why Add TypeScript to the Mix? 🛡️

TypeScript is a superset of JavaScript that adds static types. Here's why it's a game-changer for this pattern:

Type Safety: It prevents you from putting the wrong kind of data into your state.
Amazing Autocomplete: TypeScript knows exactly what your state looks like. When you type state., it will show you all the available properties.
Smarter Actions: It ensures you dispatch actions with the correct type and payload. For example, if your ADD_WALLET action needs a WalletType payload, TypeScript will give you an error if you try to send a simple string. This catches bugs before you even run the code.

The Folder Structure

We'll organize our context logic into a dedicated contexts folder. This keeps the state management code neatly separated from our UI components. For a Next.js App Router project, it might look like this:

/src
|-- /app
|   |-- layout.tsx          # We'll wrap our app here
|   |-- usage-examples.tsx  # Component to test our context
|
|-- /contexts
|   |-- appContext.tsx      # The main context provider file
|   |-- reducer.tsx         # The reducer function and initial state
|   |-- reducerTypes.tsx    # All our TypeScript types

Step 1: Define Your Types (reducerTypes.tsx)

This is the most important step for achieving type safety. We start by defining the "shape" of our state, the actions we can perform, and the context itself. By doing this first, we let TypeScript guide us through the rest of the implementation.

Here we define the shape of a user's wallet, the entire application state (ContextStateType), and most importantly, our actions. We use a discriminated union for ContextActionTypes. This is a fancy term for a pattern where each object type in the union has a common property (in our case, type) that TypeScript can use to figure out the exact shape of the action, including its payload.

contexts/reducerTypes.tsx

import { Dispatch } from 'react';

export type WalletType = {
    currency: string,
    availableBalance: number,
    pendingBalance: number,
}

export type ContextStateType = {
    theme: 'light' | 'dark',
    selectedCurrency: string,
    userData: {
        firstName: string,
        lastName: string,
        email: string
    },
    token: string, // For API Requests Authentication
    wallets: WalletType[]
}

// Discriminated union for our action types
export type ContextActionTypes = (
    {
        type: 'SET_THEME',
        payload: ContextStateType['theme']
    } | {
        type: 'SET_SELECTED_CURRENCY',
        payload: ContextStateType['selectedCurrency']
    } | {
        type: 'LOGIN_USER',
        payload: ContextStateType['userData']
    } | {
        type: 'SET_TOKEN',
        payload: ContextStateType['token']
    } | {
        type: 'LOGOUT_USER' // An action with no payload
    } | {
        type: 'SET_WALLETS',
        payload: ContextStateType['wallets']
    } | {
        type: 'UPDATE_WALLET',
        payload: WalletType
    } | {
        type: 'ADD_WALLET',
        payload: WalletType
    } | {
        type: 'REMOVE_WALLET',
        payload: WalletType['currency']
    }
)

// Type for our reducer function
export type ReducerType = (
    state: ContextStateType,
    action: ContextActionTypes
) => ContextStateType;

// Type for the context value that will be provided
export type ContextValueType = {
    state: ContextStateType;
    dispatch: Dispatch<ContextActionTypes>;
}

Step 2: Create the Reducer Function (reducer.tsx)

The reducer is the heart of our state logic. It's a pure function that takes the previous state and an action, and returns the next state. We'll also define our initialState here.

Notice how the switch statement handles each action type we defined earlier. Thanks to our discriminated union, if action.type is 'ADD_WALLET', TypeScript knows that action.payload must be a WalletType object.

contexts/reducer.tsx

import { ContextStateType, ContextActionTypes, ReducerType } from './reducerTypes';

// Initial state for the reducer
export const initialState: ContextStateType = {
    theme: 'light',
    selectedCurrency: 'USD',
    userData: {
        firstName: '',
        lastName: '',
        email: ''
    },
    token: '',
    wallets: []
};

export const reducer: ReducerType = (state: ContextStateType, action: ContextActionTypes): ContextStateType => {
    switch (action.type) {
        case 'SET_THEME':
            return { ...state, theme: action.payload };

        case 'SET_SELECTED_CURRENCY':
            return { ...state, selectedCurrency: action.payload };

        case 'LOGIN_USER':
            return { ...state, userData: action.payload };

        case 'SET_TOKEN':
            return { ...state, token: action.payload };

        case 'LOGOUT_USER':
            return {
                ...state,
                userData: initialState.userData,
                token: ''
            };

        case 'SET_WALLETS':
            return { ...state, wallets: action.payload };

        case 'UPDATE_WALLET':
            return {
                ...state,
                wallets: state.wallets.map(wallet =>
                    wallet.currency === action.payload.currency
                        ? { ...wallet, ...action.payload }
                        : wallet
                )
            };

        case 'ADD_WALLET':
            const walletExists = state.wallets.some(wallet => wallet.currency === action.payload.currency);
            if (walletExists) {
                // If wallet exists, update it instead of adding a duplicate
                return {
                    ...state,
                    wallets: state.wallets.map(wallet =>
                        wallet.currency === action.payload.currency
                            ? action.payload
                            : wallet
                    )
                };
            }
            // Add new wallet
            return { ...state, wallets: [...state.wallets, action.payload] };

        case 'REMOVE_WALLET':
            return {
                ...state,
                wallets: state.wallets.filter(wallet => wallet.currency !== action.payload)
            };

        default:
            return state;
    }
};

Step 3: Build the Context Provider (appContext.tsx)

Now we tie everything together. In this file, we:

Create the context using createContext().
Create the AppProvider component. This component will use our useReducer hook to create the state and dispatch function. It then makes them available to all of its children via the <AppContext.Provider> component.
Create a custom hook useAppContext(). This is a best practice that makes consuming the context much cleaner and safer in our components. It abstracts the useContext call and also throws an error if we try to use the context outside of its provider.

contexts/appContext.tsx

import React, { createContext, useContext, useReducer, ReactNode } from 'react';
import { ContextStateType, ContextActionTypes, ContextValueType } from './reducerTypes';
import { reducer, initialState } from './reducer';

// Create the context
const AppContext = createContext<ContextValueType | undefined>(undefined);

// Provider component props
interface AppProviderProps {
    children: ReactNode;
}

// Provider component
export const AppProvider: React.FC<AppProviderProps> = ({ children }) => {
    const [state, dispatch] = useReducer(reducer, initialState);

    const value: ContextValueType = {
        state,
        dispatch
    };

    return (
        <AppContext.Provider value={value}>
            {children}
        </AppContext.Provider>
    );
};

// Custom hook to use the context
export const useAppContext = (): ContextValueType => {
    const context = useContext(AppContext);

    if (context === undefined) {
        throw new Error('useAppContext must be used within an AppProvider');
    }

    return context;
};

Step 4: Wrap Your App (layout.tsx)

For our context to be available everywhere, we need to wrap our entire application with the AppProvider we just created. In a Next.js app, the root layout.tsx is the perfect place to do this.

layout.tsx

import React, { ReactNode } from 'react';
import { AppProvider } from '@/contexts/appContext';

// Root Layout Component
export default async function RootLayout({
    children,
}: {
    children: ReactNode
}) {
    return (
        <html lang="en">
            <body>
                {/* Wrap the entire app with AppProvider */}
                <AppProvider>
                    {children}
                </AppProvider>
            </body>
        </html>
    );
}

Step 5: Using Your New Context! (usage-examples.tsx)

Setup complete! Now for the fun part: using it.

In any component that's a child of AppProvider, you can now use your custom useAppContext hook to get access to the state and the dispatch function.

Here are a few examples of how you might read data and dispatch actions.

app/usage-examples.tsx

import React from 'react';
import { useAppContext } from '@/contexts/appContext';

export const UsageExamples = () => {
    const { state, dispatch } = useAppContext();

    // --- Accessing State Data ---
    const currentTheme = state.theme; // 'light' or 'dark'
    const isLoggedIn = state.userData.email !== '';
    const usdWallet = state.wallets.find(wallet => wallet.currency === 'USD');

    // --- Dispatching Actions ---

    // Toggle between light and dark theme
    const toggleTheme = () => {
        const newTheme = state.theme === 'light' ? 'dark' : 'light';
        dispatch({
            type: 'SET_THEME',
            payload: newTheme
        });
    };

    // Set user data when logging in
    const loginUser = () => {
        dispatch({
            type: 'LOGIN_USER',
            payload: {
                firstName: 'John',
                lastName: 'Doe',
                email: 'john.doe@example.com'
            }
        });
        // Try sending the wrong payload and see TypeScript complain!
        // dispatch({ type: 'LOGIN_USER', payload: 'wrong data' });
    };

    // Add a new wallet
    const addWallet = () => {
        dispatch({
            type: 'ADD_WALLET',
            payload: {
                currency: 'ETH',
                availableBalance: 2.5,
                pendingBalance: 0.1
            }
        });
    };

    // Remove wallet by currency
    const removeWallet = () => {
        dispatch({
            type: 'REMOVE_WALLET',
            payload: 'BTC' // Payload is just a string, as we defined!
        });
    };

    // ... other functions

    return (
        <div>
            <h2>Welcome, {isLoggedIn ? state.userData.firstName : 'Guest'}!</h2>
            <p>Current Theme: {currentTheme}</p>
            <button onClick={toggleTheme}>Toggle Theme</button>
            <button onClick={loginUser}>Login</button>
            {/* ... other UI elements */}
        </div>
    );
};

Bonus: How to Persist State on Refresh?

You're right, there's one problem. If you refresh the page, all your state disappears! We can solve this by syncing our state with the browser's localStorage.

Here is an enhanced version of appContext.tsx that saves the state to localStorage whenever it changes and loads it back on the initial render. This uses the logic from your appContextWithPersistence.tsx file.

contexts/appContext.tsx

import React, { createContext, useContext, useReducer, useEffect, ReactNode } from 'react';
import { ContextStateType, ContextActionTypes, ContextValueType } from './reducerTypes';
import { reducer, initialState } from './reducer';

const AppContext = createContext<ContextValueType | undefined>(undefined);

// Helper function to get initial state from localStorage
const getPersistedState = (): ContextStateType => {
    if (typeof window === 'undefined') {
        return initialState; // Default for server-side rendering
    }
    try {
        const theme = localStorage.getItem('app_theme') as 'light' | 'dark' || initialState.theme;
        const selectedCurrency = localStorage.getItem('app_selectedCurrency') || initialState.selectedCurrency;
        const userData = JSON.parse(localStorage.getItem('app_userData') || 'null') || initialState.userData;
        const wallets = JSON.parse(localStorage.getItem('app_wallets') || 'null') || initialState.wallets;

        return {
            ...initialState, // Start with defaults
            theme,
            selectedCurrency,
            userData,
            wallets,
        };
    } catch (error) {
        console.error('Error loading persisted state:', error);
        return initialState;
    }
};

// Helper function to save state to localStorage
const saveToStorage = (state: ContextStateType) => {
    if (typeof window === 'undefined') return;
    try {
        localStorage.setItem('app_theme', state.theme);
        localStorage.setItem('app_selectedCurrency', state.selectedCurrency);
        localStorage.setItem('app_userData', JSON.stringify(state.userData));
        localStorage.setItem('app_wallets', JSON.stringify(state.wallets));
    } catch (error) {
        console.error('Error saving state to localStorage:', error);
    }
};

export const AppProvider: React.FC<{ children: ReactNode }> = ({ children }) => {
    // Pass the getPersistedState function as the third argument to useReducer
    const [state, dispatch] = useReducer(reducer, initialState, getPersistedState);

    // Save state to localStorage whenever it changes
    useEffect(() => {
        saveToStorage(state);
    }, [state]);

    return (
        <AppContext.Provider value={{ state, dispatch }}>
            {children}
        </AppContext.Provider>
    );
};

export const useAppContext = (): ContextValueType => {
    const context = useContext(AppContext);
    if (context === undefined) {
        throw new Error('useAppContext must be used within an AppProvider');
    }
    return context;
};

Key changes:

A getPersistedState function lazy-initializes our reducer's state with data from localStorage. We pass it as the third argument to useReducer.
A saveToStorage function is called inside a useEffect hook that listens for any changes to the state object. When a change occurs, it saves the new state to localStorage. We've also taken care not to persist sensitive data like an authentication token by always starting with the initialState.

To use this, you would simply import AppProvider from this persistence file instead of the original appContext.tsx in your layout.tsx.

Download full code on my GitHub repo

Conclusion

And there you have it! You've successfully built a robust, type-safe, and maintainable state management solution using only React's built-in tools and TypeScript.

While state management libraries like Redux, Zustand, and Jotai have their place, especially in very large-scale applications, this useContext + useReducer pattern is often more than enough. It gives you centralized logic, predictable state transitions, and top-tier developer experience thanks to TypeScript, all without adding another dependency to your project.

Happy coding!

This article was crafted with care by Samuel Owolabi. Find more of his work on his portfolio.