DEV Community: Steve McDougall

The Mid-Level Mindset

Steve McDougall — Tue, 19 May 2026 12:01:05 +0000

We started this series with a single paragraph from a fictional client. A vague brief about a tool where clients can submit requests and developers can track them. Nine articles later, we have a fully interrogated set of requirements, a collection of properly shaped features, a trusted data model, a system architecture diagram, a layered application design, and a sequenced build plan with individual tickets ready to pick up.

We have not written a single migration. We have not scaffolded a controller or configured a route. And yet the most important work is done.

That is the point this entire series has been building towards.

What Actually Changed

Think back to where we started. The instinct to open your editor the moment a brief lands. The pull towards action, towards visible progress, towards the feeling of productivity that comes from lines of code appearing on a screen.

That instinct is not wrong. It is just premature.

What changed over the course of this series is not the tools you have access to. Laravel was always capable of building Clarity. The database was always going to need an organisations table and a users table and a requests table with the right foreign keys. The layered architecture was always the right approach. None of that knowledge was new.

What changed is the order of operations. The willingness to invest thinking before typing. The discipline to ask "what do I not yet know?" before asking "how do I build this?". That shift in sequence is what defines the move from junior to mid-level, and it compounds over time in ways that are hard to see until you look back.

What Mid-Level Actually Means

The industry uses the term loosely, but when I think about what a mid-level developer actually is, I come back to a few specific qualities.

A mid-level developer can be handed a brief and produce something buildable from it without constant direction. Not because they know every answer upfront, but because they know which questions to ask and how to find the answers before they start building.

A mid-level developer understands that the most expensive code to write is code that solves the wrong problem. They protect against that by doing the thinking work first.

A mid-level developer can communicate the shape of a problem to other people. They can draw a diagram, write a pitch, or explain a data model in plain language. That communication ability is what makes them valuable beyond their own output.

A mid-level developer knows when to apply a pattern and when to leave it out. They have moved past the phase of applying everything they have learned uniformly, and into the phase of using judgment about what a given situation actually needs.

None of those things are about programming language knowledge or framework familiarity. They are about thinking habits. And thinking habits are built through deliberate practice, not through reading documentation.

The Process in Brief

If you take one thing from this series, let it be this sequence. Apply it to every project you work on, every feature you are handed, every ticket that lands in your queue.

First, interrogate the requirement. Surface every unstated assumption. Ask the business questions before the technical ones. Write down what you know and what you do not know yet.

Second, define the actors and their needs. Write user stories with acceptance criteria. Make sure every feature has a clear definition of done that is anchored to a real user getting real value.

Third, shape the work. Decide how much it is worth before you estimate how long it will take. Draw the edges of what is included and write down what is explicitly out of scope.

Fourth, model the data. Draw the ERD before you touch a migration. Check every relationship for cardinality, every foreign key for direction, every array in a column for the related table it should be.

Fifth, draw the system. Show the major components, how they connect, where external dependencies sit, and where data flows. Write the plain-language description. If you cannot describe it clearly in prose, the diagram needs more work.

Sixth, sequence the build. Map the dependencies. Identify what has to exist before each feature can be built. Break each feature into discrete tickets with clear definitions of done.

Then build.

Where to Take This

This process is a foundation, not a ceiling. As you apply it to more projects, you will start to develop instincts about where the complexity hides in a brief, which ERD patterns recur across different problem domains, and which architectural decisions tend to cause the most pain if you get them wrong.

Those instincts are what senior developers have. They have run this process enough times, on enough different problems, that parts of it become automatic. They spot the ambiguous noun in a brief before the client finishes reading it to them. They see the missing pivot table in a data model before anyone has drawn it. They know from experience which features sound small and turn out to be enormous.

You build those instincts by doing the work deliberately, even when it feels slower than just opening your editor. Especially then.

A few resources worth spending time with as you continue:

Ryan Singer's Shape Up is the deepest treatment of the shaping process I have found. It is free, it is short, and every developer who works on product software should read it.

Jeff Patton's User Story Mapping goes further on the user story side than we covered here, and is particularly useful when you are working on complex products with many different user types.

John Ousterhout's A Philosophy of Software Design is the best writing I know of on the question of where complexity comes from and how to fight it. It will change the way you think about every design decision you make.

And then there is the work itself. Take a project, real or fictional, and run the full process from brief to build plan before you write the first line of code. Do it again on the next one. The process becomes faster with practice, but it never stops being valuable.

A Final Word on Clarity

We built something real in this series. Clarity started as a vague paragraph and became a fully designed application with a clear data model, a considered architecture, and a sequenced plan ready to execute.

We never wrote a migration. We never wrote a controller. But anyone who has followed this series could pick up the build plan from article nine and start building Clarity today, with confidence that the foundations are solid and the direction is clear.

That confidence, grounded in thinking rather than assumption, is what the mid-level mindset feels like from the inside.

It is worth developing.

Thank you for following along with From Requirements to Reality. If this series helped you think differently about how you approach a problem before you start building, that is exactly what it was designed to do.

From Diagram To Implementation Plan

Steve McDougall — Tue, 19 May 2026 12:01:04 +0000

We have covered a lot of ground in this series. We started with a vague client brief, interrogated it until the real requirements surfaced, wrote user stories with acceptance criteria, shaped those stories into bounded features, drew an ERD, built a system diagram, and looked at how layers give every piece of code a clear home.

That is the full design process. Now we need to translate it into something a developer can actually execute.

This article is about sequencing. Taking everything we have designed and turning it into an ordered build plan that respects dependencies, minimises wasted work, and lets you deliver value as early as possible.

Why Sequence Matters

A common junior developer instinct is to start with the most interesting part. The feature that sounds fun to build, the component that uses a technology you want to learn, the part of the system that feels most novel. That is understandable, but it is usually the wrong starting point.

The right starting point is the foundation. The code that everything else depends on. If you build the request management system before you have authentication in place, you will either need to stub out user identity in ways that do not reflect reality, or you will need to go back and retrofit it later. Both options cost time you cannot get back.

Sequencing is the discipline of asking: what has to exist before this can be built? Work backwards from every feature until you hit something that has no dependencies, and that is where you start.

Identifying Dependencies

Let me map the dependencies for the Clarity features we shaped in article four.

Client authentication and onboarding has no dependencies on other features. It needs the database and the user model, but those are foundational. This goes first.

Team member management depends on authentication being in place (admins need to be logged in to invite people) and on the user model having role support. It is almost as foundational as authentication itself, and it needs to exist before any meaningful testing of the application can happen.

Request submission depends on authentication (to know who is submitting) and on organisations existing (to associate the request correctly). Team member management should also be done first so there is at least one admin user to test with.

Request status and assignment depends on requests existing. It also depends on team members existing, because you cannot assign a request to a developer who does not exist in the system. This comes after submission.

Comment thread depends on requests existing. It could technically be built in parallel with request status and assignment, but sharing the request detail page means they are better built in sequence to avoid integration friction.

Request list views depend on requests existing and on the basic request detail page being in place. This should be the last feature built, because it is a read view over data that all the other features create.

The Build Order

With dependencies mapped, the sequence becomes clear:

Foundations: database, models, migrations, and base application structure
Authentication: client login, team member login, invitation flow
Team member management: invite, role assignment, deactivation
Request submission: form, validation, attachment upload, status initialisation
Request status and assignment: status transitions, developer assignment, client visibility
Comment thread: posting, internal flag, client-facing view
Request list views: client list, team list, basic status filtering

Each step builds on the last. Each step produces something testable before the next step begins. And each step delivers a piece of working software rather than a collection of half-built components.

Writing the Tickets

A build order is not yet a set of tickets. You still need to break each step into discrete pieces of work that a developer can pick up and complete in a day or two.

Here is how I would break down step four, request submission, into individual tickets.

Ticket: Request model and migration
Create the requests table migration with all columns from the ERD. Create the Request Eloquent model with the HasUlids trait, fillable columns, and the submitter and assignee relationships. Write a model factory for use in tests.

Ticket: Attachment model and migration
Create the attachments table migration. Create the Attachment model with its relationship back to Request. Configure the file storage driver. Write a model factory.

Ticket: Submit request endpoint
Create the StoreRequestRequest form request with validation rules and a payload() method. Create the StoreRequestPayload DTO. Create the SubmitRequest action. Create the StoreController. Wire up the route. Write feature tests covering successful submission, validation failures, and attachment handling.

Ticket: Request detail page
Create the Livewire component for the request detail view. Display title, description, status, assignee, and attachments. Scope the view so clients only see their own requests. Write feature tests covering client access and unauthorised access attempts.

Four tickets for one feature, each independently completable and testable. A developer picking up any one of these knows exactly what done looks like, because the acceptance criteria from the user stories map directly onto the test cases.

The Relationship Between Stories and Tickets

User stories describe what the system should do from a user's perspective. Tickets describe the technical work required to make that happen. They are not the same thing, and conflating them is a common source of confusion.

A single user story often maps to multiple tickets. The "submit a request" story from article three maps to at least the four tickets above. That is fine. The story is the goal. The tickets are the path.

When you write a ticket, you should be able to point to the user story it is serving. If a ticket cannot be connected to a user story, ask whether it needs to exist. Infrastructure work (setting up CI, configuring deployment, writing base test helpers) is an exception, but application feature work should always be traceable back to a user need.

Checking the Plan Against the ERD

Before you start building, do one final check. Go back to your ERD and make sure every entity and every relationship has a corresponding ticket.

In the Clarity plan, let me verify:

Organisation: covered in the authentication step
User: covered in authentication and team member management
Request: covered in request submission
Comment: covered in the comment thread step
Attachment: covered in request submission
All relationships: each foreign key maps to a ticket that creates the parent entity before the child entity

If any entity in your ERD does not have a corresponding ticket, you have a gap. Either you have forgotten something, or that entity is not actually needed for the current scope. Either way, better to find that now than two weeks into the build.

The Plan as a Living Document

A build plan is not a contract. Requirements change, technical discoveries shift priorities, and features that seemed simple turn out to be more complex than they appeared. A good plan is one that absorbs those changes without falling apart.

The way you make a plan resilient is by keeping the dependencies clear. If you know that request status depends on request submission, and request submission depends on authentication, then when authentication takes longer than expected you can immediately see what is blocked and communicate that clearly. You are not surprised. You are just updating the schedule with an accurate picture of what is affected.

That kind of clarity is what teams rely on mid-level developers to provide. Not perfect predictions, but an accurate, up-to-date map of where the work stands and what it connects to.

Putting It Into Practice

Take the project you have been working with throughout this series. Map the dependencies between your shaped features. Write a build order. Then break the first two steps into individual tickets.

For each ticket, make sure you can answer these questions: what does done look like? What does it depend on? Which user story does it serve?

If any of those questions is hard to answer, the ticket needs more work before anyone picks it up.

In the final article, we are going to step back from Clarity and talk about what this entire process represents: the shift in thinking that defines a mid-level developer, and where to take these skills from here.

Thinking In Layers

Steve McDougall — Tue, 19 May 2026 12:00:32 +0000

Ask a junior developer where a piece of logic should live and you will usually get one of two answers: the controller, or the model. Ask a mid-level developer the same question and they will ask you a question back: what kind of logic is it?

That distinction is the heart of this article.

Separation of concerns is one of those principles you hear about early in your career and nod along to without fully internalising what it means in practice. It sounds obvious. Of course different concerns should be separated. But when you are staring at a controller that has grown to three hundred lines and you are not sure how it got there, the theory suddenly feels less clear than it did.

In this article we are going to look at what separation of concerns actually means inside a Laravel application, why fat controllers are a symptom of an architectural problem rather than a code quality problem, and how thinking in layers changes the way you make decisions about where code should live.

What a Layer Actually Is

A layer is a group of code that has a single, well-defined job. Code inside a layer should only do that job. When it needs to do something outside that job, it should hand off to a different layer rather than doing the work itself.

