Forem: Beryl Christine Atieno

Building a Mini Wallet Service with Paystack Integration

Beryl Christine Atieno — Mon, 15 Dec 2025 18:58:07 +0000

How I built a mini digital wallet with Paystack integration, Google OAuth, and learned the importance of webhooks along the way.

Why I Built a Wallet Service

I recently decided to tackle a project that would push my understanding of payment systems, authentication, and API design. A digital wallet service was perfect for this; Not just a simple payment processor, but a complete wallet system where users could deposit money, transfer funds to each other, and manage their balance, all secured with proper authentication and permissions.

The goal was clear; to build something production-ready that I'd feel confident deploying. That meant handling real money (well, test money initially), implementing proper security, and most importantly, integrating with a real payment gateway.

Enter Paystack.

Choosing Paystack

I chose Paystack for several reasons:

Excellent documentation - Their API docs are clean and comprehensive
Great developer experience - Paystack has a test mode works flawlessly
Webhook support - Critical for real-time payment updates
African focus - Paystack is a Nigerian company, perfect for the African market with integrations to popular African payment solutions like MPESA.

Tech Stack

Backend: Go (Golang) - for speed and simplicity
Database: SQLite (I picked this because I have no scaling worries to think about)
Payment Gateway: Paystack
Authentication: Google OAuth + JWT tokens
Architecture: Clean architecture with repository pattern

The Paystack Integration Journey

Step 1: Understanding the Flow

The first thing I learned: payment integration isn't just "call API, get money." There's a flow:

1. User clicks "Deposit KES 5,000"
2. Your server calls Paystack: "Initialize a payment"
3. Paystack returns a payment link
4. User pays on Paystack's secure page
5. Paystack sends a webhook to your server
6. Your server verifies and credits the wallet

Step 2: Setting Up Paystack Client

First, I created a Paystack client in Go. Here's what it looks like:

package paystack

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)

type Client struct {
    secretKey string
    baseURL   string
}

func NewClient(secretKey string) *Client {
    return &Client{
        secretKey: secretKey,
        baseURL:   "https://api.paystack.co",
    }
}

Simple enough. The secret key comes from your Paystack dashboard (use test keys during development).

Step 3: Initializing a Transaction

When a user wants to deposit money, I need to initialize a Paystack transaction:

type InitializeRequest struct {
    Email     string `json:"email"`
    Amount    int64  `json:"amount"` // Amount in cents (KES 10 = 1000 cents)
    Reference string `json:"reference"` // Unique transaction reference
}

func (c *Client) InitializeTransaction(email string, amount int64, reference string) (*InitializeResponse, error) {
    reqBody := InitializeRequest{
        Email:     email,
        Amount:    amount,
        Reference: reference,
    }

    jsonData, _ := json.Marshal(reqBody)

    req, _ := http.NewRequest("POST", c.baseURL+"/transaction/initialize", bytes.NewBuffer(jsonData))
    req.Header.Set("Authorization", "Bearer "+c.secretKey)
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)

    var initResp InitializeResponse
    json.Unmarshal(body, &initResp)

    return &initResp, nil
}

Key learnings here:

Amount is in cents - KES 10.50 = 1050 cents. This avoids floating-point errors. I made this mistake initially and had users "depositing" KES 10 when they meant KES 1,000!
Reference must be unique - I generate mine like this: DEP_userID_amount_timestamp. This prevents duplicate transactions.
Email is required - Paystack uses it for receipts and verification.

Step 4: Handling the Response

Paystack returns a payment link, which is the authorizationURL in the response structure below. Here's my wallet handler:

func (h *WalletHandler) InitiateDeposit(w http.ResponseWriter, r *http.Request) {
    // Get user ID from JWT or API key
    userID := h.getUserID(r)

    // Parse request
    var req DepositRequest
    json.NewDecoder(r.Body).Decode(&req)

    // Get user's wallet
    userWallet, _ := h.walletRepo.GetByUserID(userID)

    // Generate unique reference
    reference := fmt.Sprintf("DEP_%s_%d", userID, req.Amount)

    // Initialize Paystack payment
    paystackResp, err := h.paystackClient.InitializeTransaction(
        h.getUserEmail(r),
        req.Amount,
        reference,
    )

    if err != nil {
        respondError(w, "Failed to initialize payment")
        return
    }

    // Create pending transaction in database
    h.walletService.InitiateDeposit(userWallet.ID, req.Amount, reference)

    // Return payment link to user
    respondSuccess(w, map[string]interface{}{
        "reference":         paystackResp.Data.Reference,
        "authorization_url": paystackResp.Data.AuthorizationURL,
    })
}

