DEV Community: Margaret Apiyo

System Architecture Fundamentals: A Beginner’s Guide to Building Better Software

Margaret Apiyo — Thu, 08 Oct 2026 15:28:42 +0000

When you're learning software development, it's easy to focus entirely on writing code.

You learn a programming language, build a frontend, connect a database, create an API, and eventually develop an application that works.

But as your projects grow, you may start asking different questions.

Where should business logic live?
How should the frontend communicate with the backend?
What happens when the database becomes unavailable?
How do you organize code so that adding new features doesn't break existing ones?
How do large applications handle thousands or even millions of users?

These questions go beyond writing individual functions or fixing bugs. They involve understanding system architecture.

System architecture helps developers understand how different parts of an application fit together, why they are organized in a particular way, and how they work together to solve a problem.

In this article, we'll explore the fundamentals of system architecture, examine common architectural patterns, and walk through a practical example to help you understand how these concepts apply to real-world software development.

You don't need to be an experienced developer to follow along. We'll start with the basics and build from there.

1. What Is System Architecture?

System architecture is the high-level structure of a software system.

It describes the system's major components, the responsibilities of those components, how they communicate, and how they work together to deliver functionality.

Think of it like the architectural plan for a house.

Before constructing a house, an architect considers where the rooms will be located, how people will move between them, where the plumbing will go, and how the electrical systems will work.

Without a plan, the house might still be built, but making changes later could become expensive and complicated.

Software works similarly.

Before building a complex application, developers need to consider how its different parts will interact.

For example, a typical web application might contain:

Frontend: The interface users interact with.
Backend: The server-side code that processes requests.
Database: The system that stores application data.
Authentication: The mechanisms that verify user identities and manage access.
Infrastructure: The servers, networks, and services that run the application.

Each component has a purpose, and the architecture defines how those components work together.

The important thing to understand is that system architecture isn't simply about choosing technologies. It's about making decisions concerning the structure and behavior of a system.

2. Why Does System Architecture Matter?

You might wonder why architecture matters when you can simply start coding and organize everything later.

For small projects, this approach can work for a while.

However, as an application grows, poorly considered design decisions can create problems.

Imagine building a task management application.

Initially, it allows users to create and delete tasks. Later, you add user accounts, teams, notifications, file attachments, and reporting.

If all the functionality is tightly connected, adding a new feature might require modifying several unrelated parts of the application.

This makes the system harder to understand, test, and maintain.

A good architecture helps address these challenges.

Maintainability

Maintainability refers to how easily developers can understand, modify, and extend a system.

When responsibilities are clearly separated, changes become easier to manage.

For example, changing how an application sends emails should not require rewriting its task management logic.

Scalability

Scalability describes a system's ability to handle increased demand.

As more users join an application, it may need additional computing resources, better database queries, or improved request handling.

A thoughtful architecture makes it easier to identify where these improvements are needed.

Reliability

Reliable systems continue to provide their intended functionality under expected operating conditions and handle failures appropriately.

Architecture helps developers plan for problems such as unavailable databases, failed requests, and interrupted background jobs.

Security

Architecture influences how users authenticate, how permissions are enforced, and how sensitive information is protected.

For example, an application should not rely solely on its frontend to prevent unauthorized users from accessing private information.

The backend must enforce those permissions as well.

Team collaboration

Clear architectural boundaries help developers work on different parts of an application without constantly interfering with one another's work.

The goal of system architecture is not to make software complicated. It's to make complexity manageable.

3. Understanding the Main Components of a Software System

Let's examine the basic components of a typical web application.

We'll use a simple blog platform as an example.

Users should be able to create accounts, publish articles, read posts, and leave comments.

How would we organize such a system?

The frontend

The frontend is the part of the application users see and interact with.

It includes elements such as:

Navigation menus.
Forms.
Buttons.
Article pages.
User profiles.
Comment sections.

Technologies such as HTML, CSS, JavaScript, React, and Vue.js are commonly used to build frontend applications.

When a user clicks the button to publish an article, the frontend collects the necessary information and sends a request to the backend.

The backend

The backend processes requests and implements server-side application behavior.

For our blog platform, it might handle:

Creating articles.
Validating user input.
Checking permissions.
Retrieving published posts.
Managing comments.
Coordinating database operations.

The backend acts as the application's central processing layer, although some responsibilities may be delegated to other services.

Common backend technologies include Node.js, Python, Java, Go, PHP, and C#.

The database

The database stores information the application needs to retain.

For our blog platform, this might include:

User accounts.
Articles.
Comments.
Publication dates.
User permissions.

PostgreSQL and MySQL are examples of relational databases commonly used for this type of application.

The backend communicates with the database to create, retrieve, update, and delete records.

The infrastructure

Infrastructure refers to the resources and services required to run the application.

Examples include:

Servers or cloud computing instances.
Networking.
File storage.
Domain names.
Load balancers.
Monitoring systems.

Infrastructure becomes increasingly important when deploying an application and making it accessible to users.

How do these components work together?

Consider what happens when a user publishes an article.

The user writes an article in the frontend.
The frontend sends the article data to the backend.
The backend verifies the user's identity and permissions.
The backend validates the article's contents.
The backend saves the article in the database.
The backend returns a response indicating whether the operation succeeded.
The frontend displays the appropriate message to the user.

The interaction can be represented as:

        USER
          |
          v
      FRONTEND
          |
          | HTTP Request
          v
       BACKEND
          |
          | Validate and Process
          v
       DATABASE
          |
          | Return Result
          v
       BACKEND
          |
          | HTTP Response
          v
      FRONTEND
          |
          v
        USER

This is a simplified representation, but it demonstrates a fundamental architectural idea:

A software system consists of components with different responsibilities that communicate to accomplish a shared goal.

4. What Is the Difference Between System Architecture and System Design?

These terms are closely related and are sometimes used interchangeably, but they often describe different levels of decision-making.

System architecture

System architecture focuses on the overall structure of a system.

Questions include:

Should the application be a monolith or use microservices?
Which major components are required?
How should those components communicate?
Where should data be stored?
How should security and reliability be handled?

System design

System design often focuses on how the system or its individual components should work in greater detail.