In a Laravel application, the layers I work with look like this.

The HTTP layer handles everything related to the incoming request and the outgoing response. Controllers, middleware, form requests, and responses live here. This layer's job is to receive input, validate it, hand it to the business layer, and return a response. It does not make business decisions. It does not query the database directly.

The business layer contains the logic that makes your application do what it is supposed to do. Actions, services, and domain objects live here. This layer does not know anything about HTTP. It receives data, applies rules, and returns results. It can talk to the data layer to read or write records.

The data layer handles persistence. Models, query builders, and repository classes live here. This layer knows how to find, create, update, and delete records. It does not apply business rules. It does not know about HTTP.

Three layers. Three jobs. Each one knowing about its own responsibilities and nothing else.

Why Fat Controllers Happen

A fat controller is not a discipline problem. It is an architectural vacuum.

When a team does not have a clear shared understanding of what belongs where, logic accumulates in the most obvious place. Controllers are obvious. They are where the request arrives, so they are where people start writing code. And once code is there, more code gets added next to it because it is easier to extend an existing file than to create a new one.

Before long you have a controller that validates input, queries the database, sends emails, dispatches jobs, formats responses, and handles error cases. It has absorbed everything because nothing had a clear home.

The fix is not to refactor the controller. It is to give every kind of logic a home so that developers always know where to put new code.

Applying Layers to Clarity

Let me walk through a concrete example using Clarity's request submission feature.

A client submits a new request. Here is what needs to happen:

Validate the input (title required, description required, attachments optional)
Create the request record associated with the client's organisation
Store any uploaded attachments
Set the initial status to "submitted"
Return a response confirming the submission

Without layers, all of that logic tends to end up in the controller. Here is what that looks like, and why it is a problem:

// The kind of controller you want to avoid
public function store(Request $request): JsonResponse
{
    $validated = $request->validate([
        'title' => ['required', 'string', 'max:255'],
        'description' => ['required', 'string'],
        'attachments.*' => ['nullable', 'file', 'max:10240'],
    ]);

    $projectRequest = ProjectRequest::create([
        'organisation_id' => auth()->user()->organisation_id,
        'submitted_by' => auth()->id(),
        'title' => $validated['title'],
        'description' => $validated['description'],
        'status' => 'submitted',
    ]);

    if ($request->hasFile('attachments')) {
        foreach ($request->file('attachments') as $file) {
            $path = $file->store('attachments');
            $projectRequest->attachments()->create([
                'user_id' => auth()->id(),
                'filename' => $file->getClientOriginalName(),
                'path' => $path,
                'mime_type' => $file->getMimeType(),
            ]);
        }
    }

    return response()->json(['data' => $projectRequest->load('attachments')], 201);
}

This is not terrible code. It works. But it is doing too many jobs at once. It is validating, creating records, handling file storage, and formatting a response, all in the same method. Testing it in isolation is difficult because it is deeply coupled to the HTTP request object. Reusing any of this logic (say, if requests could also be submitted via an import job) means duplicating it or extracting it under pressure.

Now here is the same feature with layers applied:

// The Form Request handles validation
class StoreRequestRequest extends FormRequest
{
    public function rules(): array
    {
        return [
            'title' => ['required', 'string', 'max:255'],
            'description' => ['required', 'string'],
            'attachments.*' => ['nullable', 'file', 'max:10240'],
        ];
    }

    public function payload(): StoreRequestPayload
    {
        return new StoreRequestPayload(
            organisationId: auth()->user()->organisation_id,
            submittedBy: auth()->id(),
            title: $this->input('title'),
            description: $this->input('description'),
            attachments: $this->file('attachments', []),
        );
    }
}

// The Action handles the business logic
final readonly class SubmitRequest
{
    public function execute(StoreRequestPayload $payload): ProjectRequest
    {
        $projectRequest = ProjectRequest::create([
            'organisation_id' => $payload->organisationId,
            'submitted_by' => $payload->submittedBy,
            'title' => $payload->title,
            'description' => $payload->description,
            'status' => 'submitted',
        ]);

        foreach ($payload->attachments as $file) {
            $path = $file->store('attachments');
            $projectRequest->attachments()->create([
                'user_id' => $payload->submittedBy,
                'filename' => $file->getClientOriginalName(),
                'path' => $path,
                'mime_type' => $file->getMimeType(),
            ]);
        }

        return $projectRequest;
    }
}

// The Controller handles HTTP in and HTTP out
final readonly class StoreController
{
    public function __construct(
        private SubmitRequest $submitRequest,
    ) {}

    public function __invoke(StoreRequestRequest $request): JsonResponse
    {
        $projectRequest = $this->submitRequest->execute(
            payload: $request->payload(),
        );

        return response()->json(
            ['data' => $projectRequest->load('attachments')],
            201,
        );
    }
}

The controller is now four lines of meaningful logic. It receives a validated payload, calls an action, and returns a response. It knows nothing about how the request is created or how attachments are stored. Those are the action's job.

The action knows nothing about HTTP. It receives a payload object and does the work. You could call it from a console command, a queued job, or a test, and it would behave identically each time.

Where the Model Fits In

You will notice the model does not appear much in the code above beyond ProjectRequest::create() and the attachments() relationship. That is intentional.

Models in a layered application are responsible for representing a database record and its relationships. They are not responsible for business rules, validation, or application logic. A model that has methods like submitAndNotifyClient() or assignToAvailableDeveloper() is doing the action's job, and it will become harder to test and maintain as that logic grows.

Keep models focused. They know about their table, their columns, their relationships, and their casts. Everything else belongs in a layer above them.

This Is Not Dogma

I want to be clear that layers are a tool, not a religion. A simple CRUD endpoint that reads a record and returns it does not need an action class. Adding indirection where none is needed creates noise without creating value.

The question to ask is: is this logic complex enough, or reusable enough, that it deserves its own home? If the answer is yes, extract it. If the answer is no, keep it in the controller and move on.

Mid-level developers learn to make that call. Juniors often apply patterns uniformly regardless of context, which leads to over-engineering simple things. The goal is judgment, not rule-following.

Putting It Into Practice

Take a controller from a project you have worked on and look at it honestly. How many jobs is it doing? Can you identify which lines belong in the HTTP layer, which belong in the business layer, and which belong in the data layer?

You do not need to refactor it right now. Just practice the act of categorising what you see. That categorisation instinct is what you are building, and it comes from practice more than from reading.

In the next article, we are going to bring everything together and look at how to turn your ERD and architecture diagram into a sequenced build plan that a developer can actually follow.

Introduction To Systems Architecture

Steve McDougall — Tue, 19 May 2026 12:00:30 +0000

We have a clear problem definition, a set of shaped features, and a data model we trust. At this point, a lot of developers would consider the design work done and start writing code. And honestly, for a project the size of Clarity, you probably could. The application is small enough that its structure is mostly implied by the framework.

But this series is about building the habits that carry you through larger, more complex projects. And on those projects, skipping the architecture diagram is where things start to quietly go wrong.

In this article I want to introduce you to what architecture actually means for application developers, and show you how to draw a simple system diagram for Clarity that captures how the pieces fit together.

What Architecture Means at This Level

When most developers hear "architecture", they think about large distributed systems, microservices, cloud infrastructure diagrams with dozens of boxes and arrows going everywhere. That is one kind of architecture, and it is not what we are talking about here.

For application developers, architecture is about a simpler set of questions. What are the major components of this system? How does data flow between them? What are the boundaries between different concerns? Where do external dependencies plug in?

You do not need to be designing a distributed system to benefit from answering those questions. Even a straightforward Laravel application has meaningful architecture: a web layer that handles HTTP, a business logic layer that does the actual work, a data layer that talks to the database, and often a set of external integrations sitting alongside all of that. Understanding where those layers are and how they connect is what lets you make good decisions about where code should live.

Components vs Layers

There are two ways to think about application structure, and both are useful in different contexts.

Layers describe a vertical slice through your application. Think of the classic presentation layer, business logic layer, data access layer split. Data comes in at the top, passes through the layers, and comes out as a response. Each layer only talks to the layer directly below it. This is a useful mental model for thinking about separation of concerns inside a single application.

Components describe horizontal groupings of related functionality. Authentication is a component. The request management system is a component. Notifications are a component. A component might span multiple layers internally, but it has a clear boundary and a clear responsibility.

In practice, most applications use both mental models at once. The layers tell you how code flows inside a component. The components tell you how the system is divided at a higher level.

Drawing a System Diagram

A system diagram does not need to be elaborate. Its job is to show the major components of your system, how they connect, and where external dependencies sit. You are not trying to document every class or every database query. You are drawing a map that helps you and your team understand the shape of what you are building.

Here is a Mermaid diagram for Clarity:

flowchart TD
    Browser["Browser / Client"]

    subgraph App ["Clarity Application"]
        Web["Web Layer\n(Routes, Controllers, Middleware)"]
        Auth["Auth Component\n(Login, Invitation, Sessions)"]
        Requests["Request Management\n(Submit, Status, Assignment)"]
        Comments["Comments\n(Post, Internal Flag)"]
        Attachments["Attachments\n(Upload, Storage)"]
        Notifications["Notifications\n(Status Changes, Comments)"]
    end

    subgraph Data ["Data Layer"]
        DB[("PostgreSQL")]
        Storage["File Storage"]
        Cache["Cache"]
    end

    Browser --> Web
    Web --> Auth
    Web --> Requests
    Web --> Comments
    Web --> Attachments
    Requests --> Notifications
    Comments --> Notifications
    Auth --> DB
    Requests --> DB
    Comments --> DB
    Attachments --> DB
    Attachments --> Storage
    Auth --> Cache

This is not a detailed technical specification. It is a conversation starter. It shows that Clarity has a web layer handling incoming requests, five functional components sitting behind it, a database and file storage for persistence, a cache layer, and a notifications pathway that gets triggered by changes in the request and comment components.

What the Diagram Reveals

Even a simple diagram like this surfaces useful questions.

The notifications component appears as a box but is currently undefined. What does it actually do? Does it send emails? Does it push in-app notifications? Does it use a queue? That is a decision we have deferred, and the diagram makes that deferral visible. For the initial version of Clarity, we scoped email notifications on comments out of the first cycle. The component box is still there, which means when we come back to build it, we have a clear place for it to sit.

The file storage box is separate from the database. That is intentional. Attachments are stored on disk or in an object store, not as blobs in the database. The diagram captures that decision explicitly. A developer joining the project later can see at a glance that attachments have their own storage concern, rather than discovering it buried in a model.

The cache layer connects only to the auth component in this version. That is a starting point, not a permanent constraint. As Clarity grows and request list queries become more expensive, caching will expand to cover other components. Having it on the diagram from the start means that growth is natural rather than bolted on.

Architecture as a Communication Tool

One of the things I value most about architecture diagrams is that they create a shared vocabulary for a team. When everyone can point at the same diagram and say "the request management component" or "the web layer", discussions become sharper. You spend less time talking past each other and more time talking about the actual problem.

That shared vocabulary is especially valuable when something goes wrong. If a bug is affecting comments but not requests, a team with a clear component diagram can focus their investigation quickly. If performance is degrading under load, having the data flow documented means you can reason about where the bottleneck is likely to be.

This is one of the reasons mid-level developers tend to be better debugging partners than juniors, even when the junior has been on the codebase longer. It is not that they know more code. It is that they think in components and flows rather than individual files and functions. The architecture diagram is how you start building that mental model.

Clarity's Architecture in Plain Language

Let me describe the Clarity architecture in prose, the way you might explain it to a new team member.

Clarity is a single Laravel application served over HTTP. All incoming requests pass through the web layer, which handles routing, authentication middleware, and request validation. Behind the web layer, the application is divided into four main functional areas: request management, comments, attachments, and authentication.

Request management is the core of the application. It covers the full lifecycle of a client request from submission through completion, including status transitions and developer assignment. Comments sit alongside request management and share the same request context, with the addition of the internal flag that controls client visibility. Attachments handle file uploads and connect to external file storage rather than the database.

