Voice Agent Monorepo: Debugging Strategy in a Multi-Layer Architecture

Debugging and Fixing Bugs: How a Voice Agent Project Stays on Track

The task was simple on the surface: help debug and fix issues in a growing Python and Next.js monorepo for a voice-agent project. But stepping into this codebase meant understanding a carefully orchestrated system where a FastAPI backend talks to a Telegram bot, a web API, and a Next.js frontend—all coordinated through a single AgentCore.

The first thing I did was read the project guidelines stored in docs/tma/. This wasn’t optional—the developer had clearly learned that skipping this step leads to missed architectural decisions. The project uses a fascinating approach to error tracking: before fixing anything new, I check docs/ERROR_JOURNAL.md to see if similar bugs had been encountered before. This pattern prevents solving the same problem twice and builds institutional knowledge into the codebase itself.

The architecture deserves a moment of attention because it shapes how bugs get fixed. There’s a single Python backend with multiple entry points: telegram_main.py for the Telegram bot and web_main.py for the web API. Both feed into AgentCore—the true heart of the business logic. The database is SQLite in WAL mode, stored at data/agent.db. On the frontend side, Next.js 15 with React 19 and Tailwind v4 handles the UI. This separation of concerns means bugs often have clear boundaries: they’re either in the backend’s logic, the database layer (handled via aiosqlite for async access), or the frontend’s component rendering.

What surprised me was how seriously the team takes validation. Every time code changes, there are verification steps: the backend runs a simple Python import check (python -c "from src.core import AgentCore; print('OK')"), and the frontend builds itself (npm run build). These aren’t fancy integration tests—they’re smoke tests that catch breaking changes immediately. I’ve seen teams skip this, and they regret it when a typo silently breaks production.

The git workflow is interesting too. Commits are straightforward: no ceremony, no Co-Authored-By lines, just clear messages. The team avoids git commit --amend entirely, preferring fresh commits that tell a linear story. This makes debugging through git history far easier than hunting through amended commits trying to understand what actually changed.

One architectural lesson worth noting: the Vercel AI SDK Data Stream Protocol for SSE (Server-Sent Events) has a strict format. Deviating from it, even slightly, breaks streaming on the client side. This is exactly the kind of subtle bug that makes developers pull their hair out—the server sends data, the network delivers it, but the frontend sees nothing because one field was named wrong or wrapped differently than expected.

The team also uses subprocess calls to the Claude CLI rather than SDK integration. This decision trades some complexity for reliability: the subprocess approach doesn’t depend on SDK version mismatches or authentication state issues.

By the end, the debugging process reinforced something important: bugs rarely occur in isolation. They’re symptoms of architectural misunderstandings, incomplete documentation, or environment inconsistencies. The voice-agent project’s approach—reading docs first, checking error journals, validating after every change—turns debugging from a frustrating whack-a-mole game into a systematic process where each fix teaches the team something new.

😄 How did the programmer die in the shower? He read the shampoo bottle instructions: Lather. Rinse. Repeat.