Questions include:

What should the database schema look like?
Which API endpoints are required?
How should a particular algorithm work?
Which indexes will improve a database query?
How should a specific feature handle concurrent requests?

The distinction is not absolute. System design can include high-level architectural decisions, while architecture also involves detailed decisions when those decisions affect the system's structure.

A useful way to think about it is:

Architecture establishes the overall structure; design determines how the components are implemented within that structure.

Both are important when building reliable software.

5. Common Architectural Patterns You Should Know

An architectural pattern is a reusable approach to organizing a software system.

Different patterns solve different problems. Understanding their strengths and limitations helps you make better architectural decisions.

Let's explore three important patterns.

A. Monolithic Architecture

A monolithic application is built and deployed as a single application unit.

Its functionality may be divided into modules, but those modules generally belong to the same deployable application.

For example:

          WEB CLIENT
              |
              v
     MONOLITHIC APPLICATION
     +---------------------+
     | Authentication      |
     | Article Management  |
     | Comments            |
     | Notifications       |
     +---------------------+
              |
              v
           DATABASE

All four responsibilities are handled within one application.

Advantages
Relatively simple to develop and deploy.
Easier to get started with.
Often requires less infrastructure.
Database transactions can be straightforward when operations use the same database.
Disadvantages
The codebase may become difficult to maintain if modules are poorly organized.
Deploying a change may require redeploying the entire application.
Scaling individual features independently can be difficult.
Poorly defined boundaries can create tight coupling.
When should you use it?

A monolith is often an excellent starting point for personal projects, startups, small teams, and applications that don't require independent service deployment.

A well-structured monolith can support substantial growth.

The important distinction is between a modular monolith, which maintains clear internal boundaries, and a poorly organized monolith in which everything depends on everything else.

B. Layered Architecture

Layered architecture organizes an application into layers, each with a defined responsibility.

A common structure looks like this:

+-------------------------+
|   Presentation Layer    |
+-------------------------+
             |
             v
+-------------------------+
|   Application Layer     |
+-------------------------+
             |
             v
+-------------------------+
|    Business Layer       |
+-------------------------+
             |
             v
+-------------------------+
|     Data Access Layer   |
+-------------------------+
             |
             v
+-------------------------+
|        Database         |
+-------------------------+

Let's understand these layers.

Presentation layer: Handles the interface through which users or external clients interact with the system.

**Application layer: **Coordinates use cases, such as publishing an article or registering a user.

Business layer: Contains the rules that define how the application operates.

Data access layer: Handles communication with the database or other data sources.

For example, when a user publishes an article:

The presentation layer sends the request.
The application layer coordinates the publishing operation.
The business layer checks relevant rules.
The data access layer saves the article.
The result travels back through the application to the client.

Advantages

Responsibilities are easier to identify.
Code is easier to organize.
Testing individual responsibilities becomes more manageable.
Developers can understand where different operations belong.

Disadvantages

Too many layers can create unnecessary complexity.
Poorly designed layers may depend too heavily on one another.
A change can sometimes require modifications across several layers.

Layered architecture is a useful starting point for understanding how to organize backend applications.

C. Microservices Architecture

Microservices architecture divides an application into multiple independently deployable services organized around specific responsibilities or business capabilities.

Instead of one application handling everything, different services manage different parts of the system.

For example, an e-commerce platform might contain:

              WEB CLIENT
                   |
                   v
               API GATEWAY
                   |
          +--------+--------+
          |        |        |
          v        v        v
       USER      ORDER    PAYMENT
      SERVICE    SERVICE   SERVICE
          |        |        |
          v        v        v
       USER DB   ORDER DB  PAYMENT DB

In this example:

The user service manages user-related functionality.
The order service manages orders.
The payment service coordinates payment operations.
Each service can have its own implementation and, where appropriate, its own data store.

Services communicate through APIs, messages, or events.

Advantages

Services can be deployed independently.
Individual services can scale according to their workloads.
Teams can own separate business capabilities.
Failures can sometimes be isolated more effectively.
Disadvantages
More infrastructure is required.
Network communication introduces additional failure possibilities.
Monitoring and debugging become more complicated.
Maintaining data consistency across services requires careful design.
Deployment and operational management can become significantly harder.
When should you use it?

Microservices can be useful when an application has clear business boundaries, multiple teams need independent deployment, or different components have substantially different scaling requirements.

However, they are not automatically better than monolithic architecture.

For beginners, the most important lesson is this:

Start with the simplest architecture that meets your requirements. Introduce additional complexity when there is a clear reason to do so.

6. What Is Separation of Concerns?

Separation of concerns is a software engineering principle that encourages developers to organize code so that different responsibilities are handled independently.

Imagine a function that:

Validates user credentials.
Queries a database.
Generates an authentication token.
Sends an email.
Formats an HTTP response.

Such a function has too many responsibilities.

Changing one behavior could affect several others, and testing the function becomes more complicated.

A better approach is to separate these responsibilities into appropriate components.

For example:

Authentication Controller
          |
          v
Authentication Service
          |
          +------> User Repository
          |
          +------> Token Service
          |
          +------> Email Service

The controller handles the incoming request and outgoing response.

The authentication service coordinates the authentication process.

The repository retrieves user information.

The token service handles token-related operations.

The email service sends messages when required.

These components can still work together, but each has a clearer responsibility.

Separation of concerns helps improve:

Readability.
Testability.
Maintainability.
Reusability.
Collaboration.

However, separation does not mean creating a separate class or service for every small operation.

The goal is to establish useful boundaries, not to maximize the number of components.

7. How Should You Choose a Database?

Database selection is another important architectural decision.

Different databases are designed to support different data models and access patterns.

Two broad categories are relational databases and NoSQL databases.

Relational databases

Relational databases organize information into tables with defined relationships.

For example, a blog application might have these tables:

Users

id  name    email
1   Alice   alice@example.com
2   Brian   brian@example.com

Articles

id  user_id title
101 1   Learning System Architecture
102 2   Getting Started with APIs

The user_id column connects an article to its author.

PostgreSQL and MySQL are popular relational database options.

They are often suitable when applications require structured data, relationships between records, and transactional guarantees.