The authorization url is used to redirect the user to Paystack's payment page. They enter their card/MPESA details (or use the test details provided by Paystack), and Paystack processes the payment.

Example response:

{
  "data": {
    "authorization_url": "https://checkout.paystack.com/09fgljcz1ierho0",
    "reference": "DEP_d892fb679690f5dc285003d161873736_5000"
  }
}

But here's where it gets interesting...

Step 5: The Webhook - The Most Important Part

Initially, I thought: "Great! User paid, I'll just check Paystack's API to see if payment succeeded."

Wrong approach. That means polling constantly, wasting resources, and delayed updates.

The right way? Webhooks.

Paystack sends a POST request to your server the moment payment succeeds. Here's how I handled it:

func (h *WebhookHandler) HandlePaystackWebhook(w http.ResponseWriter, r *http.Request) {
    // CRITICAL: Validate webhook signature
    body, valid := paystack.ValidateWebhookSignature(r, h.paystackSecret)
    if !valid {
        respondError(w, http.StatusUnauthorized, "Invalid signature")
        return
    }

    // Parse the event
    event, _ := paystack.ParseWebhookEvent(body)

    // Only process successful charges
    if event.Event == "charge.success" && event.Data.Status == "success" {
        // Credit the wallet
        h.walletService.CompleteDeposit(event.Data.Reference)
    }

    // Always return 200 OK (so Paystack knows we received it)
    respondSuccess(w, map[string]interface{}{"status": true})
}

Step 6: Webhook Signature Validation for Security

Without signature validation, anyone could send fake webhooks to credit wallets for free! The key security element here is the X-Paystack-Signature header, which includes the webhook signature used to verify that a request is coming from Paystack.

Here's how Paystack signs webhooks:

func ValidateWebhookSignature(r *http.Request, secretKey string) ([]byte, bool) {
    signature := r.Header.Get("X-Paystack-Signature")

    body, _ := io.ReadAll(r.Body)

    // Compute HMAC SHA512
    hash := hmac.New(sha512.New, []byte(secretKey))
    hash.Write(body)
    expectedSignature := hex.EncodeToString(hash.Sum(nil))

    // Compare signatures (constant-time comparison prevents timing attacks)
    return body, hmac.Equal([]byte(signature), []byte(expectedSignature))
}

Step 7: Idempotency - Handling Duplicate Webhooks

Paystack might send the same webhook twice due to network issues, retries, etc. You need to handle this gracefully. In my case, I check the webhook reference and check if it has already been processed. If yes, I do nothing making sure no single request is processed twice.

func (s *Service) CompleteDeposit(reference string) error {
    tx, _ := s.transactionRepo.GetByReference(reference)

    // Check if already processed
    if tx.Status == TransactionStatusSuccess {
        return nil // Already credited, do nothing (idempotent)
    }

    // Update transaction status
    tx.Status = TransactionStatusSuccess
    s.transactionRepo.Update(tx)

    // Credit wallet
    s.walletRepo.UpdateBalance(tx.WalletID, tx.Amount)

    return nil
}

Without this check, a user could get credited twice for the same payment!

Testing

The following is an example of a payment process, tested with curl

1. User Initiates Deposit

curl -X POST http://localhost:8080/wallet/deposit \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -d '{"amount": 5000}'

2. Server Response

{
  "data": {
    "reference": "DEP_user123_5000",
    "authorization_url": "https://checkout.paystack.com/abc123"
  }
}

3. User Pays on Paystack

Frontend redirects user to authorization_url

User enters payment details

Paystack processes payment

4. Paystack Sends Webhook

POST /wallet/paystack/webhook
X-Paystack-Signature: abc123...

{
  "event": "charge.success",
  "data": {
    "reference": "DEP_user123_5000",
    "amount": 5000,
    "status": "success"
  }
}

5. Server Credits Wallet

UPDATE wallets 
SET balance = balance + 5000 
WHERE user_id = 'user123'

6. User Checks Balance

curl http://localhost:8080/wallet/balance \
  -H "Authorization: Bearer eyJhbGciOi..."

Response: {"data": {"balance": 5000}}

Lessons Learned

1. Always Use Webhooks

Polling is tempting but wrong. Webhooks give you real-time updates and are how Paystack intends you to work.

2. Validate Everything

Webhook signatures (prevent fraud)
Amount formats (use smallest currency unit)
Transaction uniqueness (prevent duplicates)

