From vague brief to architecture: requirements before code

When I built a payment collection platform from scratch, the hardest part was not React or Material-UI. It was working out what the system actually had to do. Code you write against the wrong requirements is just a well-organized mistake.

Ask about the money and the mess first

In anything that handles payments, start with the uncomfortable questions. What happens when a payment fails halfway? Who can see what? What must be recorded, and for how long? These answers shape the architecture far more than the choice of framework.

Write the user journeys in plain language

Before any diagram, I write each journey as a short story: who is the user, what do they want, what do they see at each step, what can go wrong. A client can read and correct a story. They cannot correct a database schema.

Turn stories into a small, honest scope

• What must exist on day one.
• What can wait for version two.
• What is explicitly out of scope, written down.

That last list saves more arguments than any other.

Let AI interrogate the brief

This is where an assistant is genuinely useful. I paste the requirements and ask it to find contradictions, missing edge cases and questions I should ask the client. It does not decide anything, but it finds holes faster than I do at the end of a long day.

Choose the architecture last, and keep it boring

Once the journeys and the scope are clear, the architecture is mostly obvious: a component structure that mirrors the journeys, a clear boundary between the interface and the data, and as few moving parts as the problem allows.

Good requirements analysis feels slow at the start and saves weeks at the end. It is also the part of the job AI is least able to do for you, because it depends on talking to people.