NoSQL databases

NoSQL is a broad category that includes document databases, key-value stores, graph databases, and wide-column databases.

For example, a document database might store an article as:

{
  "title": "Learning System Architecture",
  "author": "Alice",
  "tags": [
    "software",
    "architecture"
  ],
  "published": true
}

MongoDB is an example of a document database.

Different NoSQL databases provide different capabilities, so the choice depends on the requirements.

Which should you choose?

Don't choose a database simply because a technology is trending.

Consider:

The structure of your data.
How the application will query it.
The relationships between records.
Transaction and consistency requirements.
Expected data volume.
Operational complexity.

For many beginner projects, a relational database such as PostgreSQL is a practical starting point.

You can explore other options when your application's requirements justify them.

8. How Do Components Communicate?

Components need a way to exchange information.

Two common approaches are synchronous and asynchronous communication.

Synchronous communication

In synchronous communication, a component sends a request and waits for a response before continuing with the operation.

For example, when a user opens an article, the frontend might send:

GET /api/articles/101

The backend retrieves the article and returns a response:

{
  "id": 101,
  "title": "Learning System Architecture",
  "published": true
}

This is a typical request-response interaction.

HTTP APIs are commonly used for synchronous communication.

Asynchronous communication

In asynchronous communication, a component can initiate work without waiting for the entire operation to finish.

Imagine a user uploads a large image.

The application might need to:

Save the original image.
Generate thumbnails.
Extract metadata.
Update the search index.
Send a notification.

Instead of performing every operation before responding to the user, the system can place some tasks in a queue for background processing.

A simplified workflow looks like this:

       USER UPLOADS IMAGE
                |
                v
          UPLOAD SERVICE
                |
                v
           MESSAGE QUEUE
                |
                v
         BACKGROUND WORKER
                |
         +------+------+
         |             |
         v             v
    GENERATE       EXTRACT
   THUMBNAILS      METADATA

Message queues and event brokers can support this approach.

Asynchronous processing can improve responsiveness and help separate independent tasks.

However, it also introduces additional considerations, including failed jobs, duplicate messages, retries, and delays before all components reflect the latest state.

For beginners, a useful rule is:

Use request-response communication when an immediate result is needed. Consider asynchronous processing for tasks that can safely happen in the background.

9. Security Should Be Part of the Architecture

Security is not a feature that should be added only after an application is complete.

It should influence architectural decisions from the beginning.

Consider a blogging platform where users can edit their articles.

When a user attempts to update an article, the system needs to answer two separate questions.

**Authentication: **Who is making the request?

Authorization: Is that user allowed to perform this operation?

These are different responsibilities.

A user might be successfully authenticated but still lack permission to edit another person's article.

The backend should verify the user's permissions before performing the update.

Other important security considerations include:

Validating incoming data.
Protecting sensitive information.
Using secure communication.
Storing credentials safely.
Applying the principle of least privilege.
Restricting access to private files.
Avoiding the exposure of secrets in source code.

For example, a database password should not be hardcoded into a publicly accessible frontend application.

Sensitive configuration should be managed through appropriate server-side configuration and secret-management practices.

A useful principle is to assume that requests can be manipulated and enforce security controls at the appropriate system boundaries.

10. What Happens When Something Fails?

One of the most important lessons in system architecture is that components can fail.

A database can become unavailable. An external API can time out. A network connection can drop. A background task can crash.

A reliable system needs a strategy for handling these situations.

Consider our blogging platform.

A user submits an article, but the database becomes temporarily unavailable.

What should happen?

A poorly designed system might crash or leave the user uncertain about whether the article was saved.

A better design could:

Detect the database error.
Log enough information to investigate the problem.
Return an appropriate error response.
Avoid claiming that the article was successfully published.
Allow a safe retry when appropriate.

Retries require care.

For example, retrying a request to retrieve an article is generally straightforward.

Retrying a payment or another operation that creates side effects can be more complicated. If the original request succeeded but its response was lost, retrying it blindly could perform the operation twice.

This is why concepts such as** timeouts, bounded retries,** and **idempotency **matter.

An idempotent operation can be repeated without changing the final result beyond what the first successful execution established.

Planning for failures helps make software more predictable and resilient.

11. A Practical Example: Designing a Simple Task Management Application

Let's bring everything together by designing a small task management application.

The application allows users to:

Register and sign in.
Create tasks.
Update task status.
Delete tasks.
View their personal task lists.

We don't need microservices, a complex event-driven infrastructure, or multiple databases to build this application.

A simple layered monolith would be a reasonable starting point.

Step 1: Identify the components

We can begin with four major components:

Frontend: Provides the interface for managing tasks.

Backend API: Receives requests and coordinates application operations.

**Database: **Stores user accounts and tasks.

Authentication mechanism: Establishes user identity and supports access control.

Authentication can be implemented within the backend or delegated to an appropriate identity provider.

Step 2: Define the architecture

        WEB FRONTEND
              |
              | HTTPS Requests
              v
        BACKEND API
              |
       +------+------+
       |             |
       v             v
  AUTHENTICATION   TASK SERVICE
                       |
                       v
                 DATA ACCESS
                       |
                       v
                  POSTGRESQL

This is a conceptual diagram. Authentication and task management may share the same backend deployment while remaining logically separate responsibilities.

Step 3: Define the data

A simple database schema might include two tables.

Users

id
email
password_hash
created_at

Tasks

id
user_id
title
description
status
created_at
updated_at

The user_idfield connects each task to its owner.

The system should enforce ownership when retrieving, updating, or deleting tasks.

For example, a user should not be able to change another user's task simply by guessing its ID.

Passwords should be stored using an appropriate password-hashing algorithm, not as plaintext.

Step 4: Define the request flow

Suppose a user creates a task.

The process could look like this:

The user enters the task details in the frontend.
The frontend sends an authenticated request to the backend.
The backend verifies the user's identity.
The task service validates the request.
The data access layer stores the task in the database.
The backend returns the created task.
The frontend displays the new task.

Each component has a clear responsibility.

Step 5: Consider future growth

As the application grows, we might need:

Pagination for large task lists.
Database indexes to improve query performance.
Caching for frequently accessed data.
Background jobs for scheduled reminders.
Monitoring to identify errors and slow requests.
Additional backend instances to handle increased traffic.

Notice that we don't need to implement all these features immediately.

We can introduce them as requirements emerge.

This is a practical example of incremental architectural evolution: begin with a reasonable foundation and improve it when there is a clear need.

12. Common Architecture Mistakes Beginners Should Avoid

Understanding architectural principles is useful, but knowing what to avoid is equally important.

Mistake 1: Choosing technologies before understanding the problem

It's tempting to begin by asking whether an application should use React, MongoDB, microservices, or a particular cloud platform.

But these questions are difficult to answer without understanding the requirements.

Start by identifying what the application must do and what constraints it must satisfy.

Then select technologies that support those needs.

Mistake 2: Making everything dependent on everything else

When components depend heavily on each other's internal details, small changes can have unexpected consequences.

Use clear responsibilities and interfaces to reduce unnecessary coupling.

Mistake 3: Overengineering a small project

A beginner application does not need the same infrastructure as a large distributed platform.

Every additional component introduces implementation, maintenance, and operational costs.

Choose complexity deliberately.

Mistake 4: Ignoring security

Never assume that hiding a button in the frontend is sufficient to protect an operation.

Enforce authorization on the backend and validate untrusted input.

Mistake 5: Ignoring failure scenarios

Don't assume that databases, networks, and external services will always be available.

Think about how your application should respond when a dependency fails.

Mistake 6: Treating architecture as something you design only once

Requirements change, workloads grow, and teams learn more about the problem over time.

Review architectural decisions when the circumstances that justified them change.

Architecture should evolve with the application.

13. How to Start Learning System Architecture

If you're new to software architecture, you don't need to study every advanced concept at once.

A practical learning path is more effective.

First, understand how web applications work.

Learn how browsers, HTTP requests, backend servers, APIs, and databases interact.

Second, build a complete application.

Create a project that includes a frontend, backend, authentication, and persistent storage.

A task manager, blogging platform, or expense tracker is a good starting point.

Third, organize your code.

Learn separation of concerns, modular design, layered architecture, and the principles of maintainable code.

Fourth, learn database fundamentals.

Understand tables, relationships, indexes, transactions, and database constraints.

Fifth, study reliability and security.

Explore error handling, authentication, authorization, logging, testing, and backup strategies.

Sixth, learn how systems grow.

Once you understand a simple application, explore caching, background jobs, load balancing, and horizontal scaling.

Finally, explore distributed architectures.

Learn about microservices, message queues, event-driven systems, and distributed data consistency when you're ready to understand the additional challenges they introduce.

The best way to learn architecture is to combine theory with practical experience.

Build something, identify its limitations, and improve its design.

Conclusion

System architecture is about understanding how the pieces of a software system fit together.

It helps developers make informed decisions about component responsibilities, communication, data storage, security, reliability, and future growth.

You don't need an elaborate architecture to build good software. A small application with clear boundaries and well-defined responsibilities can be easier to maintain than a complex system built around unnecessary abstractions.

As you gain experience, you'll learn that architectural decisions involve trade-offs. Improving scalability might increase operational complexity. Introducing microservices might enable independent deployments while making debugging more difficult.

The goal is not to eliminate every trade-off. It's to understand them and choose an approach that fits the problem.

If you're just starting out, focus on mastering the fundamentals:

Understand how application components communicate.
Separate responsibilities appropriately.
Choose technologies based on requirements.
Design for security and failure.
Keep your architecture as simple as practical.
Improve the system as your understanding grows.

You don't become a better architect by designing the most complicated system. You become a better architect by understanding the problem, making deliberate decisions, and knowing why those decisions make sense.

Let's Discuss

I'd love to hear from other developers, especially those who are just starting their software engineering journey.

When building a new application, do you design the architecture before writing code, or do you start building and refine the architecture as the project grows?

Share your approach in the comments.

A Practical Guide to API Types: REST, GraphQL, gRPC, SOAP, and WebSocket.

Margaret Apiyo — Fri, 17 Jul 2026 18:33:37 +0000

A Practical Guide to API Types and When to Actually Use Each One

Every job posting says "experience with APIs," but that phrase covers a lot of ground. REST, GraphQL, gRPC, SOAP, WebSocket, they're all "APIs," yet they solve different problems and make different trade-offs. I've shipped code against all five, and picking the wrong one for a project is the kind of mistake you don't feel until six months later when you're stuck maintaining it.

This post covers what an API actually is, then breaks down the major styles you'll run into on the job and how each one works, what a request/response actually looks like, and when you'd reach for it over the others.

What Is an API

An API (Application Programming Interface) is a interface that allows one piece of software to communicate to another without either side needing to know how the other one is implemented internally. You send a request in an conventional format, you get a response back in an conventional format, done.

The differences between API styles come down to a handful of design decisions:

What does a request/response actually look like on the wire?
Is communication one-shot (request → response) or ongoing (a persistent connection)?
How strict is the interface between client and server?
How is data structured,documents,remote procedure calls, or something else?

Let's go through the major styles.

1. REST (Representational State Transfer)

REST is quite common API that most people interact with either knowingly or unknowingly. It's not a protocol like HTTP or TCP,it's an architectural style, a set of conventions for using HTTP the way it was originally intended.

How it works:

Everything is a resource, addressed by a URL (/users/42, /orders/107/items)
You interact with resources using standard HTTP methods: GET (read), POST (create), PUT/PATCH (update), DELETE (remove)
Responses are usually JSON (though XML is technically fine too)
REST is meant to be stateless ,each request carries everything the server needs; the server doesn't remember previous requests

Example:

GET /api/users/42 HTTP/1.1
Host: example.com

Response:
{
  "id": 42,
  "name": "Apiyo Okafor",
  "email": "apiyo@example.com"
}

Creating a resource looks similar, just with a different verb and a body:

POST /api/users HTTP/1.1
Host: example.com
Content-Type: application/json

{
  "name": "Apiyo Okafor",
  "email": "apiyo@example.com"
}

Strengths:

Simple, widely understood, huge tooling ecosystem
Plays nicely with HTTP caching, load balancers, and CDNs
Easy to debug with just a browser or curl