3. Handle Idempotency

Webhooks can arrive multiple times. Your code should handle this gracefully without double-crediting.

4. Unique References Matter

Generate unique transaction references. I use: {type}_{userID}_{amount}_{timestamp}. This makes debugging easier and prevents conflicts.

7. Security Layers

I implemented multiple security layers:

Google OAuth for user authentication
JWT tokens for session management
API keys with permissions for services
Webhook signature validation
HTTPS in production

What's Next?

I'm planning to add:

Recurring payments - Using Paystack subscriptions
Payouts to bank - Using Paystack Transfer API
Split payments - For marketplace scenarios
Invoice generation - PDF receipts for deposits
Analytics dashboard - Transaction trends and insights

Final Thoughts

Building this wallet service taught me more about payment systems than any tutorial could. The moment I saw my first test webhook arrive and the balance update automatically.

Paystack made the integration smooth with great docs and test mode. The webhook system is elegant once you understand it. And seeing real (test) money flow through the system you built? That's incredibly satisfying.

If you're building anything involving payments in Africa, I highly recommend Paystack. The developer experience is top-notch, and they handle the complex parts so you can focus on your product.

The complete code is on Github. Feel free to explore, learn, and build your own!

AI Agents in Go: Exploring Agent-to-Agent (A2A) Protocols in AI Ecosystems

Beryl Christine Atieno — Mon, 03 Nov 2025 08:19:33 +0000

In multi-agent systems, effective communication is what transforms isolated algorithms into coordinated intelligence. Agent-to-Agent (A2A) protocols define the structured way autonomous agents exchange information, make requests, and respond to one another. Much like human communication relies on shared languages and rules, agents rely on these protocols to ensure that messages are understood consistently across systems. By defining message formats, interaction patterns, and behavior expectations, A2A protocols enable agents to collaborate, negotiate, and act toward shared goals without central control. This structured communication allows systems to scale, adapt, and interoperate across diverse environments; from AI marketplaces and IoT networks to digital identity frameworks.

In this post, I’ll walk you through how I built a simple customer profile generating agent. The agent uses Gemini AI to generate a target consumer profile based on a business idea. I designed the profiling logic, and wired everything together to interact seamlessly with Telex, a messaging platform, using A2A protocol.

Architecture Overview

The project is divided into three main packages:

profiler/ — Handles communication with Gemini and parses generated profiles.
a2a/ — Implements the Telex A2A (Agent-to-Agent) communication protocol and request handling.
main.go — Bootstraps the HTTP server and wires everything together.

The profiling logic

At the heart of the agent is the GeminiClient. It connects to Google’s Generative AI API (Gemini) and crafts a very specific prompt:

func (g *GeminiClient) buildPrompt(businessIdea string) string {
    return fmt.Sprintf(`You are an expert market researcher. Based ONLY on the business idea "%s", generate a SINGLE, concise customer profile.
    The output MUST be a single line in the format "key: value, key: value, ..."`, businessIdea)
}

A response might look like..

age: 25-35, gender: female, location: urban, occupation: social media manager,
income: $60k-80k, pain_points: time constraints, product overload,
motivations: sustainability, simplicity, interests: skincare, yoga, travel, channel: Instagram

The agent then splits and maps this text into a structured Go model (CustomerProfile), making it machine-readable for downstream integrations.

func (g *GeminiClient) parseSimpleProfile(text string) (*models.CustomerProfile, error) {
    profile := models.CustomerProfile{}

    // Clean up any extraneous whitespace
    text = strings.TrimSpace(text)

    // Split the entire string by ", " to get key-value pairs
    pairs := strings.Split(text, ", ")

    // A simple map to hold the extracted data
    data := make(map[string]string)

    for _, pair := range pairs {
        parts := strings.SplitN(pair, ": ", 2)
        if len(parts) == 2 {
            key := strings.ToLower(strings.TrimSpace(parts[0]))
            value := strings.TrimSpace(parts[1])
            data[key] = value
        }
    }

    // Map the simple string data to the struct fields
    profile.Age = data["age"]
    profile.Gender = data["gender"]
    profile.Location = data["location"]
    profile.Occupation = data["occupation"]
    profile.Income = data["income"]

    // Split comma-separated lists for arrays in your struct
    profile.PainPoints = strings.Split(data["pain_points"], ",")
    profile.Motivations = strings.Split(data["motivations"], ",")
    profile.Interests = strings.Split(data["interests"], ",")

    profile.PreferredChannels = []string{data["channel"]}


    return &profile, nil
}

