From Idea to Specs: Planning HandyFEM's Architecture with Claude.ai - Specs Driven development.

What is HandyFEM?

HandyFEM is a web app I'm building to connect women professionals in technical trades (electricians, plumbers, carpenters...) with clients who are looking for them. It's both a real product I plan to launch and a portfolio project — so it has to be well-built, secure, and professional.
I'm documenting the entire process as I go. This is the first post in the series.

The problem with jumping straight into code

Without a solid plan, we can find several problems, features that don't connect, components that have to be rebuilt, a design that makes sense locally but not globally.
So I decided to do it properly — specs first, code second.
I used Claude.ai as a thinking partner throughout this process. Not just to generate content, but to challenge my decisions, suggest alternatives, and help me document everything in a structured way.

Step 1 — Reviewing the user flow

I already had a flow diagram from a previous iteration of the project. We started there. I put my diagram to be judged by Claude and it identified a few issues or things that were unclear, even though I had the ideas in my mind. The most important decision came from a simple question I hadn't fully answered: can one person be both a client and a professional?
I went with a single account with a base client role, with the ability to activate a professional profile from the dashboard later. Same pattern as LinkedIn.

Step 2 — Defining the MVP scope

With the corrected flow, we mapped out all the features. Then we cut ruthlessly.

What's in the MVP:

Landing page

• Sign up / Log in + email verification
• Public directory with search and filters
• Professional public profile
• Unified dashboard with role toggle
• Professional onboarding (4-step flow)
• Basic chat

What's out (v2):

• Admin panel for profile moderation
• Payments
• Geolocation / map view
• Emergency button
• Push notifications The Admin Panel was a tough cut — it was in my original diagram and it's genuinely important for safety. But it adds significant complexity and the MVP can function without it (profiles go live directly). It'll be the first thing added in v2.

Step 3 — Stack decisions (and why)

I was already planning to use Next.js + Supabase, but I took the time to articulate why:

• Next.js — the professional directory needs to be indexed by Google. If someone searches "female electrician Barcelona", I want HandyFEM to show up. That requires SSR, which React alone doesn't give you. Next.js also has API routes built in, so no separate backend for simple logic.

• Supabase — covers auth, PostgreSQL, realtime (for chat), and storage (for profile photos and portfolio) in one service. It has a generous free tier for an MVP and integrates cleanly with Next.js.
  shadcn/ui — component library that copies code directly into your project rather than installing as a dependency. Accessible by default, unstyled, and you apply your own design tokens. Very common in Next.js projects right now.

• Tailwind CSS — utility-first styling that works perfectly with shadcn.

Step 4 — Writing the specs

This is where most of the session went.
I've been experimenting with a specs-driven development approach — writing detailed specifications for each screen and component before writing any code. The idea is that a well-written spec becomes the prompt for Claude Design, and a well-prompted Claude Design produces clean, copy-paste-ready code on the first try.

For each component in the Design System, we documented:

• All variants and sizes
• All states (default, hover, focus, error, disabled, loading)
• Exact color tokens
• Accessibility requirements (aria labels, focus rings, touch targets)
• shadcn/ui implementation notes

And for each screen:

• Layout and sections
• All interactive elements
• All states (loading skeletons, empty states, error states)
• SEO considerations
• Technical notes for Supabase queries

The full spec document is saved in /docs in the project repo.

What I learned

1. Specs are not overhead — they are the work. The time I spent writing specs today will save me hours of refactoring later. And they double as documentation, which makes the project look serious in a portfolio context.
2. Claude works best as a thinking partner, not an autocomplete. The most valuable moments weren't when it generated content — they were when it pushed back on my decisions or asked clarifying questions I hadn't considered.
3. Cut early, cut ruthlessly. Every feature that goes into an MVP is a feature that needs to be designed, built, tested, and maintained. The Admin Panel will be better in v2 anyway — I'll have real users to learn from.

What's next
Next post: taking all of this into Jira — turning the specs into epics, stories, and tasks so the build phase has clear structure.
After that: the Design System in code, and then building screen by screen.