Weaknesses:

Over-fetching / under-fetching: GET /users/42 might return fields you don't need, and you might need three more requests to get related data
No built-in strict schema,contracts often live only in documentation (or Swagger/OpenAPI specs)
Versioning (/v1/, /v2/) can get messy over time

Best for: public APIs, CRUD-heavy applications, anything where cacheability and simplicity matter more than flexibility.

2. GraphQL

GraphQL came out of Facebook, built specifically to fix REST's over-fetching and under-fetching problem. Instead of many fixed endpoints, you get a single endpoint, and the client describes exactly the shape of data it wants back.

How it works:

One endpoint, typically POST /graphql
The client sends a query describing the fields it needs, and the server returns exactly that, no more, no less
A strongly typed schema defines every possible query, mutation, and type up front

Example:

query {
  user(id: 42) {
    name
    orders(last: 3) {
      total
      date
    }
  }
}

This single request replaces what might be two or three REST calls, and it returns only the fields listed. Writes work through mutations, which look similar:

mutation {
  updateUser(id: 42, input: { name: "Apiyo N. Okafor" }) {
    id
    name
  }
}

Strengths:

Client controls exactly what data comes back,no over-fetching
One request can pull nested/related data in one round trip
Strong typing means better tooling (autocomplete, validation, introspection)

Weaknesses:

Caching is harder since there's no URL-per-resource for HTTP caches to key off
More complex to set up on the server (resolvers, schema design, query cost limits)
A single expensive/deeply nested query can strain the server if not guarded against

Best for: applications with complex, nested, or highly variable data needs, think mobile apps pulling data from many related sources, or frontends built by teams who don't want to wait on backend changes for every new field.

3. gRPC (Google Remote Procedure Call)

gRPC works differently from both. Instead of resources (REST) or queries (GraphQL), you're calling a function on another machine, and it feels almost like calling a local function.

How it works:

Built on HTTP/2, using Protocol Buffers (protobuf),a compact binary format instead of JSON
You define a .proto file describing services and message types, and gRPC generates client/server code in your language of choice
Supports streaming: client-streaming, server-streaming, and full bidirectional streaming, not just request/response

Example (.proto definition):

service UserService {
  rpc GetUser (UserRequest) returns (UserResponse);
}

message UserRequest {
  int32 id = 1;
}

Once you generate code from that .proto file, calling it from Python looks like a normal function call:

response = user_service_stub.GetUser(UserRequest(id=42))
print(response.name)

No manual JSON parsing, no guessing field names,the client is generated straight from the contract.

Strengths:

Very fast and bandwidth-efficient (binary format, HTTP/2 multiplexing)
Native streaming support,great for real-time or high-throughput data
Strict, generated contracts reduce integration bugs between services

Weaknesses:

Not human-readable on the wire and it is harder to debug without tooling
Poor browser support natively (needs gRPC-Web + a proxy)
Steeper learning curve, less friendly for public-facing APIs

Best for: internal microservice-to-microservice communication where speed and strict contracts matter more than human readability.

4. SOAP (Simple Object Access Protocol)

SOAP is the oldest style on this list, and you won't see it much in modern startups — but it's still running plenty of banking, insurance, and government systems, so it's worth knowing.

How it works:

Messages are strictly formatted XML, wrapped in an "envelope"
Comes with a rigid contract called WSDL (Web Services Description Language) that precisely defines every operation, input, and output
Includes built-in standards for security (WS-Security), transactions, and reliable messaging

Example:

<soap:Envelope>
  <soap:Body>
    <GetUser>
      <UserId>42</UserId>
    </GetUser>
  </soap:Body>
</soap:Envelope>

Strengths:

Extremely strict, well-defined contracts — great for formal enterprise integrations
Built-in support for security and transactional guarantees that heavily regulated industries need
Protocol-agnostic (can technically run over more than just HTTP)

Weaknesses:

Verbose XML payloads — slower and heavier than JSON or binary alternatives
Rigid and ceremonial; slower to develop against than REST or GraphQL
Considered legacy by most modern web/mobile developers

Best for: enterprise systems, financial services, healthcare, and other domains where formal contracts, security standards, and reliability guarantees are non-negotiable.

5. WebSocket

Everything above is request-then-response. WebSocket breaks that pattern — it opens a persistent, two-way connection between client and server, and either side can send a message whenever it wants, without waiting to be asked.

How it works:

Starts as an HTTP request that "upgrades" to a WebSocket connection
After the handshake, both client and server can push messages over the same open connection, with much lower overhead than repeated HTTP requests

Example (JavaScript client):

const socket = new WebSocket("wss://example.com/chat");

socket.onmessage = (event) => {
  console.log("New message:", event.data);
};

socket.send("Hello, server!");

Strengths:

True real-time, bidirectional communication
Low overhead once the connection is open,no repeated HTTP headers per message
Ideal for anything that needs to "push" data without the client asking

Weaknesses:

Not resource-oriented — doesn't fit naturally with typical CRUD operations
Harder to scale/load-balance (connections are stateful and long-lived)
Overkill for anything that isn't genuinely real-time

Best for: chat apps, live dashboards, multiplayer games, collaborative editing tools, stock tickers, anywhere the server needs to talk first.

Quick Comparison

Style	Data Format	Communication	Best For
REST	JSON/XML	Request/response	General-purpose, public APIs
GraphQL	JSON	Request/response (flexible shape)	Complex, nested, client-driven data needs
gRPC	Protobuf (binary)	Request/response + streaming	Internal microservices, high performance
SOAP	XML	Request/response	Enterprise, regulated industries
WebSocket	Any (often JSON)	Persistent, bidirectional	Real-time, push-based apps

How to Choose

A few rules of thumb that tend to hold up in practice:

Building a public API for third parties? Start with REST. It's the lowest common denominator everyone understands.
Frontend team constantly needs new field combinations and you're tired of versioning endpoints? GraphQL earns its complexity.
Talking service-to-service inside your own infrastructure, and performance matters? gRPC.
Integrating with a bank, hospital system, or government agency? You'll probably be handed a WSDL file and told to use SOAP and that's fine, it's built for that world.
Need the server to push updates the moment something happens? WebSocket (or a managed alternative like Server-Sent Events for one-directional push).