The A2A Handler Package

The a2a package forms the backbone of agent communication in this project. It implements the A2A protocol, providing a consistent structure for how agents send, receive, and interpret messages. The design focuses on simplicity, extensibility, and reliability, allowing different agents to interact over HTTP while maintaining protocol integrity.

At its core, the package defines a message schema and a handler that processes incoming agent messages. Each message can contain multiple parts, such as text or structured data, representing different elements of an agent conversation.

Message Structure

Each A2AMessage is defined with a unique identifier and an array of message parts. This allows agents to exchange multi-modal data (e.g., text, JSON payloads) in a single structured request.

type A2AMessage struct {
    ID    string      `json:"id"`
    Parts []MessagePart `json:"parts"`
}

type MessagePart struct {
    Kind string           `json:"kind"`
    Text *string          `json:"text,omitempty"`
    Data json.RawMessage  `json:"data,omitempty"`
}

The Kind field determines how the handler interprets the part, for example, "text" parts are treated as plain messages, while "data" parts may include structured content like conversation context or business idea metadata.

Handler Design

The A2AHandler is designed to process messages from other agents, extract useful data, and generate appropriate responses. It uses dependency injection for modularity, ensuring that logic like parsing, validation, and business reasoning can be swapped or extended.

type A2AHandler struct {
    mu sync.Mutex
}

func NewA2AHandler() *A2AHandler {
    return &A2AHandler{}
}

Incoming messages are processed through a dedicated route. The handler reads each part of the message and reconstructs the complete intent behind the request.

func (h *A2AHandler) HandleMessage(c *gin.Context) {
    var msg A2AMessage
    if err := c.BindJSON(&msg); err != nil {
        c.JSON(http.StatusBadRequest, gin.H{"error": "Invalid A2A message"})
        return
    }

    businessIdea := h.extractBusinessIdea(msg)
    response := h.generateProfile(businessIdea)

    c.JSON(http.StatusOK, gin.H{"response": response})
}

Here, the extractBusinessIdea method scans through the message parts to find relevant text or data:

func (h *A2AHandler) extractBusinessIdea(msg A2AMessage) string {
    var texts []string
    for _, part := range msg.Parts {
        if part.Kind == "text" && part.Text != nil && *part.Text != "" {
            texts = append(texts, *part.Text)
        }
    }
    return strings.Join(texts, " ")
}

This modular approach allows the handler to later evolve to interpret other part types, such as "intent", "metadata", or "context", without rewriting the communication logic.

Design Rationale

The handler was built to achieve three main goals:

Protocol Consistency: All agents exchange data in a predictable message format, reducing parsing errors and ambiguity.
Extensibility: The modular structure makes it easy to add new message kinds or integrate AI reasoning layers later.
Scalability: Using lightweight HTTP endpoints via Gin allows multiple agents to communicate efficiently, even when distributed across different services or environments.

By encapsulating communication logic in the a2a package, this project achieves a clean separation between message handling, business logic, and agent behavior, a key principle in designing interoperable multi-agent systems.

Integration with Telex

The Customer Profiler Agent integrates with Telex through a declarative workflow configuration that defines how the agent is discovered, described, and executed within the Telex ecosystem. Instead of manual registration or static service discovery, Telex reads the workflow file, written in JSON, to understand the agent’s purpose, category, capabilities, and endpoint.

Telex uses this configuration to automatically connect to the agent’s A2A interface, defined at
POST /a2a/profiler. Through this endpoint, Telex sends structured Agent-to-Agent (A2A) messages containing business ideas, which the profiler analyzes to generate customer personas. The workflow ensures that requests and responses follow a standardized format, making the profiler interoperable with other Telex-based agents.

A simplified version of the workflow file looks like this:

{
  "id": "customer_profiler",
  "name": "Customer Profiler",
  "category": "business",
  "description": "AI-powered customer profiler that predicts ideal customer personas",
  "nodes": [
    {
      "id": "profiler_agent",
      "type": "a2a/generic-a2a-node",
      "url": "https://overparticular-lissette-myographic.ngrok-free.dev/a2a/profiler",
      "parameters": {
        "blocking": true,
        "timeout": 30000
      }
    }
  ]
}

When Telex runs this workflow, it discovers the agent via the provided URL and executes it as a node of type a2a/generic-a2a-node.
This node type tells Telex that the target endpoint supports the Agent-to-Agent protocol, enabling direct message exchange with automatic JSON serialization and deserialization. The "blocking": true flag ensures Telex waits for the agent’s full response before continuing workflow execution, while "timeout": 30000 defines a safe execution window (in milliseconds).