Authentication covers client login via password, team member login, and the invitation flow. Session state is cached to reduce database load on authenticated requests.

Notifications are triggered by events in the request and comment components. In the first version of Clarity, notifications are out of scope. The component is acknowledged in the architecture but not built yet.

Data persistence uses PostgreSQL for relational data and a file storage service for attachments. The application does not use a search index or a message queue in the initial version.

Putting It Into Practice

Draw a system diagram for your own project using the same approach. Start with the major components you can identify, then add the data layer and any external dependencies. Draw arrows to show how data flows between them.

Then write a plain-language description of the architecture the way I did above. If you struggle to write it in a few clear paragraphs, the diagram probably needs more work. The prose and the diagram should tell the same story.

In the next article, we are going to look at separation of concerns in more detail, understand why the "fat controller" problem is really an architectural symptom, and start thinking about what belongs in each layer of a Laravel application.

Relationships, Cardinality, and the Questions Your Schema Is Asking

Steve McDougall — Tue, 19 May 2026 11:59:58 +0000

In the last article we drew the Clarity ERD and ended up with a clean diagram covering five entities and seven relationships. If you followed along and drew one for your own project, you probably found a few things that surprised you. That is normal, and it is exactly the point.

Now I want to go deeper. Drawing an ERD is one skill. Reading what it is telling you is another, and the second one is where the real value lives.

In this article we are going to look at the three relationship types in detail, walk through the most common mistakes I see developers make when modelling data, and show you how to catch them at the diagram stage before they become painful migrations.

The Three Relationships, Properly

We covered these briefly in the last article, but they deserve more attention.

One-to-One

A one-to-one relationship means one record in table A maps to exactly one record in table B, and that mapping is unique on both sides.

These are less common than people expect. When a developer reaches for a one-to-one, I always ask: why is this data in a separate table? Sometimes there is a good reason. You might have a users table and a user_profiles table where the profile data is large, infrequently accessed, and cleaner to separate. Or you might have a base users table that is extended by either a client_profiles table or a team_member_profiles table depending on role.

But a lot of the time, a one-to-one relationship is a sign that the data should just live in the same table. Before you commit to one, ask yourself whether there is a genuine reason for the separation or whether you are adding complexity without adding value.

In Clarity, we do not have any one-to-one relationships. The model is clean enough that everything fits in its own entity without needing auxiliary tables.

One-to-Many

This is the workhorse of relational data modelling. One record in table A is referenced by many records in table B. The foreign key lives on the "many" side.

In Clarity: one organisation has many users, so organisation_id lives on the users table. One request has many comments, so request_id lives on the comments table. The pattern is consistent.

The mistake I see most often with one-to-many is putting the foreign key on the wrong side. If you put user_ids (as some kind of serialised array) on the organisations table instead of organisation_id on the users table, you have inverted the relationship and created a mess. You cannot join efficiently, you cannot enforce referential integrity, and you will hit a wall the moment you need to query it properly.

The rule is simple: the foreign key always goes on the child. The "many" side. If you are unsure which side is the child, ask yourself which record is owned by the other. A user is owned by an organisation. A comment is owned by a request. The owned record holds the foreign key.

Many-to-Many

A many-to-many relationship means records on both sides can be connected to multiple records on the other side. You cannot model this directly with a foreign key on either table. You need a pivot table that sits between them and holds the connection.

Clarity does not have a many-to-many in the current design, so let me add one to illustrate the point. Suppose we wanted to add tagging to requests, where a request can have many tags and a tag can be applied to many requests. That is a classic many-to-many.

The entities involved:

Request {
    uuid id
    string title
    ...
}

Tag {
    uuid id
    string name
    string colour
}

RequestTag {
    uuid request_id
    uuid tag_id
}

The RequestTag pivot table is the relationship. It holds nothing but the two foreign keys (and sometimes additional data about the relationship itself, like a created_at timestamp or a user who applied the tag).

In Laravel, this maps to a belongsToMany relationship on both models:

// Request model
public function tags(): BelongsToMany
{
    return $this->belongsToMany(Tag::class, 'request_tags');
}

// Tag model
public function requests(): BelongsToMany
{
    return $this->belongsToMany(Request::class, 'request_tags');
}

The common mistake here is not recognising when you have a many-to-many. Developers often start by modelling it as a one-to-many and then discover mid-build that the constraint they assumed does not hold. When you spot a noun in your application that sounds like it could belong to many different records of another type, treat it as a signal to check whether you are looking at a pivot.

Common ERD Mistakes

Let me walk through the mistakes I see most often and how to spot them before they cause problems.

Storing arrays in a column

If you ever find yourself writing tags: string or assigned_to: json on an entity, stop. That is almost always a sign that the data belongs in a related table. Arrays in columns cannot be indexed properly, cannot be joined against, and are a maintenance headache the moment the data inside them grows or needs to be queried individually.

In the Clarity ERD, assigned_to is a single foreign key pointing at one user. That is correct because our business rule says a request has one assignee. But if the requirement had been "a request can be assigned to multiple developers", the right answer would be an assignments pivot table, not a JSON array of user IDs in a column.

The missing pivot

Related to the above: when you draw a many-to-many relationship between two entities without drawing the pivot table, you have an incomplete diagram. Always draw the pivot explicitly. It forces you to think about what data the relationship itself carries, and it makes the migration obvious when you get to that stage.

Nullable foreign keys as a shortcut

It is tempting to make a foreign key nullable when you are not sure whether a relationship will always exist. Sometimes that is correct. In Clarity, assigned_to on Request is nullable because a request might not have an assignee yet. That is a real business rule.

But sometimes a nullable foreign key is a sign that the relationship is modelled incorrectly. If you find yourself with a record that should always belong to a parent but the foreign key keeps being null in practice, the relationship direction might be wrong, or the data might belong in a different table entirely.

Conflating user roles with user types

This one is specific to applications like Clarity, but it comes up constantly. When your system has multiple types of users (clients and team members, customers and staff, students and teachers), there is a temptation to use a single role column and call it done.

Sometimes that is fine. But if the two user types have genuinely different data requirements, different relationships to other entities, or different constraints on what they can do, a single role column will not hold the weight. You end up with columns that are only relevant to one type of user, nullable columns everywhere, and logic scattered across your codebase to handle the differences.

In the Clarity design I chose a single users table with a role column and a nullable sub_role. That works for our use case because the data requirements for clients and team members are similar enough. But it is a decision worth examining on your own projects. If the profiles for your two user types are genuinely different shapes, a polymorphic users table or a base users table with separate profile tables might serve you better.

Revisiting the Clarity ERD

Now that we have covered these in detail, let me take one more look at the Clarity diagram and point out the decisions that are worth noting.

The Request entity has two foreign keys pointing at User: submitted_by and assigned_to. This is intentional, but it means the Eloquent relationships on Request need to be named explicitly to avoid ambiguity:

public function submitter(): BelongsTo
{
    return $this->belongsTo(User::class, 'submitted_by');
}

public function assignee(): BelongsTo
{
    return $this->belongsTo(User::class, 'assigned_to');
}

If you wrote $this->belongsTo(User::class) without the second argument, Laravel would look for a user_id column that does not exist. Naming the foreign key explicitly in the relationship definition is the correct approach here, and the ERD is what made this obvious before we wrote a single line of code.

The Comment entity has is_internal as a boolean. This is a simple field, but it carries real access control logic: when is_internal is true, the comment must be excluded from any query that is serving data to a client user. That is an application-layer concern rather than a schema concern, but spotting it on the diagram is a reminder to handle it consistently across every query that touches comments.

Putting It Into Practice

Go back to the ERD you drew in the last exercise. Now look at every relationship line and ask these questions for each one:

Is the foreign key on the correct side?
Is this truly a one-to-many, or could it become a many-to-many as the application grows?
Are there any arrays or JSON fields that should be a related table?
Are there any nullable foreign keys that feel like shortcuts rather than genuine business rules?

Fix what you find. A diagram is cheap to change. A migration is not.

In the next article, we are going to step back from the data model and look at the bigger picture: what application architecture actually means for backend developers, and how to draw a simple system diagram that shows how the pieces of Clarity fit together.

Your First ERD

Steve McDougall — Tue, 19 May 2026 11:59:56 +0000

Up until now, everything we have done has been about understanding the problem. We interrogated the brief, surfaced the assumptions, wrote user stories, and shaped the features into bounded pieces of work. That is a lot of thinking before touching anything technical, and it is exactly the right order to do things in.

Now we get to use that thinking. Because once you know what your application needs to do, the next question is: what does it need to remember?

That question is what an Entity Relationship Diagram is designed to answer.

What an ERD Actually Is

An ERD is a visual map of the data your application works with. It shows you the things your system needs to store (entities), the properties those things have (attributes), and the connections between them (relationships).

Before you write a single migration, before you think about table names or column types, drawing an ERD gives you a bird's-eye view of your entire data model. It lets you spot problems, ask questions, and make decisions on paper, where changing your mind costs nothing.

I have seen developers skip this step and pay for it later. A misunderstood relationship between two entities can mean a painful migration weeks into a build, or worse, a data model that quietly produces wrong results and nobody notices until a client reports it. Fifteen minutes with a pencil and a blank page is a much cheaper way to find those problems.

The Building Blocks

Every ERD is made of three things.

Entities are the nouns in your system. The things your application tracks and stores. In Clarity, the entities we can already see from our user stories are: organisations, users, requests, comments, and attachments.

Attributes are the properties of each entity. A user has a name, an email address, and a role. A request has a title, a description, and a status. Attributes map directly to the columns you will eventually write in your migrations.

Relationships are the connections between entities. An organisation has many users. A user can submit many requests. A request can have many comments. These connections are what give your data model its shape, and getting them right is the most important part of the exercise.

Cardinality

When you draw a relationship between two entities, you need to describe how many of one thing can be connected to how many of another. This is called cardinality, and there are three basic types.

One-to-one. One record in table A corresponds to exactly one record in table B. These are relatively rare. An example might be a user having one profile, where the profile data lives in a separate table.

One-to-many. One record in table A corresponds to many records in table B. This is the most common relationship in most applications. One organisation has many users. One user has many requests. One request has many comments.

Many-to-many. Many records in table A can be connected to many records in table B. This always requires a pivot table. An example in Clarity might be if we allowed a request to be tagged, where a request can have many tags and a tag can belong to many requests.

Getting cardinality wrong is the most expensive ERD mistake. If you model a one-to-many relationship as a one-to-one, you will hit a wall the moment a second record tries to attach itself somewhere it cannot go. Drawing it out first makes these mistakes obvious before they are baked into your schema.

Drawing the Clarity ERD

Let me walk through how I would build the Clarity ERD from our user stories and shaped features.

I start by listing every entity I can see:

Organisation
User
Request
Comment
Attachment

Then for each entity, I list its attributes. I am not worrying about data types yet, just the fields that need to exist.

Organisation: id, name, created_at

User: id, organisation_id, name, email, password, role (client or team_member), sub_role (developer or admin, nullable), invited_at, created_at

Request: id, organisation_id, submitted_by (user_id), assigned_to (user_id, nullable), title, description, status, created_at, updated_at

Comment: id, request_id, user_id, body, is_internal, created_at

Attachment: id, request_id, user_id, filename, path, mime_type, created_at

Now the relationships:

An Organisation has many Users
An Organisation has many Requests
A User (client) submits many Requests
A User (developer) is assigned to many Requests
A Request has many Comments
A Request has many Attachments
A User posts many Comments

In Mermaid syntax, which I would recommend learning because it lets you write diagrams as code and store them in version control alongside your project, this looks like:

erDiagram
    Organisation {
        uuid id
        string name
        timestamp created_at
    }

    User {
        uuid id
        uuid organisation_id
        string name
        string email
        string role
        string sub_role
        timestamp invited_at
        timestamp created_at
    }

    Request {
        uuid id
        uuid organisation_id
        uuid submitted_by
        uuid assigned_to
        string title
        text description
        string status
        timestamp created_at
        timestamp updated_at
    }

    Comment {
        uuid id
        uuid request_id
        uuid user_id
        text body
        boolean is_internal
        timestamp created_at
    }

    Attachment {
        uuid id
        uuid request_id
        uuid user_id
        string filename
        string path
        string mime_type
        timestamp created_at
    }

    Organisation ||--o{ User : "has many"
    Organisation ||--o{ Request : "has many"
    User ||--o{ Request : "submits"
    User ||--o{ Comment : "posts"
    Request ||--o{ Comment : "has many"
    Request ||--o{ Attachment : "has many"

Render that in any Mermaid viewer and you get a complete picture of the Clarity data model. Every entity, every attribute, every relationship, on a single page.

Reading the Diagram

The notation on the relationship lines is worth understanding. In Mermaid ERDs, each side of a relationship is described with two symbols: one for the minimum cardinality and one for the maximum.

|| means exactly one. o{ means zero or more. So ||--o{ reads as: exactly one on the left, zero or more on the right.

Put together, Organisation ||--o{ User reads as: one organisation has zero or more users. An organisation can exist with no users yet (useful when you first create it), but every user belongs to exactly one organisation.

What the ERD Is Telling You

The real value of drawing this out is what you notice when you step back and look at it.

I can already see a potential question in the Clarity diagram. The Request entity has two foreign keys pointing at User: submitted_by and assigned_to. That is fine and intentional, but it means when you build the Eloquent relationships on the Request model, you will need named relationships rather than a single belongsTo. Something like submitter() and assignee() rather than just user(). That is a small thing, but it is much better to notice it here than halfway through writing a controller.

I can also see that Comment and Attachment both have a user_id. That means both clients and team members can post comments and add attachments, which matches our user stories. If the stories said only team members could add attachments, that user_id column would need a constraint we would need to enforce at the application layer. The diagram surfaces that decision.

This is what ERDs are actually for. Not documentation. Not formality. They are a thinking tool that forces you to look at your data model as a whole before you start building pieces of it in isolation.

Putting It Into Practice

Take the project from the previous exercises and draw an ERD for it. Start with just the entities and relationships, then add attributes once the structure feels right.

Use Mermaid if you want to keep it in code, or draw.io if you prefer a visual tool. The format matters less than the act of drawing it out and looking at what it tells you.

Pay particular attention to your foreign keys. For every relationship line you draw, ask yourself: does this direction make sense? What happens if the parent record is deleted? Is there anything here that I assumed was a one-to-many that might actually be a many-to-many?

In the next article, we are going to go deeper on relationships and cardinality, look at some of the most common ERD mistakes, and talk about how to catch the wrong relationship on paper before it becomes the wrong migration in production.

Shaping Before You Build

Steve McDougall — Tue, 19 May 2026 11:59:24 +0000

We now have a solid set of user stories for Clarity. We know who the actors are, what they need to do, and what done looks like for each feature. That is real progress. But there is a gap between a well-written user story and something a developer can confidently pick up and build within a reasonable timeframe.

That gap is what shaping is designed to close.

Shaping is a concept from the Shape Up methodology, written by Ryan Singer at Basecamp. If you have not read it, I would strongly recommend it. It is free at basecamp.com/shapeup, and it is one of the most practical pieces of writing on software product development I have come across. This article is not a replacement for it, but it will introduce you to the core ideas and show you how to apply them to Clarity.

The Problem Shaping Solves

User stories are great for describing what a user needs. They are not great at describing how much work that need represents, or how to build it in a way that is actually feasible within a given timeframe.

Without shaping, a story like "as a client, I want to add a comment to my request" can balloon into a real-time threaded messaging system with emoji reactions and read receipts, or it can be a simple text box that posts to a list. Both satisfy the story. One takes two days to build, the other takes two months.

Shaping forces you to make that decision deliberately, before anyone writes a line of code. It gives features a specific form: a defined scope, a considered approach, and an explicit boundary around what is included and what is not.

The Three Elements of a Shaped Feature

Every shaped feature has three components.

The first is appetite. This is the amount of time you are willing to spend on the feature, decided upfront. Not an estimate of how long it will take, but a deliberate decision about how much it is worth. This is one of the most powerful ideas in Shape Up, and it inverts the normal way teams think about time. Instead of estimating a feature and then planning around that estimate, you decide how much time a feature deserves and then shape the work to fit inside that boundary.

The second is the solution. This is a rough sketch of how the feature will work, at a level of detail that is enough to build from without being so prescriptive that it removes all creative problem-solving from the developer. Shape Up calls these "fat marker sketches" because the point is to communicate structure and flow, not pixel-perfect detail.

The third is the boundaries. This is an explicit list of what is not included. Boundaries are as important as the solution itself, because they are what prevent scope from quietly expanding during the build. If you do not write down what is out of scope, someone will assume it is in scope.

Writing a Pitch

The output of shaping is called a pitch. A pitch is a short document that captures all three elements and makes the case for why the feature is worth building in this cycle.

A pitch is not a specification. It does not tell developers exactly how to implement something. It tells them what problem they are solving, roughly how it should work, how much time they have, and what the edges of the work are.

Let me write a pitch for one of the Clarity features.

Pitch: Request Comments

Appetite: Two days

Problem: Clients and team members currently have no way to communicate directly on a specific request within Clarity. Context gets lost in email threads, and there is no record of decisions or questions attached to the work itself.

Solution: A simple comment thread on each request detail page. Any user with access to the request can post a comment. Team members can mark a comment as internal, which hides it from clients. Comments appear in chronological order. No threading, no reactions, no editing after posting in the first version.

Rough sketch:

Request detail page
---------------------
[ Request title ]
[ Status badge ] [ Assigned to: Sarah ]
[ Description ]

Comments
---------
[ Client User ] 14 May
Can you confirm the deadline for this?

[ Developer ] 15 May  [internal]
Need to check with the PM before responding.

[ Text area: Add a comment... ]
[ Internal? checkbox ] [ Post comment ]

Out of scope:

Threaded replies
Editing or deleting comments
Emoji reactions or mentions
Email notifications on new comments (deferred to a later cycle)
File attachments on comments

Look at what that pitch gives you. A developer picking this up knows exactly what they are building, roughly how it should look and behave, how long they have to build it, and where the edges of the work are. They are not going to spend a day building a notification system because they assumed it was included. They are not going to build a threaded reply UI because no one said not to.

That clarity (again, no pun intended) is what makes teams fast. Not velocity metrics, not sprint ceremonies. Clear, bounded work.

Appetite as a Design Tool

I want to spend a moment on appetite specifically, because it is the idea most developers initially resist.

The instinct when you hear "two days for a comment system" is to think about all the things a comment system could be and conclude that two days is not enough. But that framing is backwards. The appetite is not a constraint on what you could build. It is a statement about what the problem is worth solving right now.

A comment thread that works and ships in two days is more valuable than a fully-featured messaging system that takes six weeks and delays everything else. You can always come back and add threading, notifications, and mentions in a later cycle if the basic version proves its value. What you cannot do is un-spend six weeks.

This is one of the most important mental shifts in moving from junior to mid-level. Juniors often think about features in terms of what they could be. Mid-level developers think about features in terms of what they need to be, right now, to solve the problem in front of them.

Shaping the Clarity Features

Let me apply appetites to the full set of Clarity user stories, so we have a shaped backlog to build from as the series continues.

Client authentication and onboarding
Appetite: three days. Clients are invited by an admin, set a password via an invitation link, and log in. No social auth, no self-registration.

Submitting a request
Appetite: two days. Title, description, and optional file attachments. Status set to "submitted" on creation.

Request status and assignment
Appetite: two days. Team members can update status and assign a developer. Status and assignee are visible to clients. No real-time updates in the first version; a page refresh is acceptable.

Comment thread
Appetite: two days. As pitched above.

Team member management
Appetite: one day. Admins can invite team members by email, set their role, and deactivate their account. Invitations expire after 48 hours.

Request list views
Appetite: one day. Clients see a list of their own requests. Team members see all requests with basic filtering by status.

That is the full Clarity application shaped into six discrete pieces of work, with a total appetite of twelve days. That is not an estimate of how long it will take. It is a decision about how much time the initial version of Clarity is worth. If any piece of work is running over its appetite, the right question is not "how do we go faster?" but "what can we remove from this piece to fit inside the time we agreed it was worth?"

Putting It Into Practice

Take one of the user stories you wrote in the last exercise and write a pitch for it. Define an appetite, sketch a rough solution, and write out the out of scope list.

The out of scope list is the most important part. Be honest about what you are tempted to include, and then deliberately leave it out.

In the next article, we are going to move from features into data, and look at how to draw your first Entity Relationship Diagram before you write a single migration.

Writing Features Not Tasks

Steve McDougall — Tue, 19 May 2026 11:59:22 +0000

If you have ever looked at a ticket in your backlog and felt genuinely unsure where to start, there is a good chance the ticket was written as a task rather than a feature. It is one of the most common sources of confusion for junior developers, and it is almost never talked about directly.

The difference matters more than you might think. Tasks describe what to build. Features describe why it needs to exist and what it should enable. That distinction changes everything from how you estimate work, to how you test it, to how you know when you are actually done.

In this article we are going to look at what a properly written feature actually looks like, introduce the concept of user stories as a tool for capturing them, and apply all of it to Clarity using the confirmed assumptions we established in the last article.

Tasks vs Features

Let me show you the difference with a concrete example.

Here is a task:

Add a status column to the requests table.

Here is the same thing written as a feature:

As a client, I want to see the current status of my submitted request, so that I know whether the team has started working on it.

The task tells a developer to do something. The feature tells everyone involved why it matters, who benefits from it, and what outcome it is trying to produce.

That distinction has real consequences. If I hand you a task, you can complete it and technically be done. You can add the column, run the migration, and close the ticket. But you have not built anything a user can actually interact with. The feature, on the other hand, only counts as done when a client can log in, find their request, and read a meaningful status value. That is a fundamentally different definition of done.

The format I just used has a name. It is a user story.

What a User Story Actually Is

A user story follows a simple template:

As a [type of user], I want to [do something], so that [I achieve some goal].

Each part of that template is doing a specific job.

The actor ("as a client") anchors the story to a real person in your system with a real perspective. It forces you to think about who is actually going to use this thing, rather than thinking about it in the abstract.

The action ("I want to see the current status") describes the behaviour the system needs to support. It is written from the user's point of view, not the developer's. You will notice it says "see the status", not "query the status from the database". That is deliberate. Implementation details do not belong in a user story.

The goal ("so that I know whether the team has started working on it") is the part most people skip, and it is often the most valuable. The goal is what gives you a basis for questioning whether you are building the right thing. If you cannot articulate a meaningful goal for a feature, that is a signal worth paying attention to.

Acceptance Criteria

A user story on its own is not quite enough to build from. You also need acceptance criteria: a concrete list of conditions that must be true for the story to be considered complete.

Acceptance criteria answer the question: "how do we know this is done?"

Here is the status visibility story with acceptance criteria added:

Story: As a client, I want to see the current status of my submitted request, so that I know whether the team has started working on it.

Acceptance criteria:

The request detail page displays the current status
The status reflects one of the defined values: submitted, in review, in progress, on hold, completed
The status updates in real time when a team member changes it, without requiring a page refresh
The client cannot change the status themselves; the field is read-only for them

Now you have something you can actually build against. You have a clear definition of done, a set of testable conditions, and a user perspective that keeps you grounded in what actually matters.

Writing Stories for Clarity

Let us take the confirmed assumptions from the last article and turn them into a proper set of user stories. I am going to organise them by actor, because that is the most natural way to think about the scope of work.

Client stories

Submitting a request

As a client, I want to submit a project request with a title, description, and optional attachments, so that I can communicate what I need from the team.

Acceptance criteria:

The submission form requires a title and description
Attachments are optional and support common file types
After submission, the request status is set to "submitted" automatically
The client is redirected to the request detail page after a successful submission

Editing a request

As a client, I want to edit my request while it is in the submitted state, so that I can correct mistakes or add information before the team begins reviewing it.

Acceptance criteria:

Edit controls are visible only when the request is in the "submitted" state
Once the status moves past "submitted", the edit controls are hidden
Edits do not reset the request status

Tracking request status

As a client, I want to see the current status of my request and who it has been assigned to, so that I have visibility into where things stand without needing to chase the team.

Acceptance criteria:

The request detail page shows the current status and the assigned developer's name
If no developer has been assigned yet, a placeholder is shown rather than a blank field
Status changes are reflected without requiring a page refresh

Adding a comment

As a client, I want to add a comment to my request, so that I can ask questions or provide additional context as the work progresses.

Acceptance criteria:

Clients can post a comment on any request they own
Comments appear in chronological order
Internal comments marked by team members are not visible to clients

Team member stories

Reviewing and updating request status

As a team member, I want to update the status of a request, so that clients and colleagues have an accurate picture of where the work stands.

Acceptance criteria:

Team members can move a request to any valid status
Status changes are logged with a timestamp and the team member's name
The client is notified when the status changes

Assigning a request

As a team member, I want to assign a request to a developer, so that ownership is clear and the developer knows what they are responsible for.

Acceptance criteria:

Any team member can assign a request
Only one developer can be assigned at a time
Reassigning a request replaces the previous assignment rather than stacking them

Adding an internal comment

As a team member, I want to mark a comment as internal, so that I can communicate with colleagues about a request without the client seeing the discussion.

Acceptance criteria:

Internal comments are visually distinct in the team view
Internal comments are completely hidden in the client view
A team member can toggle the internal flag before submitting a comment

Admin stories

Managing team members

As an admin, I want to invite and manage team members, so that I can control who has access to the system and what role they hold.

Acceptance criteria:

Admins can invite users by email
Invitations expire after 48 hours if not accepted
Admins can change a team member's role or deactivate their account

What This Set of Stories Gives You

Look at what we have built here. From a single vague paragraph in a client brief, we now have a complete set of structured, testable, actor-anchored stories that describe the entire surface area of the Clarity application.

Every story has a clear definition of done. Every story is written from a user's perspective. And every story is independent enough that a developer could pick one up and work on it without needing to understand the whole system first.

That last point matters a lot when you are working in a team. Vague tasks create dependencies and confusion. Well-written stories create clarity (no pun intended) and autonomy.

Putting It Into Practice

Take the project from the last article's exercise and write three user stories from it. Pick stories from different actors if you can. For each story, write at least three acceptance criteria.

Then ask yourself honestly: could someone else on your team pick up one of those stories and know exactly what done looks like? If the answer is no, the story needs more work.

In the next article, we are going to move from user stories to feature shaping, and look at how the Shape Up methodology gives you a practical framework for deciding what to build and how much time it is worth.

Reading Between the Lines

Steve McDougall — Tue, 19 May 2026 11:58:50 +0000

In the last article, I asked you to take the Clarity brief and write down every question you would want answered before you started building. If you did that exercise, you probably found somewhere between five and fifteen questions depending on how deeply you read into it.

Here is what I have found over the years: the first time developers do that exercise, they mostly surface technical questions. Things like "should I use a polymorphic relationship?" or "what database should I use?". Those are not bad questions, but they are the wrong starting point. They are implementation questions dressed up as requirements questions, and they put the cart firmly in front of the horse.

The questions that actually matter before you write a line of code are business questions. And learning to ask them is one of the most valuable skills you can develop as you move towards mid-level.

The Brief, Revisited

Let us look at the Clarity brief again:

"We need a tool where our clients can submit project requests, and our team can manage and track them. Clients should be able to see the status of their requests, and we need to be able to assign them to developers."

On the surface, this looks like a reasonable starting point. You could probably sketch out a rough data model from it in ten minutes. But read it again, and this time treat every noun and every verb with suspicion.

Every noun is a potential entity. Every verb is a potential action. And every place where the brief is vague is a place where an unstated assumption is hiding.

Interrogating the Nouns

Let us pull out the nouns: clients, tool, project requests, team, status, developers.

These seem obvious until you start asking questions about them.

Clients. Are clients individual people, or organisations? Can a single organisation have multiple client users? If a client submits a request, can another person from the same organisation see it? This alone could mean the difference between a simple users table and a full organisations -> users relationship.

Project requests. What actually constitutes a request? Is it just a title and a description? Does it have attachments? Can it have a priority? Can a client submit multiple requests at the same time, and if so, are those requests independent or grouped somehow?

Team. Who is "our team"? Are these people with admin access to everything, or do different team members have different permissions? Can a developer only see requests assigned to them, or all requests?

Status. This one word is carrying an enormous amount of weight. Is "status" a simple label (pending, in progress, done) or is it a proper workflow with defined transitions? Can a client change the status, or only view it? Can a developer set any status, or only move it forward?

Developers. Are developers a separate user type from clients, or just users with a different role? Can a developer also be a client on a different project?

None of these are trick questions. They are the kind of thing a product manager or a client would answer in a thirty-minute call. But if you skip straight to building, you are making silent choices about all of them, and those choices will come back to cost you.

Interrogating the Verbs

Now the verbs: submit, manage, track, see, assign.

Submit. Can a client edit a request after submitting it? Can they delete it? Is there a draft state before submission, or is it submit-or-nothing?

Manage and track. These are vague by nature. What does managing a request look like? Adding notes? Updating status? Logging time? The brief does not say, which means this is a gap you need to close before you start.

See. Can clients only see the status, or can they see the full request detail and any notes added by the team? Is there a concept of private notes that clients should not see?

Assign. Can a request be assigned to multiple developers? What happens when the assigned developer is unavailable? Is assignment visible to the client?

The Questions Worth Asking

When I am working from a brief like this, I structure my questions into three categories.

The first is scope questions. These define the boundaries of what we are building. What is explicitly included? What is explicitly out of scope? For Clarity, that might be: are we building client authentication ourselves, or are clients invited via a link?

The second is actor questions. These define who can do what. For every type of user in the system, I want to know what actions they can take, what they can see, and what restrictions apply to them.

The third is data questions. These define the shape of the information we are working with. What does each entity look like? What are its required fields? What are its optional fields? What are the relationships between entities?

You do not need formal workshops or long documents to work through these. A simple shared notes document and a conversation with whoever owns the brief is often enough. The goal is not to write a specification novel. It is to surface the decisions that have already been made implicitly, and make them explicit before they become mistakes.

Applying This to Clarity

After running this process on the Clarity brief, here is what I would want confirmed before I drew a single diagram:

On actors:

There are two distinct user types: clients and team members
Clients belong to an organisation, and organisations can have multiple client users
Team members have a role of either developer or admin
Admins can manage everything; developers can manage requests assigned to them

On requests:

A request has a title, description, and optional file attachments
Requests are submitted by a client user and belong to their organisation
Requests move through a defined set of statuses: submitted, in review, in progress, on hold, completed
Only team members can change the status of a request
Clients can edit their request while it is in the submitted state; after that, it is read-only for them

On assignment:

A request can be assigned to one developer at a time
Assignment is visible to the client
Developers can see all requests, not just their own

On comments:

Both clients and team members can add comments to a request
Team members can mark a comment as internal, which hides it from clients

These are the confirmed assumptions we will carry forward through the rest of this series. Notice that none of them are technical decisions. We have not decided on a database, a framework, a caching strategy, or a queue driver. We have simply defined the shape of the problem we are solving.

That comes next.

Putting It Into Practice

Take a project you are currently working on, or one you have worked on recently. Go back to the original brief or requirements you were given. Now apply the noun-and-verb interrogation to it. How many questions can you surface that were never explicitly answered? How many of those questions did you answer yourself, silently, while you were building?

Write them down. You might be surprised how many decisions were made without anyone realising a decision was being made.

In the next article, we will take the confirmed Clarity assumptions and turn them into properly structured user stories, and explore what the difference between a task and a feature actually means in practice.

Stop Writing Code First

Steve McDougall — Tue, 19 May 2026 11:58:48 +0000

There is a habit almost every junior developer shares. A client sends over a brief, or a ticket lands in your queue, and within minutes your editor is open and your fingers are moving. It feels productive. It feels like progress.

It is almost always the wrong move.

This is the first article in a series called From Requirements to Reality, designed for developers who are ready to stop thinking like juniors and start thinking like mid-level engineers. Over the course of this series, we are going to work through a fictional product called Clarity, a client project management tool where clients submit requests and developers scope and track them. Every concept we explore will be applied to Clarity, so by the end you will have seen a complete design process play out from a vague brief all the way to an implementation plan.

But before we can do any of that, we need to talk about the most expensive habit in software development.

The Cost of Jumping Straight In

When you are junior, speed feels like the measure of your value. The faster you can translate a requirement into working code, the better you are doing. That instinct makes sense early on. You are learning by doing, and doing means writing code.

The problem is that this habit does not scale. As projects grow in complexity and your role in them grows with it, the cost of building the wrong thing becomes enormous. Refactoring a misunderstood feature three weeks after it was built is not just slower than getting it right the first time. It is often more expensive than the original build, because now you have tests to update, documentation to revise, and sometimes downstream code that relied on the wrong behaviour.

Mid-level developers do not move faster than juniors by typing more quickly. They move faster by spending time upfront that prevents expensive mistakes downstream.

What "Designing Before You Build" Actually Means

When I say design, I do not mean wireframes or Figma files (though those have their place). I mean asking a specific set of questions before a single migration, controller, or model gets created.

Those questions look something like this:

What problem is this feature actually solving?
Who is it for, and what do they need to be able to do?
What data does this feature create, read, update, or delete?
How does it connect to what already exists?
What does success look like, and how would we know if it had not worked?

These are not big questions. They do not require a week of planning or a product manager. They require maybe thirty minutes of thinking, a notepad, and the willingness to slow down before you speed up.

Introducing Clarity

Throughout this series we will apply every concept to Clarity. Here is the initial brief, written exactly the way a real client might send it:

"We need a tool where our clients can submit project requests, and our team can manage and track them. Clients should be able to see the status of their requests, and we need to be able to assign them to developers."

If you opened your editor right now, what would you build? A requests table? A users table? A status column? Maybe a polymorphic relationship between clients and developers?

All of those might end up being correct. But right now, you do not actually know enough to make those decisions well. There are at least a dozen unstated assumptions buried inside that brief. We have no idea whether "clients" and "developers" live in the same users table or separate ones. We do not know what "status" means: is it a free-text field, an enum, a workflow? We do not know if one request can be assigned to multiple developers, or only one. We do not know if clients can edit their requests after submission.

Every one of those unknowns is a fork in your schema. Pick the wrong path and you are doing a data migration at the worst possible time.

The Mindset Shift

The thing that separates a junior developer from a mid-level one is not the number of Laravel packages they have memorised or how quickly they can scaffold a resource. It is the ability to look at a requirement and ask "what do I not yet know?" before asking "how do I build this?"

This series is going to build that muscle systematically. We will cover:

How to read a client brief and extract what they actually need (not just what they said)
How to turn requirements into properly shaped features using user stories
How to draw an ERD before you write a migration
How to think about system architecture at the application level
How to turn all of that design work into a sequenced build plan

Each article will apply its concepts directly to Clarity, so you will see the thinking, not just the theory.

Putting It Into Practice

Before the next article, take the Clarity brief above and write down every question you would want answered before you started building. Do not try to answer them, just list them. How many can you find?

The number might surprise you.

In the next article, we will take that brief apart properly and look at how to extract the real requirements hiding inside it.

Introducing Signal: documentation that lives in your code

Steve McDougall — Thu, 30 Apr 2026 09:35:58 +0000

I have a confession. I have shipped more than a few projects where the documentation was a lie.

Not deliberately. Nobody sits down and thinks "I'll write docs that contradict my code." It happens gradually. You refactor a method, update the logic, rename a route, and the comment block at the top of the class quietly becomes fiction. The docs say one thing. The code does another. Whoever opens that file next, usually someone who isn't you, has to figure out which one to trust.

I got tired of that problem. So I built Signal.

Signal is a PHP library that turns PHP attributes into living documentation. You annotate your classes and methods directly in the source, and a single CLI command generates Markdown and JSON docs that always reflect what the code actually does. No separate documentation site to keep in sync. No wiki pages that rot. No README sections that nobody updates after the initial commit.

Why attributes?

PHP 8 gave us native attributes and, honestly, they remain underused. Most people know #[Route] from Symfony or #[Column] from Doctrine, but the mechanism itself is just a structured, machine-readable annotation system built into the language. That is exactly what documentation needs to be: structured and machine-readable, not a comment that any editor will happily let drift out of sync with reality.

The key difference with Signal is that attributes are not comments. PHP will parse them, your IDE understands them, and Signal can reflect on them at any point. If you delete a method, the attribute goes with it. If you rename a class, your tooling will tell you. The docs cannot lie because the docs are the code.

Installation and setup

Getting started is one line:

composer require juststeveking/signal

Then create a signal.json config at your project root. This tells Signal where to look and where to write:

{
    "input": "src/",
    "output": {
        "format": ["markdown", "json"],
        "path": "docs/"
    },
    "exclude": [
        "src/Attributes/"
    ]
}

The exclude array is useful for telling Signal to skip directories it does not need to reflect on. You almost certainly do not want Signal documenting its own attributes if you are using the library inside a package, and you may have internal bootstrap classes that should stay out of the generated output.

Once you have annotated your classes, run:

php vendor/bin/signal generate

Signal scans the input directory, reflects on every annotated class, and writes docs/signal.md and docs/signal.json. Both are safe to commit. Both can go into CI as required artefacts. If a developer removes an annotation, the next generate run will remove it from the docs automatically.

If you keep your config somewhere other than the project root, you can point to it explicitly:

php vendor/bin/signal generate --config=config/signal.json

The attribute system

Signal ships with 24 attributes split across three groups: class type attributes that identify what a class is, class metadata attributes that describe relationships and status, and method attributes that document individual methods. Let me walk through each group properly.

Class type attributes

These attributes go on the class declaration itself. They tell Signal what kind of class it is looking at, which determines how the generated output groups and presents the information.

Each class type attribute accepts a description string and a tags array. The description becomes the first thing a reader sees in the generated docs for that class. The tags appear as metadata and can be used to filter or group output in custom tooling downstream.

`#[Module]`

Marks a top-level application module that groups related functionality together.

use JustSteveKing\Signal\Attributes\Module;

#[Module(
    description: 'Handles everything related to billing, invoicing, and payment processing',
    tags: ['billing'],
)]
final class BillingModule {}

`#[Service]`

Marks an application or domain service containing business logic.

use JustSteveKing\Signal\Attributes\Service;

#[Service(
    description: 'Processes subscription renewals and handles billing retries',
    tags: ['subscriptions', 'billing'],
)]
final class SubscriptionRenewalService {}

`#[Repository]`

Marks a data access layer class that wraps persistence.

use JustSteveKing\Signal\Attributes\Repository;

#[Repository(
    description: 'Reads and writes Order records to the database',
    tags: ['orders', 'persistence'],
)]
final class OrderRepository {}

`#[Action]`

Marks a single-purpose action class. If you follow a use-case or interactor pattern, this is the attribute you will use most.

use JustSteveKing\Signal\Attributes\Action;

#[Action(
    description: 'Places a new customer order and reserves the required inventory',
    tags: ['orders'],
)]
final class PlaceOrderAction {}

`#[Controller]`

Marks an HTTP controller that handles incoming requests.

use JustSteveKing\Signal\Attributes\Controller;

#[Controller(
    description: 'Manages order CRUD endpoints',
    tags: ['orders', 'api'],
)]
final class OrderController {}

