Forem: Moustafa Abdelhamid

From Vibe Coding to Agent Teams: How I Stopped My AI Projects from Turning into a Mess

Moustafa Abdelhamid — Thu, 02 Oct 2025 12:32:19 +0000

1) The Problem: My Code Was Slowly Rotting

After months of using general AIs, I kept seeing the same frustrating pattern: duplicated logic everywhere, alternating libraries for the same job, inconsistent patterns that made no sense, weak tests, and a structure that looked like it was designed by committee (a very confused committee).

2) What I Tried (And Why It Didn't Work)

Spec-first tools like Kiro: They shipped multiple stories beautifully, but when I needed to refactor or fix bugs or change direction? Total disaster. It was like trying to steer a cruise ship with a bicycle.
Mixing tools: Kiro for greenfield + Cursor for edits + Claude for cleaner code helped, but it was like juggling chainsaws. Stability was still terrible.

3) The Breakthrough: Specialist Agents + Organized Docs

Then I had a lightbulb moment: what if I gave AI the same structure as a real development team? I created sub-agents with clear roles under .claude/agents, and anchored each to specific docs:

architect → owns docs/arc42/* (the system design stuff)
tech-lead → owns docs/developer-guide/* (standards + templates)
developer → follows CLAUDE.md + dev guide (the actual coding)
react-ui-designer → Next.js/shadcn; src/app/*, src/components/*
manual-tester → test plans in docs/product/*
product-owner → epics/stories in docs/product/*

4) How It Actually Works (With Code Examples)

Here's how I define each agent:

---
name: architect
description: "Use this agent when you need to create, update, or maintain architectural documentation and decisions for the project."
model: sonnet
color: purple
---

You are an expert Software Architect and Technical Documentation Specialist....

And here's what the generated code looks like - consistent service patterns:

import { z } from 'zod';
import { httpClient } from '@/src/lib/http-client';

export class TopicService {
  private readonly path = '/api/topics';

  async list() {
    const response = await httpClient.get(this.path);
    return z.array(z.object({ id: z.string(), name: z.string() })).parse(response.data);
  }
}

ViewModel + schema validation harmony

import { z } from 'zod';

export const TopicSchema = z.object({ id: z.string(), name: z.string().min(1) });
export type Topic = z.infer<typeof TopicSchema>;

export class TopicViewModel {
  private state: Topic[] = [];
  setTopics(input: unknown) { this.state = z.array(TopicSchema).parse(input); }
  get topics() { return this.state; }
}
...

5) My Documentation Strategy (The Key to Success)

Keep docs short and focused: arc42/dev-guide stays concise and references code; put runnable examples in docs/developer-guide/templates/*
Break up big docs: Shard large markdowns into small files for better agent navigation and recall
Separate concerns: Keep agent definitions reusable and separate from working docs

6) The Results (Spoiler: It Actually Works)

Quality compounds instead of decays: My codebase gets better over time, not worse
Refactors and bug fixes get cheaper: Changes are easier because patterns are consistent
I still review/fix, but my effort drops over time: As agents align with the repo, they make fewer mistakes

I'll publish the exact documentation method per agent in a follow-up, plus the specific design patterns I followed. If your AI projects are degrading after a few prompts (like mine were), this approach might be worth trying.

🚀 Getting Started with Deepgram Nova-3 for Real-Time Speech-to-Text

Moustafa Abdelhamid — Tue, 25 Feb 2025 14:29:03 +0000

Introduction

Deepgram’s Nova-3 is the latest evolution in speech-to-text AI, offering real-time multilingual transcription, improved accuracy, and instant vocabulary updates. If you’re working on AI-driven transcription, you’ll want to explore this model.

At Transgate.ai, we took our first look at Nova-3, and the results were promising! (Check out our insights here: Transgate’s article).

In this guide, let’s get started with Nova-3 by setting up a simple transcription pipeline using Deepgram’s API.

Step 1: Set Up Your Deepgram API Key

First, sign up at Deepgram and grab your API key.

Then, install the Deepgram SDK:

npm install @deepgram/sdk

Step 2: Basic Real-Time Transcription

Using Node.js, we’ll create a simple WebSocket connection to transcribe live audio.

import { Deepgram } from '@deepgram/sdk';
import WebSocket from 'ws';
import fs from 'fs';

// Replace with your Deepgram API key
const deepgramApiKey = 'YOUR_DEEPGRAM_API_KEY';
const audioFile = 'sample.wav'; // Path to your audio file

const deepgram = new Deepgram(deepgramApiKey);

const ws = new WebSocket('wss://api.deepgram.com/v1/listen', {
  headers: { Authorization: `Token ${deepgramApiKey}` },
});

ws.on('open', () => {
  console.log('Connected to Deepgram WebSocket');
  const stream = fs.createReadStream(audioFile);
  stream.on('data', (chunk) => ws.send(chunk));
  stream.on('end', () => ws.close());
});

ws.on('message', (message) => {
  const transcript = JSON.parse(message);
  console.log('Transcript:', transcript.channel.alternatives[0].transcript);
});

ws.on('close', () => console.log('Connection closed'));

What This Script Does:

✅ Connects to Deepgram’s real-time transcription API

✅ Streams an audio file for processing

✅ Logs transcriptions in real time

Step 3: Customizing the Transcription

Nova-3 supports custom vocabulary and language models. To enhance accuracy, pass custom parameters like this:

const ws = new WebSocket('wss://api.deepgram.com/v1/listen?model=nova-3&language=en&keywords=AI,transcription');

This boosts accuracy for domain-specific terms like AI, medical jargon, or industry-specific words.

Final Thoughts

Deepgram’s Nova-3 is fast, multilingual, and highly customizable. It’s a powerful tool for anyone building real-time voice applications.

🚀 Next Steps:

Try it with your own audio files 🎙️
Experiment with different languages 🌍
Fine-tune with custom vocabulary 🔧

Check out Transgate.ai’s first impressions: Read here.

What do you think about Nova-3? Let’s discuss in the comments! 👇

Deploy your Youtube downloader on Cloudrun

Moustafa Abdelhamid — Sun, 19 Jan 2025 05:38:11 +0000

Here is a beginner-friendly step-by-step tutorial to create and deploy a YouTube video downloader service on Google Cloud Run using FastAPI. The tutorial assumes basic Python knowledge but no prior production deployment experience. Each step is explained in detail to help you understand what you're doing and why it's important.

Step 1: Set Up a Python Project with Pyenv and Virtualenv

What is Pyenv?

Pyenv is a tool to manage multiple Python versions on your system. It ensures your project uses the right Python version without interfering with global settings.

What is Virtualenv?

Virtualenv creates isolated environments for Python projects. This ensures your project dependencies don't conflict with others.

Instructions:

Install Pyenv:

   curl https://pyenv.run | bash

Add the following to your shell configuration file (~/.bashrc, ~/.zshrc, etc.):

   export PATH="$HOME/.pyenv/bin:$PATH"
   eval "$(pyenv init --path)"
   eval "$(pyenv virtualenv-init -)"

Restart your terminal or run:

   source ~/.bashrc  # or ~/.zshrc

Install a Python Version:

   pyenv install 3.10.12
   pyenv global 3.10.12

Set Up Virtualenv:

   python -m venv venv
   source venv/bin/activate

Create a Project Directory:

   mkdir youtube-downloader
   cd youtube-downloader

Create a requirements.txt File: Add the following:

   fastapi
   uvicorn

Install the dependencies:

   pip install -r requirements.txt

Create a Hello World API:
- File: app.py

   from fastapi import FastAPI

   app = FastAPI()

   @app.get("/")
   def read_root():
       return {"message": "Hello, World!"}

Run the app locally:
```
 uvicorn app:app --reload
```

Step 2: Create a Docker Image and Run Locally

What is Docker?

Docker allows you to package your application and its dependencies into a container that can run consistently anywhere.

Instructions:

Create a Dockerfile:

   FROM python:3.10-slim

   WORKDIR /app

   COPY requirements.txt requirements.txt
   RUN pip install -r requirements.txt

   COPY . .

   CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8080"]

Build and Run the Docker Image:
- Build:
```
 docker build -t youtube-downloader .
```

Run:

 docker run -p 8080:8080 youtube-downloader

Access the App: Open your browser and go to http://localhost:8080.

Step 3: Push the Docker Image to Google Container Registry (GCR)

Why Use GCR?

Google Container Registry stores your Docker images securely in Google Cloud, making them accessible for deployment.

Instructions:

Set Up GCP Authentication: Install the Google Cloud CLI:

   curl -O https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-cli-<latest_version>-linux-x86_64.tar.gz
   tar -xvf google-cloud-cli-<latest_version>-linux-x86_64.tar.gz
   ./google-cloud-sdk/install.sh
   gcloud auth login

Tag and Push the Image:

Tag the image:

 docker tag youtube-downloader gcr.io/<your-project-id>/youtube-downloader

Push the image:

 docker push gcr.io/<your-project-id>/youtube-downloader

Step 4: Deploy Using GitHub Actions

Why GitHub Actions?

GitHub Actions automates your CI/CD process, making deployment seamless.

Instructions:

Create a GitHub Repository and Push Code:

   git init
   git add .
   git commit -m "Initial commit"
   git branch -M main
   git remote add origin <your-repository-url>
   git push -u origin main

Create a .github/workflows/deploy.yml File:

   name: Deploy to Cloud Run

   on:
     push:
       branches:
         - main

   jobs:
     deploy:
       runs-on: ubuntu-latest
       steps:
       - name: Checkout code
         uses: actions/checkout@v3

       - name: Set up Google Cloud CLI
         uses: google-github-actions/setup-gcloud@v1
         with:
           project_id: <your-project-id>
           service_account_key: ${{ secrets.GCP_SA_KEY }}

       - name: Authenticate Docker
         run: gcloud auth configure-docker

       - name: Build and Push Docker Image
         run: |
           docker build -t gcr.io/<your-project-id>/youtube-downloader .
           docker push gcr.io/<your-project-id>/youtube-downloader

       - name: Deploy to Cloud Run
         run: |
           gcloud run deploy youtube-downloader \
             --image gcr.io/<your-project-id>/youtube-downloader \
             --platform managed \
             --region us-central1 \
             --allow-unauthenticated

Add a Secret for GCP Service Account Key: In your GitHub repository settings, add GCP_SA_KEY as a secret containing your GCP service account key.

Step 5: Deploy Using Command Line

Instructions:

Deploy to Cloud Run:

   gcloud run deploy youtube-downloader \
     --image gcr.io/<your-project-id>/youtube-downloader \
     --platform managed \
     --region us-central1 \
     --allow-unauthenticated

Update GitHub Actions for Command Line Deployment: Add steps in deploy.yml to notify about the deployment process.

Step 6: Add YouTube Video Metadata and Download Endpoints

Instructions:

Install pytube:

   pip install pytube

Update app.py:

   from fastapi import FastAPI
   from pytube import YouTube

   app = FastAPI()

   @app.get("/metadata")
   def get_metadata(video_url: str):
       yt = YouTube(video_url)
       return {
           "title": yt.title,
           "description": yt.description,
           "duration": yt.length,
           "thumbnail": yt.thumbnail_url
       }

   @app.get("/download")
   def download_video(video_url: str, quality: str = "high"):
       yt = YouTube(video_url)
       stream = yt.streams.filter(progressive=True, file_extension="mp4").order_by("resolution")
       if quality == "low":
           video = stream.first()
       elif quality == "medium":
           video = stream[len(stream) // 2]
       else:
           video = stream.last()

       file_path = video.download(output_path="/tmp")
       return {"file_path": file_path}

Conclusion

Now you've created a FastAPI-based YouTube downloader deployed on Cloud Run! This service includes endpoints for retrieving metadata and downloading videos with quality options. Each step builds on the previous one, ensuring a smooth learning process for beginners.

Redux vs. Context.Provider: Choosing State Management in React Applications

Moustafa Abdelhamid — Wed, 28 Aug 2024 05:57:06 +0000

TL;DR

Use Redux when you need a robust and scalable solution for complex state management, especially in large applications with many components interacting with the state.
Use Context.Provider when your state management needs are simpler, more localized, or when you want to avoid the overhead of Redux in smaller applications.

Let's Begin

When managing state in a React or Next.js application, the choice between Redux and Context.Provider hinges on the complexity and scale of the state you're handling. Redux excels in managing complex, frequently updated global state with multiple consumers, ensuring performance optimization and better scalability. On the other hand, Context.Provider is simpler and more suitable for localized state management, avoiding the overhead that Redux introduces. This article delves into the pros and cons of each approach, illustrated with code examples, and explores how Redux can be optimized for performance in real-world scenarios.

Redux vs. Context.Provider: When to Use Which?

Redux

Redux is a powerful state management library that provides a global store to hold your application's state. It allows for predictable state updates, fine-grained control over rendering, and is well-suited for large applications where multiple components need to access and modify the state.

Context.Provider

Context.Provider, on the other hand, is built into React and is ideal for smaller, more straightforward state management tasks. It's perfect for cases where the state is relatively simple, and only a few components need to consume it. However, as the state becomes more complex and needs to be accessed by many components, Context.Provider can lead to performance issues due to unnecessary re-renders.

When to Use Redux:

Complex State Management:
- Global State with Many Consumers: If your application has a complex state that needs to be shared across many components, Redux is a better choice. It provides a centralized store and a structured way to manage state changes through actions and reducers.
- Predictable State Management: Redux’s strict unidirectional data flow and immutability make it easier to predict and trace state changes, which is especially useful in large or complex applications.
Debugging and Developer Tools:
- Redux DevTools: Redux comes with powerful debugging tools like Redux DevTools, which allow you to inspect state changes, replay actions, and time-travel through state changes. This can be invaluable for debugging complex applications.
Middleware for Side Effects:
- Handling Asynchronous Logic: If your application involves complex asynchronous logic (e.g., API calls, side effects), Redux middleware like redux-thunk or redux-saga provides a robust way to handle these scenarios.
- Centralized Middleware Management: Redux allows you to add middleware to the entire state management process, making it easier to manage side effects, logging, and other cross-cutting concerns in a centralized way.
Scalability:
- Large Applications: Redux scales well with larger applications, especially when the application grows in complexity, and there is a need to maintain a consistent way of managing state across many parts of the app.
- Modular Code Structure: Redux encourages a modular structure (actions, reducers, selectors), which can be beneficial for maintaining and scaling large codebases.

When to Use Context.Provider:

Simple or Localized State:
- Localized State Management: If you have a relatively simple state that doesn't need to be accessed or modified by many components, Context.Provider is often sufficient and more lightweight than Redux.
- Small to Medium Applications: For smaller applications where state management is not overly complex, using Context.Provider can reduce the overhead of adding Redux.
Avoiding Boilerplate:
- Less Boilerplate: Redux comes with more boilerplate (actions, reducers, etc.), whereas Context.Provider allows for simpler and more direct state management without the need for additional libraries.
- Direct State Sharing: If you only need to share state between a few components, Context.Provider allows you to do this without the complexity of Redux.
No Need for Middleware:
- Simple State Changes: If your application doesn’t require middleware for handling asynchronous actions or side effects, Context.Provider is more straightforward and less complex.
- Direct API Calls: In many cases, API calls and side effects can be handled directly in components or through custom hooks, making the additional abstraction of Redux unnecessary.
Component-Themed or Configuration State:
- Theme/Localization: Context.Provider is often used for managing theme, localization, or other configuration states that don’t change frequently and don’t need complex state management.
- Component-Level State: When managing state that is specific to a subtree of your component tree, Context.Provider provides a way to scope that state to just the components that need it.

When to Combine Redux and Context.Provider:

In some cases, you might want to use both Redux and Context.Provider in the same application. For example:

Global State with Local Contexts: Use Redux for global state management and Context for specific contexts like theming, authentication, or forms.
Performance Optimization: You might use Context to avoid unnecessary re-renders when only a part of your component tree needs to access or modify state.

Explaining With Code

Let's explore two scenarios in a Next.js application where Redux can solve some downsides of Context.Provider and another scenario where Context.Provider is a simpler and more appropriate solution.

1. Scenario Where Redux Solves Context Provider's Downsides

Problem: Complex State with Frequent Updates and Multiple Consumers

Imagine you have a Next.js app where multiple components across different pages need to access and update a shared state. The state is complex and changes frequently (e.g., managing a shopping cart in an e-commerce app). With Context.Provider, every state update could trigger unnecessary re-renders across the entire component tree.

Solution with Redux: Redux allows you to manage this complex state efficiently with a centralized store, reducers, and actions. It minimizes unnecessary re-renders and provides better performance through selectors and memoization.

// store.ts
import { configureStore } from '@reduxjs/toolkit';
import cartReducer from './cartSlice';

export const store = configureStore({
  reducer: {
    cart: cartReducer,
  },
});

// cartSlice.ts
import { createSlice, PayloadAction } from '@reduxjs/toolkit';

interface CartState {
  items: { id: number; name: string; quantity: number }[];
}

const initialState: CartState = { items: [] };

const cartSlice = createSlice({
  name: 'cart',
  initialState,
  reducers: {
    addItem(state, action: PayloadAction<{ id: number; name: string }>) {
      const item = state.items.find(i => i.id === action.payload.id);
      if (item) {
        item.quantity += 1;
      } else {
        state.items.push({ ...action.payload, quantity: 1 });
      }
    },
    removeItem(state, action: PayloadAction<number>) {
      state.items = state.items.filter(i => i.id !== action.payload);
    },
  },
});

export const { addItem, removeItem } = cartSlice.actions;
export default cartSlice.reducer;

// index.tsx
import { useSelector, useDispatch } from 'react-redux';
import { RootState } from '../store';
import { addItem, removeItem } from '../cartSlice';

export default function Home() {
  const cartItems = useSelector((state: RootState) => state.cart.items);
  const dispatch = useDispatch();

  return (
    <div>
      <h1>Shopping Cart</h1>
      <ul>
        {cartItems.map(item => (
          <li key={item.id}>
            {item.name} - {item.quantity}
            <button onClick={() => dispatch(removeItem(item.id))}>Remove</button>
          </li>
        ))}
      </ul>
      <button onClick={() => dispatch(addItem({ id: 1, name: 'Item 1' }))}>
        Add Item 1
      </button>
    </div>
  );
}

Why Redux is Better Here:

Avoids Unnecessary Re-renders: The useSelector hook ensures that only components that depend on specific parts of the state will re-render.
Scalability: Redux handles complex state logic across multiple components and pages, making the code more maintainable as the application grows.

Here is the rest of the article formatted in Markdown:

2. Scenario Where Redux is Overkill and Context Provider is Simpler

Problem: Simple State Management for Theming

Consider a scenario where you want to manage the application's theme (light/dark mode). The state is simple, and only a few components need access to it.

Solution with Context.Provider:

Using Context.Provider is more straightforward and lightweight for this case.

// ThemeContext.tsx
import { createContext, useState, useContext, ReactNode } from 'react';

interface ThemeContextProps {
  theme: 'light' | 'dark';
  toggleTheme: () => void;
}

const ThemeContext = createContext<ThemeContextProps | undefined>(undefined);

export const ThemeProvider = ({ children }: { children: ReactNode }) => {
  const [theme, setTheme] = useState<'light' | 'dark'>('light');

  const toggleTheme = () => {
    setTheme(prevTheme => (prevTheme === 'light' ? 'dark' : 'light'));
  };

  return (
    <ThemeContext.Provider value={{ theme, toggleTheme }}>
      {children}
    </ThemeContext.Provider>
  );
};

export const useTheme = () => {
  const context = useContext(ThemeContext);
  if (!context) {
    throw new Error('useTheme must be used within a ThemeProvider');
  }
  return context;
};

// index.tsx
import { useTheme } from '../ThemeContext';

export default function Home() {
  const { theme, toggleTheme } = useTheme();

  return (
    <div style={{ background: theme === 'light' ? '#fff' : '#333', color: theme === 'light' ? '#000' : '#fff' }}>
      <h1>Current Theme: {theme}</h1>
      <button onClick={toggleTheme}>Toggle Theme</button>
    </div>
  );
}

// _app.tsx
import { ThemeProvider } from '../ThemeContext';

export default function MyApp({ Component, pageProps }) {
  return (
    <ThemeProvider>
      <Component {...pageProps} />
    </ThemeProvider>
  );
}

Why Context.Provider is Better Here:

Simplicity: Theming is a simple, localized state, and Context.Provider provides a minimal and direct way to manage it without the overhead of Redux.
Less Boilerplate: There's no need for actions, reducers, or a store. The state is managed directly with React hooks, making the codebase smaller and easier to understand.

How Redux Helped Us at Transagate.ai

At Transagate.ai, Redux has significantly improved our speed of development. By centralizing state management, we've been able to deliver features quickly without compromising on performance. The ability to fine-tune re-renders and manage complex state effectively has unleashed our creativity, allowing us to build robust and scalable solutions. Redux's predictable state updates and extensive ecosystem have made it a critical part of our development process, enabling us to focus on innovation and user experience.