In essence, this configuration allows Telex to

Discover the agent dynamically through its exposed endpoint.
Send A2A messages describing a business idea.
Receive structured customer profiles as a response.

An example of a response in Telex logs:

2025-11-03 06:28:28 - RESPONSE
{
  "jsonrpc": "2.0",
  "id": "e148455b7ef64f5a946c29c94507eb9e",
  "result": {
    "id": "e148455b7ef64f5a946c29c94507eb9e",
    "status": {
      "state": "completed",
      "timestamp": "2025-11-03T05:28:27Z",
      "message": {
        "kind": "message",
        "role": "agent",
        "parts": [
          {
            "kind": "text",
            "text": "# Customer Profile for: a car wash business customer profile for a natural hair salon business a salon for braiding in the U.S A business for dog walking A business for dog walking\n\n**Demographics:**\n- Age: 25-55\n- Gender: female\n- Location: Suburban\n- Occupation: Professional\n- Income: $60k-120k\n\n**Pain Points:**\n- lack of time\n\n**Motivations:**\n- reliable service\n\n**Interests:**\n- fitness\n\n**Preferred Channels:**\n- Facebook\n"
          }
        ]
      }
    },
    "artifacts": [
      {
        "artifactId": "6ef2cd8f-29c2-4cde-ae19-26358ae43765",
        "name": "Customer Profile Data",
        "parts": [
          {
            "kind": "text",
            "text": "{\"profiles\":[{\"age\":\"25-55\",\"gender\":\"female\",\"location\":\"Suburban\",\"occupation\":\"Professional\",\"income\":\"$60k-120k\",\"motivations\":[\"reliable service\"],\"interests\":[\"fitness\"],\"pain_points\":[\"lack of time\"],\"buying_behaviors\":null,\"preferred_channels\":[\"Facebook\"]}]}"
          }
        ]
      }
    ],
    "kind": "task"
  }
}

Telex reads the artifacts.parts in the response to display the agent's response to the user's message.

This tight integration enables Telex to orchestrate intelligent workflows, where the Customer Profiler can collaborate with other agents such as market analyzers, product planners, or campaign optimizers, without additional infrastructure setup.

Conclusion

The implementation of the Agent-to-Agent (A2A) protocol in this project demonstrates the power of structured communication in autonomous systems. By defining a clear message schema and modular handler, agents can exchange data, interpret intent, and collaborate without human intervention or centralized control. The a2a package serves as a robust foundation for this interaction, ensuring consistency, scalability, and flexibility in message processing.

Media Generation with Go Graphics (GG Package)

Beryl Christine Atieno — Mon, 27 Oct 2025 08:49:11 +0000

A robust API does more than just serve JSON; it can be an engine for custom content. In building my RESTful country data service with Go, I integrated a unique feature: generating and serving a summary image directly from my backend. This showcases how modern Go applications can seamlessly blend data management with on-demand media creation, demonstrating a high degree of engineering versatility.

Use Case for Dynamic Graphics

The primary goal of my API's refresh endpoint ,POST /api/v1/countries/refresh, is to update cached country data. However, I added a visual status update that is guaranteed to be fresh and accurate—a summary PNG image showing the total country count, the top 5 countries by Estimated GDP, and the exact last refresh timestamp.

A static image or a client-side chart wouldn't suffice; the image needed to be universally embeddable, such as in emails or reports, and generated only when the database was successfully updated.

Drawing Graphics with Go

The process of creating the PNG image is handled entirely within the Go backend, leveraging the features of the fogleman/gg package, which provides a clean, API-like wrapper around Go's native graphics capabilities, simplifying the creation of complex visuals.

1. The Canvas and Drawing Context Set-up

The process begins by fetching the necessary data from the database and initializing the graphics context.

// Fetch Top 5 Countries by Estimated GDP
var topCountries []models.Country
result := db.Order("estimated_gdp DESC").Limit(5).Find(&topCountries)

// Setup Drawing Context
dc := gg.NewContext(ImageWidth, ImageHeight)

The gg.NewContext(ImageWidth, ImageHeight) line creates the drawing canvas, and a targeted GORM query (Order("estimated_gdp DESC").Limit(5)) efficiently retrieves only the data needed for the leader board, keeping the process fast.

2. Canvas Construction and Styling

After initializing, the context is styled using straightforward method calls:

// Set background color (light gray)
dc.SetColor(color.RGBA{R: 240, G: 240, B: 240, A: 255})
dc.Clear()