`#[Event]`

Marks a domain event representing something that happened in the system.

use JustSteveKing\Signal\Attributes\Event;

#[Event(
    description: 'Fired when a customer successfully places an order',
    tags: ['orders', 'events'],
)]
final class OrderPlacedEvent {}

`#[Listener]`

Marks an event listener that reacts to one or more domain events. You will typically combine this with #[ListensTo] from the metadata group.

use JustSteveKing\Signal\Attributes\Listener;

#[Listener(
    description: 'Handles post-order notification emails',
    tags: ['orders', 'email'],
)]
final class OrderNotificationListener {}

`#[Middleware]`

Marks HTTP middleware. It accepts an optional priority integer that controls the order in which middleware appears in the generated output, which is useful when execution order matters.

use JustSteveKing\Signal\Attributes\Middleware;

#[Middleware(
    description: 'Validates the Bearer token on every authenticated request',
    tags: ['auth'],
    priority: 10,
)]
final class AuthMiddleware {}

`#[Job]`

Marks a queueable background job. It accepts an optional queue string so the target queue is visible in the generated docs without anyone having to open the job class.

use JustSteveKing\Signal\Attributes\Job;

#[Job(
    description: 'Sends the customer invoice PDF by email after an order is placed',
    tags: ['billing', 'email'],
    queue: 'invoices',
)]
final class SendInvoiceJob {}

