The Boundary Between Good Code and Good Systems
Good code solves local problems. Good systems survive changing requirements, failures, unexpected inputs, and the engineers who maintain them.
Software / field notesThe Code Is Not the System
It is easy to think about software one function at a time.
A function receives input, performs some work, and returns an output. If the function is correct, the code feels correct.
Real systems are rarely that simple.
A production application is a collection of boundaries:
- a browser talks to an API
- an API talks to a database
- a service calls another service
- a queue moves work between processes
- a cache changes where data comes from
- an external provider introduces behavior you do not control
The difficult bugs often appear between these components.
That is why a useful engineering question is not only:
It is also:
That question moves the focus from individual code to system behavior.
Boundaries Are Where Assumptions Meet
Every software boundary contains assumptions.
Consider a simple API response:
{
"user": {
"id": 42,
"name": "Gulshan"
}
}The frontend may assume that user always exists.
The backend may assume that the database always returns a valid record.
The database may return no record at all.
Now the system has three different assumptions about the same piece of data.
The resulting bug may not belong entirely to any one component.
It exists at the boundary.
Make the Contract Explicit
A better system defines what can cross the boundary.
For example:
type UserResponse = {
user: {
id: number;
name: string;
} | null;
};Now the frontend cannot pretend that a user always exists.
The type becomes a small piece of documentation and a small piece of protection.
The important idea is not TypeScript itself.
The important idea is making assumptions visible.
Validate at the Boundary
Validation is most useful where untrusted or uncertain data enters a system.
For example:
function isValidUserResponse(value: unknown): value is UserResponse {
if (!value || typeof value !== "object") {
return false;
}
const response = value as { user?: unknown };
if (response.user === null) {
return true;
}
if (!response.user || typeof response.user !== "object") {
return false;
}
const user = response.user as Record<string, unknown>;
return (
typeof user.id === "number" &&
typeof user.name === "string"
);
}This looks more verbose than simply trusting the response.
That is intentional.
A boundary is where defensive code pays for itself.
A System Is a Chain of Contracts
One useful way to reason about a system is to describe each boundary as a contract.
| Boundary | Producer | Consumer | Important contract |
|---|---|---|---|
| UI → API | Browser | Server | Request shape |
| API → Database | Service | Database | Query and schema |
| Service → Service | Internal API | Another service | Response contract |
| Application → Queue | Producer | Worker | Event schema |
| Application → External API | Your system | Provider | Authentication and response behavior |
The exact technologies do not matter.
The principle does.
If every boundary has an explicit contract, debugging becomes narrower.
Instead of asking:
you can ask:
That is a much smaller question.
Small Questions Beat Large Debugging Sessions
The most expensive debugging habit is changing several things at once.
It feels productive because the screen changes quickly.
It is not productive if you no longer know which change helped.
Suppose a page suddenly stops rendering.
A weak debugging strategy is:
- update dependencies
- rewrite the component
- change the API response
- modify CSS
- restart the database
- try again
If the page starts working, you still do not know what actually fixed it.
A better approach is to shrink the question.
Ask One Boundary Question
For example:
Does the data shape returned by the API match what this component expects?That creates a small experiment.
Log the boundary:
console.log("API response:", response);
console.log("Expected user:", response.user);Then compare the actual value with the expected contract.
If the response is wrong, the search moves toward the API.
If the response is correct, the search moves toward rendering.
The debugging tree becomes smaller.
Observability Turns Behavior Into Evidence
Logs are useful, but production systems need more than random console.log statements.
A useful system makes important events observable.
For example:
logger.info({
event: "payment.request.completed",
requestId,
userId,
durationMs,
status: "success",
});Now an engineer can ask:
- How often does this happen?
- How long does it take?
- Which request caused it?
- Did the database call succeed?
- Did the external provider respond?
Without those signals, debugging becomes archaeology.
The Three Basic Signals
A practical starting point is:
- logs for events
- metrics for behavior over time
- traces for request flow across services
They answer different questions.
| Signal | Best question |
|---|---|
| Logs | What happened? |
| Metrics | How often or how much? |
| Traces | Where did time or failure occur? |
You do not need a giant observability platform before these concepts become useful.
Even a small application benefits from structured thinking about evidence.
Failure Should Have a Shape
Failures are unavoidable.
The important question is what the system does when they happen.
Consider an external API call:
async function fetchProfile(id: string) {
const response = await fetch(`/api/profile/${id}`);
if (!response.ok) {
throw new Error(`Profile request failed: ${response.status}`);
}
return response.json();
}This is better than silently returning an empty object.
An empty object can make the application continue with incorrect assumptions.
An explicit failure gives the system an opportunity to respond correctly.
Not Every Failure Should Crash Everything
A resilient system distinguishes between failures.
For example:
Database unavailable
↓
Retry?
↓
Temporary failure?
↓
Yes → retry with backoff
↓
Still failing
↓
Fallback / graceful degradation
↓
Record the failure
↓
Alert if necessaryThe correct response depends on the operation.
A failed analytics request may be acceptable if the rest of the application works.
A failed authentication check may require stopping the request completely.
A failed payment should never be treated like a missing profile image.
The system needs failure semantics, not just error handling.
Small Changes Create Better Feedback Loops
When debugging or evolving a system, prefer changes that are:
- small
- observable
- reversible
- isolated
- easy to verify
For example:
git checkout -b fix/api-contract-validationMake one change.
Run the relevant test.
Inspect the result.
Then commit:
git add .
git commit -m "fix: validate user response contract"Now the change has a clear boundary.
If it fails later, you know what changed.
This is not bureaucracy.
It is a debugging tool.
Architecture Should Reduce the Cost of Change
Good architecture is not about having the most folders.
It is about making change predictable.
Suppose an application contains:
components/
services/
database/
external/That structure alone tells us very little.
A better architectural question is:
If replacing one external provider requires modifying twenty unrelated components, the boundary is weak.
If the provider is isolated behind an interface:
interface PaymentProvider {
createPayment(input: PaymentInput): Promise<PaymentResult>;
refund(paymentId: string): Promise<RefundResult>;
}then the rest of the application depends on a stable contract.
The implementation can change behind it.
That is the real value of abstraction.
Good Abstractions Have a Cost
Abstraction is useful, but too much abstraction creates another problem.
A five-line operation does not always need:
Controller
↓
Service
↓
Use Case
↓
Repository
↓
Gateway
↓
Adapter
↓
FactoryArchitecture should match the problem.
A useful rule is:
Do not add a boundary merely because a framework example contains one.
Complexity Should Earn Its Place
Every abstraction introduces:
- another file
- another interface
- another mental model
- another place to debug
The benefit must be larger than the cost.
This is especially important in small applications.
A simple system that is easy to understand can be more reliable than an over-engineered system that technically follows every architectural pattern.
Tests Are Executable Contracts
A good test does more than verify that code currently works.
It documents what the system promises.
For example:
it("rejects an invalid user response", () => {
const response = {
user: {
id: "42",
name: "Gulshan",
},
};
expect(isValidUserResponse(response)).toBe(false);
});This test captures a boundary contract.
If someone changes the API later and accidentally converts id into a string, the test explains why the change matters.
Test the Important Boundaries
Not every line needs a test.
Focus first on:
- authentication
- data validation
- persistence
- external APIs
- critical business rules
- failure handling
- transformations between systems
A useful test suite gives confidence where mistakes are expensive.
Reliability Comes From Feedback Loops
Reliable systems are not systems where nothing ever goes wrong.
They are systems where failure creates information.
A healthy feedback loop looks like:
Change
↓
Test
↓
Deploy
↓
Observe
↓
Detect
↓
Understand
↓
Improve
↓
Change againThe shorter and clearer this loop becomes, the easier it is to improve the system.
That is why CI, tests, logs, metrics, code review, and small deployments are connected ideas.
They all reduce uncertainty.
The Difference Between Code Quality and System Quality
Code quality asks questions like:
- Is this function readable?
- Are names meaningful?
- Is the logic understandable?
- Are edge cases handled?
System quality asks larger questions:
- What happens when a dependency fails?
- What happens when data is malformed?
- Can the problem be observed?
- Can the system recover?
- Can another engineer understand the failure?
- Can one component change without breaking everything else?
Both matter.
Clean functions cannot rescue a system with undefined boundaries.
Likewise, a beautifully designed architecture cannot rescue unreadable code.
Good engineering happens when both levels reinforce each other.
A Practical Engineering Checklist
Before calling a feature complete, ask:
- What does this component receive?
- What does it guarantee?
- What assumptions does its consumer make?
- Where is the boundary?
- What happens with invalid input?
- What happens when a dependency is unavailable?
- How will I know that something failed?
- Can I test the failure?
- Can I roll the change back?
- Can another engineer understand the behavior?
These questions are often more valuable than another framework or another abstraction.
Final Thought
The difference between good code and a good system is not the number of technologies involved.
It is the quality of the boundaries.
A function can be perfectly written and still participate in a fragile system.
A small application can have very little infrastructure and still be remarkably resilient if its contracts are clear, failures are visible, and changes are easy to reason about.
When something breaks, the goal should not be to search the entire application.
Start at the boundary.
Ask a smaller question.
Collect evidence.
Change one thing.
Then verify what actually happened.
That is how software becomes easier to build, easier to debug, and much harder to accidentally break.