// Add a title bar (dark blue)
dc.SetColor(color.RGBA{R: 50, G: 70, B: 100, A: 255})
dc.DrawRectangle(0, 0, ImageWidth, 50)
dc.Fill()

The power of gg is evident here: methods like DrawRectangle, SetColor, and Fill abstract away the complexities of low-level pixel manipulation.

3. Font Loading and Text Rendering

Handling custom fonts is crucial for professional visuals. gg simplifies loading a font file and setting properties:

// Load Font and Set Text Properties
if err := dc.LoadFontFace(FontPath, 20); err != nil {
    // ... (Handle fallback)
}

// Draw Header Text (centered by default)
dc.SetColor(color.White)
dc.DrawString("Country Data API Summary", ImageWidth/2, 30)
dc.Fill()

By calling dc.DrawString, we render dynamic information directly, including the total country count and the formatted refresh timestamp. A key part of the logic is the loop that iterates through the topCountries slice to draw the leader board:

// Draw Top 5 List
for i, country := range topCountries {
    // ... (Safety check for nil pointers)

    line := fmt.Sprintf("%d. %s - GDP: $%s (%s)", i+1, country.Name, gdpStr, currency)
    dc.DrawString(line, 40, y)
    y += 20
}

This loop dynamically adjusts the y coordinate to ensure clean vertical spacing for the ranked list. Note the essential safety check for nil pointers on fields like EstimatedGDP and CurrencyCode, ensuring the image generation doesn't panic even if the data is incomplete.

4. File Persistence and Error Handling

The final output is saved to the designated path, including a check to ensure the directory structure exists:

// Ensure the 'cache' directory exists
if err := os.MkdirAll(filepath.Dir(ImagePath), 0755); err != nil {
    return fmt.Errorf("failed to create cache directory: %w", err)
}

// Save the final PNG file
if err := dc.SavePNG(ImagePath); err != nil {
    return fmt.Errorf("failed to save summary image: %w", err)
}

The use of os.MkdirAll ensures the necessary cache/ directory is present before attempting the final save, preventing a common I/O error and making the deployment more robust. The dc.SavePNG function then handles the entire PNG encoding and writing process.

Conclusion

To conclude, integrating on-demand media generation with data service functionality, elevates a standard REST API into a more versatile engineering solution. By coupling the image creation process to a successful database transaction and leveraging the fogleman/gg package, we ensure the visual asset is always current and consistent with the cached data.

Go Channels Explained Like You’re Five

Beryl Christine Atieno — Sat, 09 Aug 2025 08:41:38 +0000

When I first started working with Go’s concurrency model, channels seemed mysterious. I knew they were a way for goroutines to talk to each other, but the finer points of how they communicate and when to close them were still fuzzy. After experimenting with a simple example, I now have a much clearer mental model.

1. Channels Are Pipelines for Communication

A channel in Go is like a conveyor belt between goroutines.

A sender puts values onto the belt.
A receiver takes values off the belt.

You can think of it as:

ch := make(chan int) // a channel for int values

Now ch is ready to carry int data from one goroutine to another.

2. Sender Channels vs Receiver Channels

In Go, you can explicitly mark a function’s parameter as a send-only or receive-only channel:

chan<- int → send-only channel
<-chan int → receive-only channel

This makes the intent clear and prevents accidental misuse.
Example:

func producer(ch chan<- int) {
    ch <- 42 // send only
}

3. Data Channels vs Signaling Channels

I’ve come to see two main roles for channels:

Data Channels : carry actual information (numbers, strings, structs, etc.) between goroutines.
Signaling Channels : used only to say “I’m done” or “you can proceed,” often carrying struct{} (an empty struct) to avoid extra memory cost.

Example of a signaling channel:

done := make(chan struct{})

go func() {
    // do some work
    done <- struct{}{}
}()

<-done // wait for signal

4. Why Closing a Channel Matters

If the receiver is in a loop, it needs to know when there’s nothing more to read. Closing a channel is the sender’s way of saying:

"I’m done sending. Don’t wait for more."

For example:

ch := make(chan int)

go func() {
    for i := 0; i < 5; i++ {
        ch <- i
    }
    close(ch) // tell receiver no more data
}()

for v := range ch {
    fmt.Println(v)
}

Without close(ch), the range loop would wait forever.

5. The Rule of Responsibility

The sender is responsible for closing the channel ; never the receiver.
Closing from the receiver side can cause a panic if the sender tries to send afterward.

6. Key Takeaways