`#[Command]`

Marks a console command.

use JustSteveKing\Signal\Attributes\Command;

#[Command(
    description: 'Recalculates all open subscription invoices for the current billing cycle',
    tags: ['billing', 'cli'],
)]
final class RecalculateInvoicesCommand {}

`#[Query]`

Marks a read-only query class on the query side of a CQRS pattern.

use JustSteveKing\Signal\Attributes\Query;

#[Query(
    description: 'Fetches a paginated list of orders for the currently authenticated user',
    tags: ['orders', 'cqrs'],
)]
final class GetUserOrdersQuery {}

`#[Aggregate]`

Marks a DDD aggregate root that owns a consistency boundary.

use JustSteveKing\Signal\Attributes\Aggregate;

#[Aggregate(
    description: 'Order aggregate root managing the full order lifecycle from placement to fulfilment',
    tags: ['orders', 'ddd'],
)]
final class OrderAggregate {}

`#[ValueObject]`

Marks a DDD value object. Immutable and identity-less.

use JustSteveKing\Signal\Attributes\ValueObject;

#[ValueObject(
    description: 'Represents a monetary amount with currency, safe for arithmetic operations',
    tags: ['money', 'ddd'],
)]
final class Money {}

Class metadata attributes

These attributes sit alongside the class type attribute and add relational and status context. They describe what a class depends on, what events it handles, whether it is deprecated, and whether it is internal.

`#[DependsOn]`

Declares an explicit dependency on another class. It is repeatable, so you can stack it to declare every dependency a class has.

use JustSteveKing\Signal\Attributes\Service;
use JustSteveKing\Signal\Attributes\DependsOn;

#[Service(description: 'Orchestrates the end-to-end checkout process')]
#[DependsOn(class: PaymentGateway::class, description: 'Charges the customer')]
#[DependsOn(class: InventoryService::class, description: 'Reserves stock before payment is taken')]
#[DependsOn(class: OrderRepository::class)]
final class CheckoutService {}

The generated docs will include a dependency table for this class. At a glance you can see what a service needs to function, without reading through the constructor or hunting down injected types. That is particularly useful when you are onboarding someone new or trying to understand the blast radius of a change before you make it.

`#[ListensTo]`

Declares which domain events a listener class handles. Also repeatable.

use JustSteveKing\Signal\Attributes\Listener;
use JustSteveKing\Signal\Attributes\ListensTo;

#[Listener(description: 'Handles all post-order notification events')]
#[ListensTo(event: 'OrderPlaced', description: 'Sends order confirmation email', tags: ['email'])]
#[ListensTo(event: 'OrderCancelled', description: 'Sends cancellation notice', tags: ['email'])]
#[ListensTo(event: 'OrderRefunded', description: 'Sends refund confirmation', tags: ['email'])]
final class OrderNotificationListener {}

Event-driven systems can be hard to trace because the connection between emitter and listener is often implicit and scattered across service providers or config files. Signal surfaces it directly on the class.

`#[Deprecated]`

Marks a class or method as deprecated with an optional version and reason. This is one of those attributes that pays off specifically in larger teams and older codebases.

On a class:

use JustSteveKing\Signal\Attributes\Service;
use JustSteveKing\Signal\Attributes\Deprecated;

#[Service(description: 'Legacy payment handler from the pre-Stripe era')]
#[Deprecated(reason: 'Replaced by StripePaymentService', since: '2.0.0')]
final class LegacyPaymentService {}

On a method:

#[Deprecated(reason: 'Use processRefundV2() instead', since: '1.8.0')]
public function processRefund(int $orderId): bool
{
    // ...
}

The generated docs flag deprecated classes and methods clearly, so a reader knows immediately whether they should be using something or looking for its replacement.

`#[Internal]`

Marks a class or method as internal, meaning it is not part of the public API and should not be relied upon by external consumers.

use JustSteveKing\Signal\Attributes\Internal;

#[Internal(reason: 'Framework bootstrap only, do not use directly')]
final class KernelBootstrapper {}

This is especially useful if you are building a package. Signal will note internal classes in the output so that anyone reading the docs understands the stability contract, or absence of one, for a given class.

Method attributes

This is where Signal earns its keep on a daily basis. The method-level attributes document the HTTP layer, access control, validation, caching, events, exceptions, and side effects. None of these are inferred from your code. You declare them explicitly, which forces you to think about them.

`#[Route]`

Binds a method to an HTTP verb and path.

use JustSteveKing\Signal\Attributes\Route;

#[Route(method: 'GET', path: '/v1/orders', description: 'Paginated list of orders for the authenticated user')]
public function index(Request $request): JsonResponse {}

#[Route(method: 'POST', path: '/v1/orders', description: 'Place a new order')]
public function store(Request $request): JsonResponse {}

#[Route(method: 'DELETE', path: '/v1/orders/{id}', description: 'Cancel an existing order')]
public function destroy(string $id): JsonResponse {}

`#[Authorize]`

Declares the authorization ability required to call a method. Repeatable for methods that require multiple abilities to be satisfied.

use JustSteveKing\Signal\Attributes\Authorize;

#[Authorize(ability: 'orders.view', description: 'User must own the order or be an admin')]
public function show(Order $order): JsonResponse {}

#[Authorize(ability: 'orders.update')]
#[Authorize(ability: 'orders.approve')]
public function approve(Order $order): JsonResponse {}

`#[Validates]`

Documents the validation rules applied to request fields. Repeatable, and accepts an optional description per field.

use JustSteveKing\Signal\Attributes\Validates;

#[Validates(field: 'email', rules: 'required|email', description: 'Customer email address')]
#[Validates(field: 'items', rules: 'required|array|min:1')]
#[Validates(field: 'items.*.product_id', rules: 'required|integer|exists:products,id')]
#[Validates(field: 'items.*.quantity', rules: 'required|integer|min:1')]
#[Validates(field: 'coupon_code', rules: 'nullable|string|max:20')]
public function store(Request $request): JsonResponse {}

This is not meant to replace your Form Request class. The rules you declare here should mirror what the Form Request enforces. The point is to surface them in the generated docs so that someone reading the API reference does not have to open the Form Request file to understand what a POST body should look like.

`#[Cached]`

Documents that a method's result is cached, with an optional TTL in seconds and cache key pattern.

use JustSteveKing\Signal\Attributes\Cached;

#[Cached(ttl: 300, key: 'orders.user.{userId}', description: 'Cached per user for 5 minutes')]
public function forUser(int $userId): Collection {}