None of these is objectively "better." They're solving for different constraints, and picking one is really about matching the constraint you actually have,public consumers, internal services, complex nested data, regulatory requirements, or real-time updates.

Wrapping up

You'll end up using more than one of these in a typical career, sometimes in the same project,REST for a public-facing API, gRPC between internal services, WebSocket for the live notification feed. Knowing why each one exists, not just the syntax, is what makes it easy to pick the right one instead of defaulting to whatever you used last time.

What do you reach for most often, and why? Curious to hear what other people are running in production.

Go Web Frameworks: Why I Chose Gin Over Fiber for a Real-Time Geo-App

Margaret Apiyo — Mon, 06 Jul 2026 12:38:13 +0000

If you spend five minutes browsing the Go ecosystem for a web framework, you will inevitably run into the classic showdown: Gin vs. Fiber.If you look purely at tech benchmarks, Fiber looks like the undisputed king. It boasts mind-boggling numbers of requests-per-second and near-zero memory allocations. It looks like a no-brainer, right?Well, I am currently architecting a real-time security alert mobile app based in Kenya. The app tracks user GPS locations and triggers physical hardware vibrations when they approach crime hotspots or road accident black spots.When dealing with real-world mobile networks, geospatial data, and background processing, I quickly realized that raw framework benchmarks are a lie.Here is a deep dive into why I chose Gin, the engineering trade-offs of both frameworks, and why Fiber's speed comes with a hidden cost. The Contenders under the HoodTo understand why they perform differently, we have to look at their foundational engines.

Gin: The Battle-Tested Veteran

Gin has been a staple of the Go community since 2014. It is built directly on top of Go's native standard library (net/http) but uses an incredibly fast Radix Tree-based router (httprouter).Philosophy: Stay close to idiomatic Go, maintain maximum compatibility, and remain completely predictable.

Fiber: The Speed Demon

Fiber is a newer framework heavily inspired by Node.js’s Express.js. To achieve its speed, it makes a radical architectural choice: it completely ditches Go’s standard library. Instead, it runs on top of fasthttp, an engine written from scratch for hyper-performance.Philosophy: Minimize memory allocations at all costs and give JavaScript developers a familiar syntax.

The Hidden Trap: Why Fiber is Fast (and Dangerous)

Fiber’s incredible benchmark speeds come from a feature called Request/Response Pooling.Instead of allocating fresh memory for every incoming network request, Fiber grabs a block of memory from a recycled pool, overwrites it with the new request data, uses it, and flushes it for the next request.This works beautifully for basic synchronous APIs. But in Go, we love asynchronous concurrency using goroutines. Look at this common design pattern:

go
app.Post("/api/v1/location", func(c *fiber.Ctx) error {
    req := new(LocationRequest)
    c.BodyParser(req)

    // Spin up a background routine to log location to a database
    go func() {
        // CRASH/BUG: By the time this runs, Fiber has already recycled 
        // the memory pool. 'req' now contains data from a completely different user!
        db.Save(req.Latitude, req.Longitude) 
    }()

    return c.SendStatus(200)
})

If you pass a request pointer into a background thread in Fiber, the data can be silently overwritten by another user's request a millisecond later. This leads to silent, terrifying data corruption that is a nightmare to debug.To fix this in Fiber, you have to write verbose code to explicitly "deep copy" every variable out of the context. In Gin, because it allocates clean memory per request natively, this background routine is completely safe out of the box.Real-World Constraints:

Why Gin Won My Geo-Project

For my security alert application, three practical factors completely outweighed Fiber's benchmark speeds:

Seamless Geospatial Ecosystem To index coordinates of dangerous zones like Waiyaki Way or the Kasarani-GSU stretch, I need to hook my Go backend into massive geospatial libraries like Google's S2 or Uber's H3 spatial indexers. Because Gin uses the standard net/http stack, every major database driver (PostGIS, Redis Geo) and spatial tool integrates with zero friction. Fiber often requires messy wrappers or custom adapters.
Native HTTP/2 Support for Moving Devices
When a user is moving fast on a highway or riding a Matatu, their mobile data connection constantly jumps between cellular towers, fluctuating between 3G, 4G, and 5G.Gin supports HTTP/2 natively. This allows multiplexing, keeping a stable single connection open even through network drops.Fiber (fasthttp) does not natively support HTTP/2. To get it to work for a mobile app, you are forced to deploy and configure a reverse proxy like Nginx or Envoy in front of it just to translate the traffic.
Binary Payloads (Protobuf/gRPC)
To save my users' expensive mobile data bundles, I don't want to transmit heavy, wordy JSON payloads over the network. I want to compress spatial coordinates into tiny, lightweight binary files using Protocol Buffers. Gin provides native, one-line support for rendering binary protobuf formats (c.ProtoBuf()).

The Ultimate Decision Matrix

So, when should you actually use what?

Choose Gin If...	Choose Fiber If...
Your team writes standard, idiomatic Go.	Your team comes from a heavy Node.js/Express.js background.
You rely heavily on asynchronous background goroutines.	Your routes are strictly synchronous (Fetch -> Save -> Respond).
You need native HTTP/2, HTTP/3, or Protobuf support.	You are building an IoT sensor ping server or an Ad-Tech bidder.
Enterprise data safety and stability are your top priorities.	You need to squeeze every ounce of raw requests-per-second speed.

Final Thoughts

In 95% of real-world web applications, the framework engine is never the bottleneck. Your database query execution times, network latencies, and file operations take up 99% of your application's timeline.While Fiber is an incredible feat of engineering for ultra-high-throughput, synchronous micro-services, Gin remains the pragmatic, safe, and stable choice for complex production systems where data integrity cannot be compromised.

What framework are you using for your current Go stack? Have you ever run into memory pooling bugs in production? Let's discuss in the comments!

Maps vs Structs in Go: Making the Right Choice for Your Data

Margaret Apiyo — Thu, 25 Jun 2026 08:28:29 +0000

__
Choosing between maps and structs is one of the most common dilemmas Go developers face. This guide will help you make the right decision with confidence.