A channel is like a pipe. It can carry data or just a signal.
Use chan<- and <-chan to make sender/receiver intent clear.
Close a channel when you know no more data will be sent, especially for looping receivers.
The sender owns the close operation.

Go’s channels aren’t just for sending data. They’re also about coordination. Thinking in terms of data channels vs signaling channels has made it much easier for me to decide when and how to close them.

What is the Difference between "Yield" and "Return" Keywords in Python?

Beryl Christine Atieno — Thu, 22 May 2025 14:40:17 +0000

If you're learning Python, there's a good chance you've run into the keywords yield and return and wondered what makes them different. At first glance, they both seem to "send data out" of a function, so why does Python have two ways to do this?

For many beginners, myself included, the difference between yield and return can be confusing. They both come from functions, they both output values, but they behave very differently under the hood. In this post, I’ll break down what each keyword does, how they affect a function's behavior, and when you'd want to use one over the other. By the end, you'll not only understand how generators work, but also why they exist and how they can make your Python code cleaner and more efficient.

Let’s clear up the confusion together!

Python Generators

To understand the difference between these keywords it is important to first understand the concept pf Python Generators. Python generators are a special type of function that returns an iterator that can be used to iterate through values. It uses the yield keyword instead of return

How Generators Work

Lazy Evaluation - Generators produce values on demand, only when needed. This makes them memory efficient. In comparison, normal functions produce all values at once, uses memory to store the values.
State Retention - When a generator encounters the yield keyword, it saves its internal state, including execution position and internal variables, and resumes the next time it is called.
Iterator Protocol - generators implement the iterator protocol, meaning they have the __next__() method. Meaning they can be used with iterators such as for loops.
Yield keyword - generators use the yield keyword which produces a value and pauses execution. It returns to its present state when the generator is called again.
Generator Object - When a generator function is called, it doesn't execute immediately. Instead, it returns a generator object, which is an iterator.

For Example:

   def my_generator(n):
    i = 0
    while i < n:
        yield i
        i += 1

gen = my_generator(5)

for value in gen:
    print(value)

# Output:
# 0
# 1
# 2
# 3
# 4

Key Differences with Normal Functions

Return vs Yield

Feature	`return`	`yield`
Stops function?	Yes	No — pauses and can resume
Values produced	One	Many (lazy sequence)
Memory efficiency	Not memory efficient for large data	Very efficient
Function type	Regular function	Generator function

state

Regular functions lose their state after returning. Generators retain their state between successive yield statements.
Usually, a normal funcction exits after the return statement and everything after is not reachable. In comparison, code after yield can still be executed as in the examples below.

Example 1: Using yield

def yield_example():
    print("Start")
    yield 1
    print("After first yield")
    yield 2
    print("After second yield")

gen = yield_example()

for val in gen:
    print("Received:", val)

# Output:
  # Start
  # Received: 1
  # After first yield
  # Received: 2
  # After second yield

Explanation:

"Start" is printed at the start.
First yield 1 pauses the function and gives control to the loop.
"After first yield" is run when the loop calls next() again.
This continues until the generator is exhausted.

Example 2: Using return

def return_example():
    print("Start")
    return 1
    print("This will NOT run")
    return 2

val = return_example()
print("Received:", val)

# Output:
  # Start
  # Received: 1

Explanation:

"Start" is printed.
return 1 ends the function.
The line print("This will NOT run") is never reached.

Use Cases

Working with large datasets: Generators can process large datasets without loading them entirely into memory.
Creating infinite sequences: Generators can produce infinite sequences of values, such as the Fibonacci sequence.
Stream processing: Generators can handle data streams, processing each item as it arrives.
Generating synthetic data: Generators can create synthetic data for testing and development.
Simplifying complex logic: Generators can help simplify code by breaking down complex logic into smaller, manageable parts.

Deploying a FastAPI Book Management API on AWS EC2 with Nginx

Beryl Christine Atieno — Sat, 15 Feb 2025 10:12:11 +0000

Introduction

In this blog post, I'll walk you through the entire process of building a FastAPI Book Management API and deploying it on an AWS EC2 instance with Nginx as a reverse proxy. This guide is perfect for anyone looking to deploy a backend service in a cloud environment.

Setting Up the Project

First, let's create and set up our FastAPI application.

Step 1: Install FastAPI and Uvicorn

pip install fastapi uvicorn

Step 2: Create the Project Structure

mkdir fastapi-book-project && cd fastapi-book-project
mkdir api core tests

Step 3: Define the Book Model and In-Memory Database