#[Cached(ttl: 3600, key: 'products.catalogue')]
public function all(): Collection {}

When a teammate asks why a query is not returning live data, having the caching behaviour visible in the generated docs is a much faster path to the answer than grepping through the codebase for a cache key.

`#[Emits]`

Documents domain events dispatched by a method. Repeatable and accepts an optional tags array.

use JustSteveKing\Signal\Attributes\Emits;

#[Emits(event: 'OrderPlaced', description: 'Fired after the order is persisted', tags: ['orders'])]
#[Emits(event: 'StockReserved', description: 'Fired once inventory is locked', tags: ['inventory'])]
public function store(Request $request): JsonResponse {}

`#[Throws]`

Documents exceptions a method may throw. Repeatable.

use JustSteveKing\Signal\Attributes\Throws;

#[Throws(exception: PaymentFailedException::class, description: 'When the payment gateway rejects the charge')]
#[Throws(exception: InsufficientStockException::class, description: 'When a product cannot be reserved')]
#[Throws(exception: OrderLimitExceededException::class, description: 'When the user has too many open orders')]
public function store(Request $request): JsonResponse {}

`#[SideEffect]`

Documents observable side effects beyond the return value. This is the attribute I find most clarifying to write, because it forces you to acknowledge everything your method does beyond returning a value.

use JustSteveKing\Signal\Attributes\SideEffect;

#[SideEffect(description: 'Sends an order confirmation email to the customer', tags: ['email'])]
#[SideEffect(description: 'Decrements inventory for each line item', tags: ['inventory'])]
#[SideEffect(description: 'Publishes an OrderPlaced message to the event bus', tags: ['events'])]
public function store(Request $request): JsonResponse {}

If you find yourself stacking five or six #[SideEffect] attributes on a single method, that is a signal worth listening to. A method with that many side effects is probably doing too much.

Putting it all together

Here is a complete, realistic controller with the full set of Signal annotations showing how the attributes compose in practice:

<?php

declare(strict_types=1);

namespace App\Http\Controllers\Api\V1;

use JustSteveKing\Signal\Attributes\Controller;
use JustSteveKing\Signal\Attributes\DependsOn;
use JustSteveKing\Signal\Attributes\Route;
use JustSteveKing\Signal\Attributes\Authorize;
use JustSteveKing\Signal\Attributes\Validates;
use JustSteveKing\Signal\Attributes\Emits;
use JustSteveKing\Signal\Attributes\Throws;
use JustSteveKing\Signal\Attributes\SideEffect;
use JustSteveKing\Signal\Attributes\Cached;

#[Controller(
    description: 'RESTful controller for managing customer orders',
    tags: ['orders', 'api', 'v1'],
)]
#[DependsOn(class: OrderService::class, description: 'Handles order business logic')]
#[DependsOn(class: OrderRepository::class)]
final class OrderController
{
    #[Route(method: 'GET', path: '/v1/orders', description: 'Paginated list of orders for the authenticated user')]
    #[Authorize(ability: 'orders.viewAny')]
    #[Cached(ttl: 60, key: 'orders.index.user.{userId}.page.{page}')]
    public function index(Request $request): JsonResponse
    {
        // ...
    }

    #[Route(method: 'GET', path: '/v1/orders/{id}', description: 'Fetch a single order by ID')]
    #[Authorize(ability: 'orders.view', description: 'User must own the order or be an admin')]
    #[Throws(exception: OrderNotFoundException::class, description: 'When the order does not exist')]
    public function show(string $id): JsonResponse
    {
        // ...
    }

    #[Route(method: 'POST', path: '/v1/orders', description: 'Place a new order')]
    #[Authorize(ability: 'orders.create')]
    #[Validates(field: 'items', rules: 'required|array|min:1', description: 'Line items for the order')]
    #[Validates(field: 'items.*.product_id', rules: 'required|integer|exists:products,id')]
    #[Validates(field: 'items.*.quantity', rules: 'required|integer|min:1')]
    #[Validates(field: 'payment_method', rules: 'required|in:card,bank_transfer')]
    #[Emits(event: 'OrderPlaced', description: 'Dispatched after the order is persisted')]
    #[SideEffect(description: 'Sends order confirmation email to the customer', tags: ['email'])]
    #[SideEffect(description: 'Reserves inventory for each line item', tags: ['inventory'])]
    #[Throws(exception: PaymentFailedException::class, description: 'When the gateway rejects the charge')]
    #[Throws(exception: InsufficientStockException::class, description: 'When a product cannot be reserved')]
    public function store(Request $request): JsonResponse
    {
        // ...
    }

    #[Route(method: 'DELETE', path: '/v1/orders/{id}', description: 'Cancel an existing order')]
    #[Authorize(ability: 'orders.cancel', description: 'Order owner or admin only')]
    #[Emits(event: 'OrderCancelled')]
    #[SideEffect(description: 'Releases reserved inventory back to stock', tags: ['inventory'])]
    #[Throws(exception: OrderNotFoundException::class)]
    #[Throws(exception: OrderAlreadyShippedException::class, description: 'When the order has already left the warehouse')]
    public function destroy(string $id): JsonResponse
    {
        // ...
    }
}

Running php vendor/bin/signal generate against that file produces a Markdown section with full route, authorization, validation, event, side effect, and exception tables, grouped under the Controllers heading with a table of contents entry. Everything is structured and predictable.

What the generated Markdown looks like

For the store() method above, Signal produces something close to this:

#### `store()`

**Route:** `POST /v1/orders` - Place a new order

**Requires Authorization:**

| Ability | Description |
|---------|-------------|
| `orders.create` | - |

**Validates:**

| Field | Rules | Description |
|-------|-------|-------------|
| `items` | `required\|array\|min:1` | Line items for the order |
| `items.*.product_id` | `required\|integer\|exists:products,id` | - |
| `items.*.quantity` | `required\|integer\|min:1` | - |
| `payment_method` | `required\|in:card,bank_transfer` | - |

**Emits:**

| Event | Description |
|-------|-------------|
| `OrderPlaced` | Dispatched after the order is persisted |

**Side Effects:**

| Description | Tags |
|-------------|------|
| Sends order confirmation email to the customer | `email` |
| Reserves inventory for each line item | `inventory` |

**Throws:**

| Exception | Description |
|-----------|-------------|
| `PaymentFailedException` | When the gateway rejects the charge |
| `InsufficientStockException` | When a product cannot be reserved |

Clean tables. No noise. Everything a developer needs to understand a method without opening the implementation.

The JSON output

The JSON format deserves attention on its own because it is more than a documentation format. It is machine-readable, which means you can use it as input for custom tooling.

You could pipe it into an internal developer portal. You could use it as context when generating tests or reviewing code with an LLM. You could write a validation step in CI that ensures every public controller method has at least a #[Route] and a #[Authorize] attribute before a pull request can merge.

Here is a trimmed example of what the JSON looks like for the controller above:

{
    "generated_at": "2025-04-30T09:00:00+00:00",
    "classes": [
        {
            "name": "OrderController",
            "namespace": "App\\Http\\Controllers\\Api\\V1",
            "fully_qualified_name": "App\\Http\\Controllers\\Api\\V1\\OrderController",
            "file": "src/Http/Controllers/Api/V1/OrderController.php",
            "type": "controller",
            "description": "RESTful controller for managing customer orders",
            "tags": ["orders", "api", "v1"],
            "dependencies": [
                { "class": "OrderService", "description": "Handles order business logic" },
                { "class": "OrderRepository", "description": "" }
            ],
            "methods": [
                {
                    "name": "store",
                    "route": {
                        "method": "post",
                        "path": "/v1/orders",
                        "description": "Place a new order"
                    },
                    "authorize": [
                        { "ability": "orders.create", "description": "" }
                    ],
                    "validates": [
                        { "field": "items", "rules": "required|array|min:1", "description": "Line items for the order" },
                        { "field": "items.*.product_id", "rules": "required|integer|exists:products,id", "description": "" }
                    ],
                    "emits": [
                        { "event": "OrderPlaced", "description": "Dispatched after the order is persisted", "tags": [] }
                    ],
                    "side_effects": [
                        { "description": "Sends order confirmation email to the customer", "tags": ["email"] }
                    ],
                    "throws": [
                        { "exception": "PaymentFailedException", "description": "When the gateway rejects the charge" }
                    ]
                }
            ]
        }
    ]
}

The structure is consistent and predictable. Every class has the same shape. Every method has the same shape. That predictability is what makes it useful as a data source rather than just a document to read.

Fitting Signal into your workflow

The simplest integration is to run php vendor/bin/signal generate locally before committing. But you can go further.

Add it to your CI pipeline and commit the output. If the generated output changes, the diff shows up in the pull request alongside the code change that caused it. Reviewers can see what the documentation impact of a change is without running anything locally.

You can also use it as a gate. Write a step that runs Signal and then checks whether the output contains a #[Route] and at least one #[Authorize] for every controller method. If something is missing, the build fails. Documentation becomes enforced rather than encouraged.

For teams that maintain an internal developer portal, the JSON output is a natural feed. Parse it, store it, render it however you need. The generation step can run on every merge to main and push updated docs automatically. You get a portal that stays current without anyone having to remember to update it.

What this changes about how you write code

The real value of Signal is not the docs themselves. It is the habit it creates.

When you know that an attribute will appear in the generated output, you start thinking more carefully about what you are building. Declaring #[Throws] forces you to consider what exceptions a method should actually surface. Declaring #[SideEffect] forces you to think about what your code does beyond the return value. Declaring #[DependsOn] makes implicit coupling explicit. Declaring #[Emits] means you have to name the events you are dispatching, which tends to make you think harder about whether they are well-named in the first place.

Documentation is usually an afterthought. With Signal, it is part of the act of writing the class. That shift is small. The compounding effect across a codebase and a team is significant.

If you have ever inherited a codebase where the docs were useless and the only source of truth was reading the implementation line by line, you already know why that matters.

Get started

Signal is open source and available at github.com/JustSteveKing/signal. Install it, annotate a controller or service, run the generator, and see what comes out. Issues and contributions are welcome.

If you build something interesting with the JSON output, whether that is a custom portal, a CI gate, or something I haven't thought of, I would genuinely like to hear about it.

Building Modern Laravel APIs: The Action Pattern

Steve McDougall — Tue, 14 Apr 2026 09:18:24 +0000

We have a lead ingestion endpoint. Leads arrive, get validated, and get persisted with a pending status and a score of zero. That is the raw intake. Now we need to do something with them.

In this article we are going to build the processing pipeline that transforms a raw lead into something genuinely useful for a sales team. That means AI-powered enrichment via the Laravel AI SDK, a scoring engine that assigns a priority value, and a clean pipeline that wires it all together using composable Action classes.

This is also the article where the Action pattern pays off most visibly. We are not building one thing - we are building three distinct operations and then composing them. The architecture makes that composition clean.

The Processing Pipeline

Before writing any code, let's be clear about what the pipeline does. When a lead arrives it has a pending status. We need to:

Take the raw payload and use AI to infer or fill in missing context - company size, industry, seniority level, anything that was not explicitly provided but can be reasonably inferred. Store that as enriched_data on the lead. Then calculate a score between 0 and 100 based on the enriched data and the scoring rules we care about. Finally update the lead status to enriched and persist both the enriched data and the score.

Three jobs. Three actions. One pipeline action that composes them.

The Laravel AI SDK

The AI SDK is already part of Laravel 13. Install it and publish the config:

composer require laravel/ai
php artisan vendor:publish --provider="Laravel\Ai\AiServiceProvider"
php artisan migrate

The migration creates the agent_conversations and agent_conversation_messages tables that power the SDK's conversation storage. Configure your provider credentials in .env:

ANTHROPIC_API_KEY=your-key-here

The SDK supports OpenAI, Anthropic, Gemini, and several others. Because we are using the SDK's abstraction layer, swapping providers is a config change, not a code change. That is exactly the kind of flexibility a production application needs.