Introduction

Go's simplicity is one of its greatest strengths, but that simplicity sometimes presents developers with interesting choices. One such choice arises when you need to organize and work with structured data: should you use a map or a struct?

While both serve as containers for data, they have fundamentally different characteristics that make each better suited for specific scenarios. Understanding these differences is crucial for writing efficient, maintainable Go code.

In this article, we'll explore the technical differences, performance characteristics, and practical use cases for both data structures, helping you make informed decisions in your projects.

Understanding the Basics

What are Structs?

Structs are typed collections of fields. It groups multiple related variables (fields) of different data types together under a single name to organize data efficiently. They're compile-time constructs that define a fixed schema for your data. Each field has a name, a type, and can have tags for metadata like JSON serialization.

go
type User struct {
    ID        int       `json:"id"`
    Name      string    `json:"name"`
    Email     string    `json:"email"`
    CreatedAt time.Time `json:"created_at"`
}

When you create a struct instance, the memory layout is fixed and known at compile time. This predictability is a key feature that enables excellent performance and type safety.

What are Maps?

Maps are dynamic key-value stores where all keys and values must be of the same type (or satisfy an interface). They're runtime constructs whose structure can change as your program executes.

go
user := map[string]interface{}{
    "id":        123,
    "name":      "Alice",
    "email":     "alice@example.com",
    "createdAt": time.Now(),
}

Performance Comparison

Memory Allocation

Structs allocate memory contiguously in a single block:

go
type Point struct {
    X, Y, Z float64
}

// Single allocation: 24 bytes (3 * 8 bytes)
p := Point{X: 1.0, Y: 2.0, Z: 3.0}

Maps require multiple allocations:

go
// Multiple allocations: map header, buckets, keys, values
data := map[string]float64{
    "x": 1.0,
    "y": 2.0,
    "z": 3.0,
}

Access Speed

go
func BenchmarkStructAccess(b *testing.B) {
    user := User{ID: 1, Name: "John"}
    for i := 0; i < b.N; i++ {
        _ = user.Name
    }
}

func BenchmarkMapAccess(b *testing.B) {
    user := map[string]interface{}{"name": "John"}
    for i := 0; i < b.N; i++ {
        _ = user["name"]
    }
}

Results:

text
BenchmarkStructAccess-8    1000000000    0.28 ns/op    0 B/op    0 allocs/op
BenchmarkMapAccess-8       100000000    11.5 ns/op    0 B/op    0 allocs/op
Struct access is ~40x faster than map access!

Type Safety: The Compile-Time Guardian

Structs Catch Errors Early
With structs, the compiler catches mistakes before they reach production:

go
type Product struct {
    Name  string
    Price float64
}

func UpdatePrice(p *Product, newPrice float64) {
    p.Price = newPrice
}

// Compilation errors:
p := Product{Name: "Laptop", Price: 999.99}
p.Price = "invalid" // cannot use string as float64
p.Stock = 50 // unknown field

Maps Require Runtime Checks
Maps sacrifice type safety for flexibility:

go
data := map[string]interface{}{"price": 99.99}

// Runtime type assertion required
price, ok := data["price"].(float64)
if !ok {
    return errors.New("invalid price type")
}

// This compiles but panics at runtime
price := data["price"].(int) // panic: interface conversion

When to Use Structs

Domain Models Structs excel at representing real-world entities:

go
type Order struct {
    ID          int64     `json:"id"`
    CustomerID  int64     `json:"customer_id"`
    Total       float64   `json:"total"`
    Status      string    `json:"status"`
    CreatedAt   time.Time `json:"created_at"`
}

func (o *Order) Validate() error {
    if o.Total <= 0 {
        return errors.New("order total must be positive")
    }
    return nil
}

API Contracts Structs with JSON tags provide clean serialization:

go
type CreateUserRequest struct {
    Name     string `json:"name" validate:"required"`
    Email    string `json:"email" validate:"required,email"`
    Password string `json:"password" validate:"required,min=8"`
}

Configuration Management Configuration is typically well-defined:

go
type Config struct {
    Host     string        `yaml:"host"`
    Port     int           `yaml:"port"`
    Timeout  time.Duration `yaml:"timeout"`
    Database DatabaseConfig `yaml:"database"`
}

Database Models Structs work perfectly with ORMs:

go
type User struct {
    ID        int64     `db:"id"`
    Username  string    `db:"username"`
    Email     string    `db:"email"`
    CreatedAt time.Time `db:"created_at"`
}

When You Need Methods

go
type Calculator struct {
    Precision int
}

func (c *Calculator) Add(a, b float64) float64 {
    return math.Round((a+b)*float64(c.Precision)) / float64(c.Precision)
}

When to Use Maps

Dynamic Data When the data structure is unknown at compile time:

go
func ProcessWebhook(payload map[string]interface{}) error {
    eventType, ok := payload["type"].(string)
    if !ok {
        return errors.New("missing event type")
    }

    switch eventType {
    case "user.created":
        return processUserCreated(payload)
    case "order.completed":
        return processOrderCompleted(payload)
    default:
        return fmt.Errorf("unknown event type: %s", eventType)
    }
}

Dynamic Keys When keys come from external sources:

go
func BuildQueryParams(params map[string]string) string {
    var queryParts []string
    for key, value := range params {
        queryParts = append(queryParts, fmt.Sprintf("%s=%s", key, value))
    }
    return strings.Join(queryParts, "&")
}

HTTP Headers HTTP headers are inherently dynamic:

go
func SetHeaders(headers map[string]string) {
    for key, value := range headers {
        w.Header().Set(key, value)
    }
}

Caching Maps are excellent for simple caches:

go
type Cache struct {
    store map[string]interface{}
    mu    sync.RWMutex
}

func (c *Cache) Get(key string) (interface{}, bool) {
    c.mu.RLock()
    defer c.mu.RUnlock()
    value, ok := c.store[key]
    return value, ok
}

Counting or Set Operations

go
// Using map as a set
activeUsers := make(map[string]bool)
activeUsers["alice@example.com"] = true

// Counting occurrences
wordCount := make(map[string]int)
for _, word := range words {
    wordCount[word]++
}

The Hybrid Approach