Create a schemas.py file inside api/db/ to define the book schema using Pydantic:

from pydantic import BaseModel
from enum import Enum
from typing import Optional

class Genre(str, Enum):
    fiction = "Fiction"
    nonfiction = "Non-Fiction"
    mystery = "Mystery"
    fantasy = "Fantasy"
    horror = "Horror"

class Book(BaseModel):
    id: int
    title: "str"
    author: str
    publication_year: int
    genre: Genre

Step 4: Create API Routes

Create books.py inside api/routes/:

from fastapi import APIRouter, HTTPException
from api.db.schemas import Book, Genre

router = APIRouter()
books_db = []

@router.get("/books", response_model=list[Book])
def get_books():
    return books_db

@router.post("/books", response_model=Book)
def add_book(book: Book):
    books_db.append(book)
    return book

Step 5: Create the Main App Entry Point

In main.py, set up the FastAPI app:

from fastapi import FastAPI
from api.routes import books

app = FastAPI()
app.include_router(books.router, prefix="/api/v1")

@app.get("/healthcheck")
def health_check():
    return {"status": "healthy"}

Step 6: Run the Application Locally

uvicorn main:app --reload

Now, visit http://127.0.0.1:8000/docs to test the API.

Setting Up an AWS EC2 Instance

Step 1: Launch an EC2 Instance

Log in to AWS and navigate to EC2.
Click Launch Instance.
Select Ubuntu 22.04.
Choose an instance type (e.g., t2.micro for free-tier users).
Configure the security group to allow inbound traffic on ports 22 (SSH) and 80 (HTTP).
Launch and download the .pem key file.

Step 2: Connect to the EC2 Instance

ssh -i your-key.pem ubuntu@your-ec2-public-ip

Step 3: Install Required Packages

sudo apt update
sudo apt install -y python3-pip python3-venv nginx

Deploying FastAPI on EC2

Step 1: Clone the Repository

git clone https://github.com/hng12-devbotops/fastapi-book-project.git
cd fastapi-book-project

Step 2: Set Up the Virtual Environment

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Step 3: Run the FastAPI App

uvicorn main:app --host 0.0.0.0 --port 8000 &

Setting Up Nginx as a Reverse Proxy

Step 1: Create a New Nginx Configuration

sudo nano /etc/nginx/sites-available/fastapi

Add the following content:

server {
    listen 80;
    server_name your-ec2-public-ip;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

Step 2: Enable the Configuration

sudo ln -s /etc/nginx/sites-available/fastapi /etc/nginx/sites-enabled
sudo systemctl restart nginx

Step 3: Adjust Firewall Settings

sudo ufw allow 'Nginx Full'
sudo ufw enable

Setting Up CI/CD with GitHub Actions

Step 1: Create Github Actions Workflow

CI: Run Tests

Create a .github/workflows/test.yml file in your repository:

name: Run Tests

on:
  pull_request:
    branches:
      - main

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout Repository
        uses: actions/checkout@v2

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.9'

      - name: Install Dependencies
        run: |
          pip install -r requirements.txt
          pip install pytest

      - name: Run Pytest
        run: pytest

CD: Deploy to AWS EC2

Create a .github/workflows/deploy.yml file in your repository:

name: Deploy to AWS EC2

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout Repository
        uses: actions/checkout@v2

      - name: Deploy to EC2
        uses: appleboy/ssh-action@v0.1.3
        with:
          host: ${{ secrets.EC2_HOST }}
          username: ubuntu
          key: ${{ secrets.EC2_SSH_KEY }}
          script: |
            cd fastapi-book-project
            git pull origin main
            source venv/bin/activate
            pip install -r requirements.txt
            sudo systemctl restart nginx

Step 2: Add GitHub Secrets

In your repository settings, add:

EC2_HOST: Your EC2 Public IP
EC2_SSH_KEY: Your private SSH key content

Now, every push to main will automatically deploy your application.

Accessing the API

Now, visit:

http://your-ec2-public-ip/docs

You should see the Swagger UI for testing the API.

Conclusion

In this blog, we successfully built and deployed a FastAPI Book Management API on AWS EC2 using Nginx as a reverse proxy.

🔹 Key Takeaways:

Built a FastAPI application with CRUD operations.
Set up an AWS EC2 instance.
Deployed the app using Uvicorn and Nginx.
Configured Nginx as a reverse proxy for better performance.
Set up GitHub Actions workflows for continuous integration and continuous testing

Now, your FastAPI app is live and accessible to the world!