The Enrichment Agent

The Laravel AI SDK introduces the concept of an Agent - a dedicated PHP class that encapsulates the instructions and output schema for interacting with a language model. Agents implement contracts rather than extend a base class, which keeps them clean and composable.

Generate one:

php artisan make:agent LeadEnrichmentAgent --structured

This creates a class in app/Ai/Agents/ that implements Agent and HasStructuredOutput and uses the Promptable trait. Update it at app/Ai/Agents/LeadEnrichmentAgent.php:

<?php

declare(strict_types=1);

namespace App\Ai\Agents;

use Illuminate\Contracts\JsonSchema\JsonSchema;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\HasStructuredOutput;
use Laravel\Ai\Promptable;
use Stringable;

final class LeadEnrichmentAgent implements Agent, HasStructuredOutput
{
    use Promptable;

    public function instructions(): Stringable|string
    {
        return <<<PROMPT
        You are a B2B sales intelligence assistant. Given the information about a lead,
        infer and return structured enrichment data that would help a sales team prioritise
        and personalise their outreach.

        Use only the information provided. Do not invent specific facts. Where something
        cannot be reasonably inferred, return null for that field.
        PROMPT;
    }

    public function schema(JsonSchema $schema): array
    {
        return [
            'industry' => $schema->string()->nullable()
                ->description('The lead\'s industry sector, e.g. "SaaS", "FinTech", "Healthcare"'),
            'company_size' => $schema->string()->nullable()
                ->description('Estimated company size, e.g. "1-10", "11-50", "51-200", "201-1000", "1000+"'),
            'seniority_level' => $schema->string()->nullable()
                ->description('The lead\'s seniority, e.g. "Junior", "Mid", "Senior", "Director", "C-Level"'),
            'is_decision_maker' => $schema->boolean()->nullable()
                ->description('Whether this lead is likely a decision maker based on their job title'),
            'inferred_pain_points' => $schema->array($schema->string())
                ->description('A list of likely pain points based on the lead\'s role and company context'),
            'enrichment_confidence' => $schema->number()
                ->description('A confidence score from 0.0 to 1.0 indicating how much context was available for enrichment'),
        ];
    }
}

The schema() method receives a JsonSchema $schema instance and returns an array of field definitions. Each field uses the fluent schema builder to describe its type, nullability, and what it represents. The SDK enforces this shape on the model's response, so we always get back a typed, predictable structure rather than freeform text we have to parse and validate ourselves.

The instructions() method defines the system prompt. It tells the model exactly what its job is and explicitly instructs it not to invent specific facts - a critical constraint for a production application where hallucinated data in a CRM causes real problems.

The Enrichment Action

Now the Action that uses the agent.

Create app/Actions/Leads/EnrichLead.php:

<?php

declare(strict_types=1);

namespace App\Actions\Leads;

use App\Ai\Agents\LeadEnrichmentAgent;
use App\Enums\LeadStatus;
use App\Models\Lead;

final readonly class EnrichLead
{
    public function __construct(
        private LeadEnrichmentAgent $agent,
    ) {}

    public function handle(Lead $lead): Lead
    {
        $enrichmentData = (array) $this->agent->prompt(
            $this->buildPrompt($lead),
        );

        $lead->update([
            'enriched_data' => $enrichmentData,
            'status' => LeadStatus::Enriching,
        ]);

        return $lead->fresh();
    }

    private function buildPrompt(Lead $lead): string
    {
        $context = array_filter([
            "Email: {$lead->email}",
            "Name: {$lead->first_name} {$lead->last_name}",
            $lead->company ? "Company: {$lead->company}" : null,
            $lead->job_title ? "Job title: {$lead->job_title}" : null,
            $lead->phone ? "Phone: {$lead->phone}" : null,
            "Lead source: {$lead->source}",
        ]);

        return "Enrich this lead:\n\n" . implode("\n", $context);
    }
}

A few things worth calling out. The agent is injected via the constructor - the container resolves it automatically, which means we can swap the underlying AI provider by changing configuration, not code.

Because LeadEnrichmentAgent implements HasStructuredOutput, calling ->prompt() returns the structured response directly as an object. We cast it to an array for storage in the enriched_data JSON column.

The buildPrompt() method uses array_filter() to remove null values before building the context string. We only send the model data we actually have. Sending empty fields wastes tokens and can confuse the enrichment output.

We set status to LeadStatus::Enriching rather than LeadStatus::Enriched at this stage - the lead is mid-pipeline. The orchestrating ProcessLead action sets it to Enriched once scoring is also complete.

$lead->fresh() at the end returns a fresh model instance from the database with the updated values. Returning the lead rather than void keeps the action composable - the next action in the pipeline receives the updated model.

The Scoring Action

Scoring translates the enriched data into a single integer between 0 and 100 that tells the sales team how much to prioritise this lead. The scoring rules are business logic, not AI - they should be explicit, deterministic, and easy to adjust.

Create app/Actions/Leads/ScoreLead.php:

<?php

declare(strict_types=1);

namespace App\Actions\Leads;

use App\Models\Lead;

final readonly class ScoreLead
{
    public function handle(Lead $lead): Lead
    {
        $score = $this->calculate($lead);

        $lead->update(['score' => $score]);

        return $lead->fresh();
    }

    private function calculate(Lead $lead): int
    {
        $score = 0;
        $enriched = $lead->enriched_data ?? [];

        // Decision makers are high value
        if (($enriched['is_decision_maker'] ?? false) === true) {
            $score += 30;
        }

        // Seniority signals
        $score += match ($enriched['seniority_level'] ?? null) {
            'C-Level' => 25,
            'Director' => 20,
            'Senior' => 10,
            'Mid' => 5,
            default => 0,
        };

        // Company size signals - larger companies are more valuable
        $score += match ($enriched['company_size'] ?? null) {
            '1000+' => 20,
            '201-1000' => 15,
            '51-200' => 10,
            '11-50' => 5,
            default => 0,
        };

        // Reward high enrichment confidence
        $confidence = (float) ($enriched['enrichment_confidence'] ?? 0.0);
        $score += (int) round($confidence * 15);

        // Penalise missing key fields
        if (empty($lead->company)) {
            $score -= 5;
        }

        if (empty($lead->job_title)) {
            $score -= 5;
        }

        return max(0, min(100, $score));
    }
}

The scoring rules are explicit match expressions rather than conditionals buried in if/else chains. That makes them easy to read and easy to adjust when the business decides that company size matters more than seniority, or that a new tier needs adding.

The final max(0, min(100, $score)) clamps the result to the valid range regardless of how the rules interact. Defensive but correct.

The enrichment confidence score from the AI agent feeds directly into the scoring calculation. A lead enriched from a rich dataset of context signals - job title, company, industry - gets a small bonus. A lead where the model had little to work with gets less. This creates a natural feedback loop that rewards more complete inbound data.

The Pipeline Action

Now we compose. ProcessLead is the orchestrating action that runs the full pipeline end-to-end.

Create app/Actions/Leads/ProcessLead.php:

<?php

declare(strict_types=1);

namespace App\Actions\Leads;

use App\Models\Lead;
use Throwable;

final readonly class ProcessLead
{
    public function __construct(
        private EnrichLead $enrichLead,
        private ScoreLead $scoreLead,
    ) {}

    public function handle(Lead $lead): Lead
    {
        try {
            $lead = $this->enrichLead->handle($lead);
            $lead = $this->scoreLead->handle($lead);

            $lead->update(['status' => 'enriched']);

            return $lead->fresh();
        } catch (Throwable $e) {
            $lead->update(['status' => 'failed']);

            throw $e;
        }
    }
}

The pipeline is explicit and linear. Enrich, then score, then mark as enriched. If anything throws, mark the lead as failed and re-throw so the caller can handle it at the appropriate level.

Re-throwing rather than swallowing the exception is important. Swallowing exceptions in pipelines is one of the more reliable ways to create debugging nightmares - leads silently fail and nobody knows why. We catch to set the status, then re-throw so the problem surfaces properly.

The dependency injection chain here is worth appreciating. ProcessLead declares its dependencies. Laravel's container resolves EnrichLead, which in turn declares its dependency on LeadEnrichmentAgent, which the container also resolves. Nothing is manually instantiated. The whole pipeline wires together through the container.

Lead Status as an Enum

As we add more statuses it becomes clear that representing them as raw strings is fragile. Let's introduce a proper enum.

Create app/Enums/LeadStatus.php:

<?php

declare(strict_types=1);

namespace App\Enums;

enum LeadStatus: string
{
    case Pending = 'pending';
    case Enriching = 'enriching';
    case Enriched = 'enriched';
    case Failed = 'failed';
}

Update the Lead model to cast the status column to this enum:

protected function casts(): array
{
    return [
        'raw_payload' => 'array',
        'enriched_data' => 'array',
        'score' => 'integer',
        'status' => LeadStatus::class,
    ];
}

Update the IngestLead action to use the enum:

return Lead::create([
    ...$payload->toArray(),
    'raw_payload' => $payload->toArray(),
    'status' => LeadStatus::Pending,
    'score' => 0,
]);

And update ProcessLead and EnrichLead to use the enum constants rather than raw strings:

// In EnrichLead
$lead->update([
    'enriched_data' => $enrichmentData,
    'status' => LeadStatus::Enriching,
]);

// In ProcessLead
$lead->update(['status' => LeadStatus::Enriched]);
// and on failure:
$lead->update(['status' => LeadStatus::Failed]);

Now if a status value is mistyped or a new case needs adding, the type system catches it rather than silent string comparison failures.

Triggering the Pipeline

The ProcessLead action needs to be called somewhere. For now, we can trigger it directly from the IngestLead action for demonstration - but in Article 9 we will move it to a queued job so the HTTP response is not blocked by the AI enrichment call.

Update app/Actions/Leads/IngestLead.php:

<?php

declare(strict_types=1);

namespace App\Actions\Leads;

use App\Enums\LeadStatus;
use App\Http\Payloads\Leads\StoreLeadPayload;
use App\Models\Lead;

final readonly class IngestLead
{
    public function __construct(
        private ProcessLead $processLead,
    ) {}

    public function handle(StoreLeadPayload $payload): Lead
    {
        $lead = Lead::create([
            ...$payload->toArray(),
            'raw_payload' => $payload->toArray(),
            'status' => LeadStatus::Pending,
            'score' => 0,
        ]);

        return $this->processLead->handle($lead);
    }
}

This is the synchronous version. The controller calls IngestLead, which creates the lead and immediately kicks off enrichment. In a real production environment this would block the HTTP response while the AI call completes - acceptable for now, properly addressed with queues in Article 9.

Configuring the AI Provider

Add your provider key to .env:

ANTHROPIC_API_KEY=your-key-here

The default provider is configured in config/ai.php. For Pulse-Link, Anthropic's Claude is a sensible default given the quality of structured output for enrichment tasks:

'default' => env('AI_PROVIDER', 'anthropic'),

Because we are using the SDK's agent abstraction, switching to OpenAI is a one-line change to the default provider config. The LeadEnrichmentAgent does not know or care which model is running underneath it.

What We Have Now

The Action pattern is doing real work. Three single-responsibility actions - EnrichLead, ScoreLead, and ProcessLead - compose into a pipeline that takes a raw lead from pending to enriched with an AI-generated context payload and a deterministic score.

Each action is independently testable. Swap the agent for a fake in tests, test the scoring logic in isolation, test the pipeline orchestration without touching the AI layer. We will do exactly that in Article 8.

The pipeline is also extensible. Adding a deduplication step, a geographic enrichment step, or a company data lookup is a matter of creating a new action and adding it to ProcessLead. The existing actions do not change.

In the next article we are going to build the lead scoring and prioritisation layer in more depth - turning the enriched data into a ranked list that the sales team can actually work from.

Next: Lead Scoring and Prioritisation - building the ranking engine that surfaces the highest-value leads first using enriched data and configurable scoring rules.