You don't have to choose just one. Combine both where appropriate:

go
type User struct {
    ID         int
    Name       string
    Attributes map[string]interface{} // Dynamic attributes
}

func (u *User) GetAttribute(key string) interface{} {
    return u.Attributes[key]
}

This gives you the best of both worlds: fixed fields for core data and dynamic fields for extensibility.

Decision Framework

Use this flowchart to guide your decision:

text
Is the data structure fixed at compile time?
│
├── Yes ──> Does performance matter?
│ │
│ ├── Yes ──> Use STRUCT
│ │
│ └── No ───> Use STRUCT (still better!)
│
└── No ────> Are keys dynamic or from user input?
│
├── Yes ──> Use MAP
│
└── No ───> Consider STRUCT or MAP based on other needs

Quick Decision Rules

Use Structs When:

You know the data shape at compile time
Performance is critical
Type safety is important
You need methods or interfaces
The data represents a business entity
You want self-documenting code
You're working with JSON/XML serialization

Use Maps When:

The data structure is truly dynamic
Keys come from user input or external sources
You need to iterate over all fields generically
You're working with HTTP headers or query params
You need a set or counting structure
You're caching arbitrary data

Common Pitfalls to Avoid

Using Maps for Everything

go
// Hard to maintain and error-prone
func ProcessUser(data map[string]interface{}) {
    name, _ := data["name"].(string) // Potential panic
    age, _ := data["age"].(int)      // Might be float64 from JSON
}

Using Structs for Highly Dynamic Data

go
// Adding fields requires code changes
type DynamicData struct {
    Field1 string
    Field2 string
    // Field3 needed? Must modify struct
}

Mixing Types Without Clear Semantics

go
// Avoid this pattern
data := map[string]interface{}{
    "id": 123,
    "name": "Alice",
    "tags": []string{"admin", "user"},
    "settings": map[string]interface{}{
        "notifications": true,
    },
}

Best Practices

Default to Structs
In 80% of cases, structs are the better choice. Start with structs and only switch to maps when you have a specific reason.
Use Typed Maps When Possible

go
// Better than map[string]interface{}
type Attributes map[string]string

Validate Map Data Early

go
func validateUser(data map[string]interface{}) error {
    required := []string{"name", "email"}
    for _, field := range required {
        if _, ok := data[field]; !ok {
            return fmt.Errorf("missing required field: %s", field)
        }
    }
    return nil
}

Document Map Expectations

go
// UserData must contain:
// - "name": string (required)
// - "email": string (required)
// - "age": int (optional)
func ProcessUserData(data map[string]interface{}) error {
    // Implementation...
}

Consider Conversions It's easier to convert a struct to a map than the reverse:

go
// Convert struct to map
func ToMap(v interface{}) map[string]interface{} {
    result := make(map[string]interface{})
    data, _ := json.Marshal(v)
    json.Unmarshal(data, &result)
    return result
}

Conclusion

Choosing between maps and structs in Go comes down to understanding your data's nature and your application's requirements.

Structs are the default choice for most applications. They provide:

Compile-time type safety
Superior performance (40x faster access)
Self-documenting code
Better memory efficiency
Method support
Interface implementation

Maps shine in specific scenarios:

Dynamic data structures
Unknown or user-defined schemas
Generic iteration over fields
HTTP headers and query parameters
Caching and counting operations

Remember: You can always refactor from structs to maps if needed, but the reverse is much harder and more error-prone.

What's your experience with maps vs structs in Go? Share your thoughts in the comments below!

Enjoyed this article? Follow me for more Go insights and best practices.

Why Port 8080 and Not 80? A Beginner’s Tale in Go

Margaret Apiyo — Fri, 15 May 2026 07:40:58 +0000

****I

recently started my coding journey with Go. If you’re a beginner looking for a language that is simple yet incredibly powerful, I can’t recommend Go enough.

While building my first Go HTTP web server, I hit a point of curiosity. I learned that a server must "listen" on a specific port number, but I kept seeing 8080 in every tutorial instead of the standard 80.

I did some digging, and here is what I found.

What exactly is a Port?

Think of an IP address as the building address and a Port as the specific door (entry point). The port number decides which software gets the request. When a server "listens" on a port, it means the software is standing behind that door, waiting for someone to knock.

The "Conflict" Rule

On your local machine, only one process can bind to a specific port at a time.
If you have Apache, Nginx, or another system service already listening on Port 80, your Go application will crash on startup. The OS will essentially tell you: "That door is already taken!" By using 8080, you avoid crashing into the main web services already running on your machine.

The "Root" Problem (Privileged Ports)

There is a second reason beginners use 8080 that is even more important: Permissions.
In Unix-like operating systems (Linux and macOS), ports numbered 1 to 1023 are considered "Privileged Ports."
Port 80 requires administrative (root) privileges to run.
Port 8080 is an unprivileged port.

Think of it like this:
Door 80: Imagine this door has a "Security Clearance Required" sign. Only the "System Admin" (Root/Sudo) has the key.
Door 8080: This is an open side entrance. Any developer (standard user) can walk through it and set up shop.

As a developer, you don't want to run your Go binary with sudo every time you test a change. Using 8080 allows you to run your code as a normal user, making your development workflow much smoother and safer.

Why the number 8080?

You might wonder: “Why not 1234 or 9999?”
Technically, you could! However, 8080 became the industry standard because it literally looks like "two 80s." It’s the universal signal to other developers saying: "This is a web server, but it's for development/alternative use."

A Quick Example in Go
In case you’re wondering how this looks in code, here is how we "listen" on 8080 in Go:

package main

import (
    "fmt"
    "net/http"
)

func main() {
    http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        fmt.Fprintf(w, "Hello! You've reached the Go server on port 8080.")
    })

    fmt.Println("Server starting on :8080...")
    // We use :8080 to avoid permission issues and port conflicts
    http.ListenAndServe(":8080", nil)
}

Summary

Port 80: The default for HTTP. Requires "Root" permissions.

Port 8080: The "Alternative" to 80. Easy to use for development without special permissions.

Understanding these small "why" questions makes the coding journey so much more rewarding. If you're just starting with Go like me, keep questioning the default`