How I Directed an AI Agent Through 3 Real Architecture Decisions, and What I Learned

alejandraarochaovalles — Mon, 07 Sep 2026 12:29:35 +0000

In two weeks, I built Retro Dynamics Agent, an app that generates retrospective activities for teams, facilitates them on a real-time collaborative board, and turns the outcomes into Jira or Azure DevOps tickets.

I built it working with an AI coding agent, Claude Code, throughout almost the entire process: design, implementation, production debugging, and documentation.

I do not want to tell another “I used AI and it wrote the code for me” story. We have heard that one enough.

What I found more interesting were the parts of the project where there was no obvious answer in a tutorial, and how the work was divided in those situations.

I defined the constraints and made the underlying decisions. The agent proposed concrete technical solutions and implemented them. Then the responsibility for verifying that everything actually worked, not just that it compiled, came back to me.

Here are three examples from the project.

1.- Connecting to Jira without server-side sessions or frontend memory

I wanted any team to be able to connect its own Jira account through OAuth, instead of relying on a global token that only I could configure.

The problem was that my application runs entirely on serverless functions. Nothing stays in memory between requests, and the frontend does not maintain its own state either.

No localStorage. No router.

An OAuth login means leaving the application, authenticating with Atlassian, and then coming back.

But coming back to what, if nothing remembers which screen you were on?

Before touching the code, I asked the agent to create a complete implementation plan, including the files that would need to change, the design decisions, and the scope.

I reviewed that plan as if it were a pull request from another developer.

I made decisions such as:

For now, only Jira would use OAuth. Azure DevOps would keep its manual token flow because setting up OAuth there is considerably more involved.

Tokens would be encrypted before being stored in the database, never saved as plain text.

And the existing manual connection form would remain available as a fallback instead of being removed.

The agent solved the specific technical problem by proposing a signed HMAC state parameter.

Besides validating the OAuth callback, that state contains the ID of the active session.

Because the frontend does not remember anything on its own, carrying that session ID through the OAuth round trip is what allows the application to restore the correct screen when the user returns from Atlassian.

I verified the implementation myself in production.

That is where I found a bug that no code review would have caught.

Adding a single dependency brought down the entire application, including the health check.

The reason was that Vercel was installing dependencies using a different lockfile from the one I thought it was using, even though a comment in my own code had been claiming the opposite for months.

I found the problem by reading real production logs in the dashboard, not by analyzing the code.

2.- The real-time board: why I did not use the database I already had

The board needs to synchronize note dragging, votes, and participant cursors in real time.

I already had Postgres through Supabase, so using the same provider’s real-time system would have been the simplest option from an integration perspective.

No additional synchronization provider. Less infrastructure.

I decided not to use it.

The board is free-form, closer to Miro than to a fixed-column board.

For that kind of canvas, Supabase Realtime would have required me to implement more synchronization and conflict-handling logic than I wanted to own.

With free dragging, live cursors, and concurrent edits, two people trying to interact with the same object at the same time is not an edge case. It is something that will happen regularly.

Liveblocks is specifically designed around collaborative canvas-style experiences.

I accepted the cost of maintaining two providers rather than building and maintaining that synchronization layer myself.

The agent proposed the synchronization model:

Liveblocks is the source of truth while the session is active.

When the session ends, the final state is persisted to Postgres in a single operation instead of writing to the database on every movement.
The agent also corrected an assumption I had made early on.

I originally thought notes and groups needed separate database tables.

They did not.

They are generated and consumed together, never independently, so separating them would have introduced complexity without giving me any real benefit.

Verifying this architecture required more than reading the code.

At that point I did not have a convenient real Liveblocks environment available to test interactively from the browser.

So we created a script that connects two real Liveblocks clients without a browser.

One client makes a change.

The second client must receive it immediately.

That test validated the architecture better than any code review could.

3.- Voting without people accidentally overwriting each other

During the voting phase, any participant can vote for a note or remove their vote at any time.

Several people can do this simultaneously.

If the vote total were stored as a single shared counter, concurrent writes could overwrite each other.

I decided that voting should be reversible and unlimited per participant.

That sounds like a product decision, and it is.

But it completely changes the data model.

Instead of everyone updating the same counter, each participant writes only their own list of voted notes.

The total for a note is calculated by counting how many participant lists contain that note.

No two participants ever compete to write the same value.

Instead of solving a concurrency conflict, the model removes the conflict altogether.

When the session closes, only the final vote count is persisted. The system does not keep a record of who voted for what.

The counting logic was tested as standalone functions with no dependency on Liveblocks types.

That means the correctness of the calculation can be verified without needing a real-time connection running at all.

What kept repeating across all three decisions

The valuable part was never that the AI could write the code.

The same pattern appeared every time.

Before implementing any non-trivial feature, we discussed the architecture first.

I defined the constraints, chose which trade-offs were acceptable, and decided which risks I was willing to take.

The agent was consistently good at proposing and implementing solutions within those constraints.

But my work increasingly moved away from translating decisions into syntax and toward deciding what to build, which trade-offs to accept, and what evidence I needed before I could say that something actually worked.

In the OAuth integration, that evidence came from production logs.

In the real-time architecture, it came from two real connected clients.

In the voting model, it came from isolated functions that could be tested independently.

The more capable coding agents become, the less interesting “who wrote the code?” becomes as a question.

The more interesting question is:

Who defined the constraints, chose the trade-offs, and decided what counted as proof that the system worked?

Everything from this project is documented in the repository, including the production incident and the root cause once I found it.

GitHub - alejandraarochaovalles/retro-dynamics-agent
Contribute to alejandraarochaovalles/retro-dynamics-agent development by creating an account on GitHub.
github.com

Also, here is the link to try the application in production: https://retro-dynamics-agent-gcdg.vercel.app/

DEV Community: alejandraarochaovalles

How I Directed an AI Agent Through 3 Real Architecture Decisions, and What I Learned