DEV Community: Vlad Zoff

The Agent Shouldn't Be Able to Approve Its Own Rules

Vlad Zoff — Thu, 01 Oct 2026 05:17:52 +0000

Once a coding agent can change the architecture, changing the rules that protect it becomes a different kind of operation.

One of the less obvious problems I've run into with coding agents isn't that they make bad changes.

It's that sometimes they make a perfectly reasonable change that invalidates one of the rules I'm using to check the project.

That's a different problem.

Imagine a project has this rule:

All payment-provider access must go through PaymentAdapter.

An agent is asked to add support for another payment provider.

It looks at the existing code and decides that the current adapter isn't quite right. It wants to introduce a new abstraction.

The resulting change crosses a boundary that the project currently protects.

The checker reports a violation.

So what should happen next?

The obvious automation is:

agent changes the code;
check fails;
agent changes the rule;
check passes.

Technically, everything worked.

But the system has a problem: The thing being checked was allowed to change the conditions of the check.

That made me much more interested in the difference between changing the code and changing the rules around the code.

The dangerous loop

The simplest version looks like this:

agent
  ↓
change code
  ↓
verification
  ↓
failure
  ↓
agent changes policy
  ↓
verification
  ↓
pass

There is nothing obviously broken here.

The agent might even have a good reason for changing the policy.

The problem is that the verification boundary has disappeared.

A policy is supposed to tell the system what has to remain true.

If the same actor that made the change can also redefine what "true" means, a successful verification doesn't tell you very much.

It's just a moving target.

And this isn't specific to architecture.

You could do the same thing with:

maximum service size = 300 lines

The agent produces a 420-line service.

The check fails.

The agent changes the limit to 500.

The check passes.

Or:

module A cannot import module B

The agent needs the dependency.

It changes the rule.

The import is now allowed.

Again, maybe that's the right architectural decision.

But those are two separate decisions:

The implementation changed.
The policy changed.

They shouldn't become one operation just because the same agent proposed both.

Not every policy violation is actually a mistake

This is where it gets more interesting.

I don't want an architecture checker that treats every violation as proof that the agent did something wrong.

Sometimes the agent really should change the architecture.

Suppose an application has:

Checkout
   ↓
PaymentAdapter
   ↓
Stripe

And I decide that the product is getting large enough that payment workflows deserve their own domain boundary:

Checkout
   ↓
PaymentService
   ↓
PaymentAdapter
   ↓
Stripe

The change introduces new files.

Some imports move.

Some old boundaries disappear.

New ones appear.

A strict checker could report a pile of violations.

That doesn't mean the change is bad.

It means the current policy describes the old architecture.

This distinction matters.

A policy isn't supposed to prevent architecture from ever changing.

It is supposed to make architecture changes explicit.

Proposal and approval are different things

This led me to a fairly simple rule: An agent should be able to propose a policy change, but it shouldn't automatically be able to approve that policy change.

For example:

Current policy:

Payment provider access must go through PaymentAdapter.

The agent can say:

Proposed change:

Allow PaymentService to depend directly on a new internal
PaymentProvider interface.

Reason:
The current adapter boundary prevents the new workflow
from sharing transaction state correctly.

That's useful.

The agent has done the hard reasoning.

It has identified the existing constraint.

It has explained why the constraint may no longer fit.

But the proposal should remain a proposal.

The important part is that the authority approving the policy change is separate from the agent that authored the change.

Otherwise the system can silently move the goalposts.

This is the same reason I don't want approval in the prompt

A prompt can say:

Never deploy without approval.

That's useful instruction.

It's not much of a control if the same process can modify the configuration that defines what counts as an approved deployment.

The more autonomous the agent becomes, the more these distinctions move out of the prompt and into the environment around it.

The agent should be able to reason about the policy.

It should be able to request a policy change.

It should be able to explain the change.

The actual enforcement shouldn't depend on the agent remembering to follow its own instructions.

A policy change should leave a trail

Once policy becomes a real project artifact, another problem appears.

You need to know what the policy was when the original change was checked.

Otherwise you can end up with a strange situation where today's successful verification only makes sense because yesterday's policy was replaced.

That's why I like keeping policy changes explicit and versioned.

Something like:

project state
    ↓
policy revision 17
    ↓
agent proposes architecture change
    ↓
verification fails under policy revision 17
    ↓
policy proposal
    ↓
approval
    ↓
policy revision 18
    ↓
verify change again

Now there are two separate facts:

The change passed under policy revision 18.
Policy revision 18 was itself approved.

That's much more useful than simply seeing a green check.

The old policy still matters

There's another subtle point here.

Suppose an agent changes the rule and then verifies the same diff against the new rule.

You can no longer tell whether the original change violated the previous policy.

So I want the system to preserve the distinction between:

what the project allowed before the change

and:

what the project allows after the change

This becomes especially useful when investigating a change later.

You can ask:

Why did this dependency become allowed?
Was it always allowed?
Was there an explicit exception?
Did a policy revision happen at the same time?
Who approved it?
What evidence led to the change?

Those questions are much harder to answer when policy is just another mutable config file.

Temporary exceptions are different again

Sometimes the policy is fine.

The violation is temporary.

For example:

All persistence access must go through Repository.

But I'm in the middle of a migration.

I don't want to remove the rule.

I just need one known exception for two weeks.

That's not really a policy change.

It's a waiver.

And I think treating it as a different object makes the whole system easier to reason about.

A useful waiver has at least:

owner
reason
scope
expiry

So instead of:

remove the rule

you get:

waive this finding until 2026-12-28

owner: platform-team
reason: repository migration

The rule stays.

The exception expires.

That's a very different thing from changing the architecture policy permanently.

Baselines solve a different problem

I also don't want to confuse waivers with baselines.

A baseline answers:

This violation already existed.

A waiver answers:

This active violation is intentionally allowed for a limited time.

And a policy change answers:

We changed what the project considers acceptable.

Those are three different states.

That separation might sound overly precise.

In practice, it makes the tool much more useful.

A real codebase can have old architectural debt.

It can have temporary migration exceptions.

And it can deliberately evolve its architecture.

If all three become "ignore this finding", you lose important information.

What the agent should actually do

This doesn't mean agents have to stop making architectural changes.

Quite the opposite.

I want them to do more.

A useful agent flow could look like this:

requirement
    ↓
agent plans change
    ↓
implementation
    ↓
deterministic verification
    ↓
failure
    ↓
agent explains why
    ↓
policy proposal / waiver proposal
    ↓
approval
    ↓
verification against new state

The agent can drive most of that workflow.

It can inspect the repository.

It can understand the requirement.

It can implement the refactor.

It can identify the policy that stopped the change.

It can prepare the evidence for a policy proposal.

It can even tell me that the current architecture appears to be the problem.

What it shouldn't get is an invisible path from:

my change failed

to:

therefore my own change is now allowed

This also changes what "autonomous" means

I've started thinking that autonomy isn't really one switch.

An agent can have permission to:

read the repository;
modify source files;
run tests;
inspect dependencies;
propose policy changes;

without having permission to:

approve those policy changes;
remove its own enforcement;
extend a temporary waiver indefinitely;
change the authority that verifies it.

That gives you a more useful permission model than simply:

autonomous = yes/no

Different operations can have different authorities.

And that matters more once the agent is running for a long time or can delegate work to other agents.

The verifier should not care who made the code change

There's another distinction here that I find useful.

Verification should primarily answer:

Does the current change fit the current approved policy?

It doesn't need to decide whether the author was:

human
Claude
Codex
Cursor
another agent
automation

That's a separate concern.

The verifier checks the state.

The policy layer defines the constraint.

The authority layer controls who can change the constraint.

Keeping those pieces separate makes the system much easier to reason about.

This is what I started building into Guard

This distinction ended up affecting the design of Codapult Guard quite a bit.

Guard already had the idea of:

facts
  ↓
policy
  ↓
verification

But that isn't enough when policy itself can change.

So I started treating policy changes as first-class operations.

Guard can discover project facts and prepare proposals.

A project can explicitly approve them.

For protected projects, policy approval can require a distinct actor rather than allowing the authoring agent to approve its own proposal.

The same idea now applies to waivers.

A waiver is not just "ignore this finding forever."

It has an owner, reason and expiry date.

When the expiry is reached, the finding becomes active again.

That gives the project three useful things:

policy
exception
history

instead of one growing collection of ignored warnings.

It also makes agent integration more useful

MCP makes this distinction especially important.

An agent can ask Guard:

What policy applies here?

or:

What did this change affect?

or:

Why did verification fail?

or:

What policy change would be needed for this refactor?

Those are useful questions.

But I don't want the agent to receive:

Change policy until verification passes.

That isn't really verification anymore.

The MCP layer should expose the information and operations the agent needs without quietly giving it the authority to redefine the system around itself.

That's a much more interesting role for project-aware tooling than simply adding another set of commands to an agent.

The rule can change. That isn't the problem.

I don't think architectural rules should be permanent.

Projects change.

Requirements change.

Teams change.

The shape of the system changes.

A rule that made perfect sense six months ago might become actively harmful.

The mistake is treating policy change as an implementation detail.

Changing:

src/payments/StripeAdapter.ts

and changing:

payment-provider-access

are fundamentally different operations.

One changes the system.

The other changes what the system is allowed to become.

Once an agent can perform both, they need separate boundaries.

I'm less interested in stopping agents than in making their authority explicit

The goal isn't to make agents weaker.

I actually want agents to make bigger changes.

But bigger changes require clearer boundaries.

The more of the implementation I delegate, the more I care about questions like:

What can the agent change?
What can it propose?
What can it approve?
What evidence does it have to provide?
What policy was active when the change was checked?
Was the exception temporary?
Who approved the exception?
Can the agent change the thing that verifies it?

Those questions aren't really about whether the model is smart enough.

They're about the architecture around the model.

And that's probably the part that becomes more important as coding agents become capable of doing more work without waiting for a human after every step.

I don't want the agent to be afraid of the rules.

I want it to understand them.

I want it to be able to challenge them.

I want it to be able to propose better ones.

But I don't want it to be the final authority on whether its own change should become the new rule.

The code can change.

The architecture can change.

Even the policy can change.

Those changes just shouldn't all happen under the same authority.

A Dependency Graph Is Not Architecture

Vlad Zoff — Thu, 01 Oct 2026 04:42:23 +0000

A graph can show how your code is connected. It can't tell you which of those connections your project actually wants to keep.

A dependency graph is one of the first things I wanted when I started thinking about tooling for AI coding agents.

It makes sense.

An agent needs to understand a codebase, and a graph is a much better representation of relationships than a pile of files.

You can see that a route depends on a service. That service depends on a repository. A repository depends on a database client. Another module imports the service. A shared utility is suddenly used by half the application.

That information is useful.

But after working with this problem for a while, I started thinking that there is a trap here.

A dependency graph is not architecture.

It is a description of relationships. Architecture also contains intent.

The graph tells you what exists

Suppose I have this:

Client
  ↓
Server Action
  ↓
Service
  ↓
Repository
  ↓
Database

A graph can represent that pretty well.

It can tell me that the service imports the repository. It can tell me that the repository imports the database client. It can tell me which files are connected to a changed module. It can show cycles or unusually large dependency hotspots.

All of that is valuable.

Now imagine another part of the application has this:

Client
  ↓
API Route
  ↓
Database

The graph can show that too.

What it cannot tell me by itself is whether the second path is wrong.

Maybe it is.
Maybe the project deliberately allows direct database access for a reporting endpoint.
Maybe the second path is old code that nobody has touched in three years.
Maybe it was introduced last week and is exactly the pattern the team now wants to standardize on.

The graph contains all four possibilities. It has no way to choose between them.

Architecture has a "why"

This is where the difference matters.

Architecture isn't only a collection of edges between components. It also contains decisions like:

Payment provider access goes through an adapter.
Only server-side code can access persistence.
Module A must not depend on Module B.
This package is intentionally isolated because we may remove it later.
This service owns authorization for this operation.

Those are not just observations about the current repository. They are decisions. And some of them can exist even when the repository doesn't currently satisfy them.

That's an important distinction.

The code might currently contain:

Checkout → Stripe

while the intended architecture is:

Checkout → Payment Adapter → Stripe

If all you have is the current graph, the direct dependency is simply a fact. You don't know that it is a violation until someone tells you what is supposed to be true.

This is why "architecture inference" is tricky

I've seen a few different approaches to this problem.

One is to infer architecture from directory names. If there is a services directory, call it the service layer. If there is a repositories directory, assume everything under it is persistence.

That works until it doesn't.

Another project might use:

features/
domain/
infrastructure/

Another might put all of its business logic inside feature folders. Another might have very little layering at all. Another might have started with one architecture and gradually evolved into something else.

None of those structures is automatically correct.

So I don't really want a tool to look at a repository and say: "This is good architecture."

That seems like the wrong question. I'd rather ask:

"What is this project actually doing?"
"Which parts of that behavior has the team decided to preserve?"

Those are much more concrete questions.

A graph also captures accidental history

There is another problem. Real repositories contain history. Not all history is intentional.

A developer copies an implementation. Another developer adds a shortcut. Someone moves a file but keeps the old import. A feature gets rushed into production. Six months later there are three different ways to access the same thing.

The graph faithfully records all of them.

In that sense, a graph can actually make the ambiguity more visible without resolving it. You might have:

Feature A → Service A → Repository
Feature B → Repository
Feature C → Service C → Repository
Feature D → Service A

What should a coding agent learn from this?

It could conclude that both direct repository access and service access are valid patterns. It could pick the shortest path. It could copy the most common one. It could look at recent commits.

None of those decisions necessarily tells you what the project intended.

And if an agent starts using an accidental pattern as an example for new work, the inconsistency becomes self-reinforcing. That's a much bigger problem than just having an ugly graph.

The missing layer is policy

This is the part I keep coming back to. A useful project model has at least two different things:

Facts: What the repository actually contains.
Policy: Which of those facts describe behavior the project wants to preserve.

The graph is very good at the first one. It doesn't magically give you the second.

For example:

Facts:
Checkout imports PaymentAdapter
PaymentAdapter imports Stripe
RefundService imports Stripe

And then:

Policy:
All payment-provider access must go through PaymentAdapter

Now the system can check something meaningful. A direct Stripe import isn't merely "an unusual edge." It is a concrete violation of a known project decision.

That's a much stronger signal for an AI agent too.

This also makes exceptions easier to handle

Architectural rules almost always have exceptions.

Suppose the rule is: UI modules must not import persistence modules.

Then someone builds an internal admin export screen. The simplest implementation might legitimately need a different path.

Without an explicit policy model, you tend to end up with one of two bad outcomes:

Either the tool becomes so strict that people stop using it.
Or everyone starts ignoring the warnings.

An explicit policy gives you somewhere to put the exception. The project can say:

This boundary normally applies here.
This particular module is allowed to cross it.
Or: This is temporary and needs to be removed later.

That is much closer to how real architecture works.

Baselines matter for the same reason

The same thing happens with existing violations.

Imagine a large application already has twenty direct database imports from places that ideally shouldn't have them. The graph can find twenty edges. A naive architecture checker might immediately fail the project.

That's not especially useful. I don't need a tool telling me that yesterday's codebase was imperfect. I need it to help me stop making the situation worse.

So a more useful question is:

Which violations already existed?
Which ones were approved or baselined?
Which new violations did this change introduce?

That makes the graph part of a useful workflow instead of turning it into a giant list of problems.

The interesting part starts when an agent gets involved

This becomes more important when the repository is being modified by an AI coding agent.

An agent can query a graph and ask:

What depends on this module?
What imports this package?
What routes reach this service?
What will be affected if I change this file?

That's great. But then it needs another question: Am I allowed to make this dependency?

The first question can be answered from repository facts. The second requires policy.

If the system returns: "This import exists," that's one kind of information.

If it returns: "This import exists. This dependency crosses an approved boundary," that's much more useful. It gives the model something it can act on.

This is also where history gets interesting

Git history is useful, but I don't think history should be treated as policy either.

Suppose the agent sees that a particular dependency was added in a large refactor eighteen months ago. That tells you something. Maybe there was a reason. But it doesn't necessarily tell you whether the dependency is still intentional.

The same applies to code frequency. A pattern used 200 times is not automatically a good pattern. A pattern used once is not automatically wrong.

History can provide evidence.

It shouldn't silently become a rule.

Why I built Guard around this distinction

This is one of the ideas that shaped Codapult Guard.

I didn't want to build another system that looks at a repository graph and declares what the architecture should be. Guard starts with the repository that already exists. It discovers facts about the project: files, imports, AST relationships, routes, capabilities, contracts, and other relationships derived from the code.

Then the project can decide which of those things should become policy.

After that, the useful part is verification. For example:

Client module → Database import

can be reported because the project explicitly decided that this dependency isn't allowed.

Guard doesn't treat every possible architectural preference as a universal rule. The project decides, the tooling checks, and existing violations can be baselined so future changes are checked cleanly.

The core checks are deterministic and local. There is no need to ask another model whether one module imports another.

A graph is still extremely useful

None of this means graphs are overrated. Quite the opposite.

A graph is excellent for:

What exists?
What depends on what?
What changed?
What might be affected?
Where are the cycles and hotspots?

Policy can answer:

What is allowed?
What is forbidden?
Which boundaries matter?
Which exceptions are intentional?

Verification can answer:

Did the change preserve those decisions?

Putting them together is much more powerful than pretending one representation can answer all of them.

The agent doesn't need a bigger graph

My first instinct was always: give the agent more information. More files, more history, more dependencies, more documentation, more graph data.

But eventually you hit diminishing returns. The agent doesn't necessarily need the whole graph. It needs the facts that are relevant to the decision it is making, and it needs to know which facts are constraints rather than observations.

For a change to a payment module, I probably don't need a thousand unrelated edges. I need:

This module is affected.
These modules depend on it.
These contracts apply.
This dependency is forbidden.
This exception is approved.
These tests and checks are relevant.

That's much closer to useful project context.

Maybe architecture is better thought of as a decision record

The shape is the visible part. The decisions are the interesting part.

Why is this dependency allowed?
Why is that one forbidden?
Why does this adapter exist?
Why is this module isolated?

A graph can preserve the shape. Policy can preserve some of the decisions. History can provide evidence about how we got there.

Combining them gives an agent a model of the system that separates:

what is true
  ↓
what is intended
  ↓
what changed

That separation is probably more important than making the graph itself smarter.

That's the part I'm still exploring

I don't think the answer is one giant "AI architecture brain" that understands everything in a repository. I'd rather have smaller pieces that do one thing reliably:

Repository analysis establishes facts.
Policy captures decisions.
Static checks verify deterministic constraints.
Tests verify behavior.
An agent reasons about requirements and implementation.
A human decides when the architecture itself should change.

If an AI can change a hundred files in one session, the environment must tell it which parts of that context are observations, which parts are constraints, and which decisions are still open.

A dependency graph is a very good start. It just isn't the architecture.

The Tests Passed. The Architecture Didn't.

Vlad Zoff — Fri, 25 Sep 2026 11:34:05 +0000

What I started noticing after AI coding agents began making bigger changes to my projects.

One of the stranger things about working with coding agents is that a change can be completely valid and still be wrong.

TypeScript passes.

The tests pass.

The build is green.

The feature works.

And I can still look at the diff and think: I don't want this in the codebase.

I started running into this more often as I let agents handle larger changes instead of asking them to implement one small function at a time.

The problem wasn't usually a bug.

It was the shape of the change.

A new module would bypass an existing layer. A feature would introduce another way of doing something the project already had. A dependency would point in the wrong direction. A new piece of code would technically work but ignore a convention that had become important elsewhere.

None of those things necessarily show up in a test suite.

That bothered me more than I expected.

Tests answer a different question

I like tests. This isn't an argument against them.

A test can tell me that creating a subscription works.

It can tell me that an unauthorized user gets a 403.

It can tell me that a background job retries after a failure.

Those are important questions.

But imagine the project has gradually settled on a structure like this:

UI
 ↓
Actions
 ↓
Services
 ↓
Repositories
 ↓
Database

Then an agent adds a new feature and imports the database client directly into a UI-facing module.

The code may compile.

The feature may work.

The tests may all pass.

The problem is simply that the new code doesn't belong there.

The repository now has another path through the system.

Over time those exceptions accumulate.

That's where things get expensive.

This is easier to notice when a human writes the code

When I write a new feature myself, I already have a rough model of the project in my head.

I know which directory handles a particular kind of logic.

I know that a certain integration goes through an adapter.

I know that a particular operation has to go through a service because some permissions are checked there.

I know that a module is supposed to be removable.

I don't necessarily write any of that down.

I just remember it.

An agent doesn't have that memory.

It has the repository.

That's not quite the same thing.

It can search the code and find examples, but examples aren't always rules.

If it finds three slightly different implementations, it doesn't automatically know which one is the accidental old implementation and which one represents the intended pattern.

In fact, the existing inconsistency can become new training data for the next change.

That's the part I started thinking about.

The architecture becomes part of the input

Once an agent is doing a meaningful part of the implementation, architecture is no longer just something humans discuss during design.

It becomes part of the agent's working environment.

The question changes from:

Can the agent write this feature?

To:

Can the agent write this feature without changing how the rest of the project is supposed to work?

Those aren't the same thing.

A coding agent can be very good at finding all the places that need changing.

It can also be very good at making a new abstraction when an existing one would have been enough.

That's not necessarily because the model is bad.

The repository often doesn't make the intended rules explicit.

I didn't want another AI reviewer

My first instinct was to think about adding another model to the process.

The agent writes the change.

A second model reviews the diff.

It points out architectural problems.

The first agent fixes them.

That can work.

But the more I thought about it, the less attractive it became for some classes of problems.

If the repository tells us that one module depends on another, we don't need an LLM to determine that fact.

If a project has explicitly approved a dependency boundary, we don't need a model to have an opinion about whether a particular import crosses it.

If a file changed, we can determine what it imports, what imports it, which routes depend on it, and which capabilities are connected to it.

Those are facts.

I started wondering how much of this could be moved out of the model entirely.

Start with the project that already exists

That led me to a fairly important design decision.

I didn't want an architecture tool that arrived with its own idea of what a "good" TypeScript project should look like.

There are plenty of reasonable architectures.

A random project might use:

components
services
repositories

Another might use:

features
domain
infrastructure

Another might be completely different.

I don't want to tell the project which one is correct.

I want to start by looking at what the project actually does.

That means extracting facts from the repository:

files and directories
imports and dependency relationships
AST information
routes
capabilities
contracts
change impact
other relationships that can be derived from the code itself

The distinction is subtle but important.

There is a big difference between:

"This is the architecture you should use."

and:

"This is how your project currently works."

The second one gives you something to work with without imposing a framework on every repository.

Then make the rules explicit

Facts alone aren't enough.

Suppose a project currently has this dependency:

Application
    ↓
Service
    ↓
Repository

That doesn't automatically mean somebody should never be allowed to bypass the service.

Maybe there is a legitimate exception.

So the next step is explicit policy.

The developer decides which observed patterns matter enough to enforce.

For example:

UI code must not import persistence code directly.

or:

All payment-provider access must pass through the payment adapter.

or:

Module A cannot depend on module B.

The important part for me is that these rules come from the project rather than from the tool's preferred architecture.

The project can decide what to enforce.

The tool can discover the facts and verify the decision.

The useful check is usually about the change

There can already be violations in a real codebase.

If a project has existed for a few years, I'm not going to pretend everything was perfect before today.

That's why I find the idea of a baseline useful.

I care much more about:

Did this change introduce a new architecture violation?

than:

Does this repository contain any violation at all?

That distinction makes the tool much more practical for an existing project.

You can gradually tighten things instead of trying to make a messy codebase perfect before you can use the tooling.

A simple example

Imagine this rule exists:

Client-facing modules cannot import persistence modules.

An agent adds:

import { db } from '@/lib/db';

to a module that sits on the client side of the application.

Nothing necessarily crashes.

There might not even be an obvious runtime error.

But the dependency is now different from the one the project intended to maintain.

A deterministic checker can inspect the change and tell you that.

There is no need for a model to decide whether the import "looks suspicious."

It's a fact that can be checked.

What I actually want the agent to do

This is where the distinction between context and verification becomes useful.

The agent should still do the interesting work.

It can interpret a requirement.

It can decide which existing parts of the application are relevant.

It can choose an implementation.

It can reason about trade-offs.

I'm not trying to replace that.

I want the environment around it to answer questions that don't need model reasoning.

Something more like:

Human
  ↓
Requirement
  ↓
AI agent
  ↓
Implementation
  ↓
Deterministic project checks
  ↓
Agent fixes violations
  ↓
Verification
  ↓
Human review

The model is still doing most of the work.

The difference is that it isn't the final authority on whether the change fits the repository.

This also changes how MCP becomes useful

I've become more interested in MCP for development for the same reason.

There is a big difference between giving an agent another command and giving it structured information about the project.

A command like:

run tests

is useful.

But something like:

what depends on this module?
what project rules apply here?
what capabilities are connected to this change?
what contracts does this area expose?
what changed since the last accepted state?

starts to become much more interesting.

The agent doesn't need to rediscover the entire repository every time.

It can ask for a specific piece of project state.

I've been exploring this in Codapult's own developer tooling, where the CLI and MCP layer expose structured information about a Codapult project.

That work ended up influencing how I thought about the more general problem.

That's why I built Codapult Guard

I ended up building Codapult Guard as an open-source experiment around this idea.

The goal is deliberately narrower than "AI reviews your code."

Guard is interested in the part that can be derived and checked deterministically.

It builds a model of a JavaScript or TypeScript project, lets the developer turn relevant project facts into explicit policy, and can then inspect changes against that policy.

It also looks at impact and project relationships rather than treating every changed file as an isolated blob of text.

There is no LLM call required for the core checks.

That's important to me.

I'm not trying to compete with an AI reviewer by making another AI reviewer.

I'd rather remove the model from questions that are already answerable from the repository.

There are obvious limitations

This isn't a magic solution.

A deterministic architecture check can tell me that a dependency crosses a boundary.

It can't tell me whether the business decision behind that boundary was a good one.

It can't decide whether a new product requirement makes the existing architecture obsolete.

It can't replace a human looking at a risky change.

And a project can have a perfectly consistent architecture that is still the wrong architecture.

I'm okay with that.

The point isn't to automate every decision.

It's to stop using a model where a simpler mechanism is enough.

The part I'm still figuring out

The interesting question for me now isn't really whether agents can write software.

They obviously can.

It's how much of the software environment should be made explicit once they start doing a large part of the implementation.

Some things belong in instructions.

Some belong in tests.

Some belong in static analysis.

Some are better represented as project facts.

Some need a human.

And some really do need a model.

I don't think we need to choose one of those.

We need to get better at separating them.

One last thing

The more I use agents, the less I think of the repository as just source code.

It is also a record of architectural decisions, conventions, dependencies and constraints.

Humans can keep a lot of that information in their heads.

An agent can't.

So if we want agents to make larger changes without slowly turning every project into a collection of locally reasonable decisions, some of that knowledge needs to become explicit.

Not necessarily more documentation.

Not necessarily another AI reviewer.

Sometimes just a fact that can be checked.

That's the direction I'm exploring with Codapult Guard.

Codapult Guard on GitHub

The Next.js SaaS Boilerplate Checklist for 2026

Vlad Zoff — Wed, 12 Aug 2026 19:00:47 +0000

Most SaaS boilerplates look similar on the homepage: auth, payments, dashboard, emails, blog, and a fast launch promise. The differences appear later, when a customer asks for team roles, billing changes, audit logs, SSO, data export, custom domains, or a support workflow.

Use this checklist before you build on any starter.

1. Authentication Is More Than Sign-In

A serious SaaS foundation should answer these questions:

Does it support email/password and OAuth?
Does it support magic links or passkeys?
Can you enable 2FA?
Are protected routes handled consistently?
Are auth API routes rate-limited?
Can admins impersonate users for support?
Can you switch auth providers without rewriting the app?

If auth is only a login form and a session hook, the real work is still ahead.

2. Teams Should Be First-Class

For B2B SaaS, the customer is often an organization, not a single user. The starter should model:

Organizations or workspaces.
Memberships.
Roles.
Invitations.
Active organization context.
Organization-scoped billing.
Organization-scoped analytics.
Organization-scoped webhooks.

Skipping this early usually creates painful migrations later.

3. Billing Needs Product Flexibility

Stripe checkout is useful, but it is not a complete billing model. Check whether the starter handles:

Subscriptions.
One-time purchases.
Trials.
Seat-based billing.
Usage credits.
Add-ons.
Webhook verification.
Customer portal links.
Subscription state in the database.
Admin subscription support.

Many products change packaging after launch. Your boilerplate should make that survivable.

4. Admin Is a Product Surface

Admin panels are often treated as internal afterthoughts. That is a mistake. Customer support, billing support, abuse response, feature flags, and rollout decisions all happen there.

Look for:

User management.
Subscription list.
Waitlist or leads.
Feature flags.
Webhook logs.
Activity logs.
Performance and error visibility.
Export flows.

A usable admin panel reduces support cost and launch risk.

5. The Database Layer Should Be Understandable

Before choosing a starter, inspect the schema:

Are table names clear?
Are relationships explicit?
Are indexes present where lists and lookups need them?
Are auth tables compatible with the auth library?
Is the code tied to one database vendor?
Are migrations documented?

The database is where boilerplate shortcuts become expensive.

6. API Boundaries Should Match the Product

A good SaaS starter should not force one API style everywhere. Type-safe internal product flows can use tRPC, public integrations can use REST or OpenAPI, and flexible clients may need GraphQL.

Check for:

Input validation.
Rate limits.
Authenticated procedures.
Admin-only procedures.
Versioning for public APIs.
Webhook signature verification.
Clear error responses.

7. Email Is Not Just Transactional Templates

You need more than one welcome email:

Verification.
Password or magic link flows.
Invitations.
Billing events.
Reports.
Drip campaigns.
Custom sender domains.
Bounce or suppression handling.

If email is only a demo template, plan extra time.

8. Observability Should Be Wired Early

At launch, you need to know what broke and who was affected. Evaluate:

Structured logs.
Error reporting.
Web vitals.
Analytics events.
Audit logs.
Webhook delivery records.
Background job visibility.

These systems are much easier to wire before production traffic arrives.

9. SEO and Content Matter for SaaS Starters

If the starter includes marketing pages, verify:

Metadata per page.
Open Graph images.
Sitemap.
Robots rules.
Blog RSS.
Canonical URLs.
FAQ schema where appropriate.
Product schema on pricing pages.
Noindex for auth, dashboard, and admin pages.

Marketing infrastructure is part of the product when your acquisition depends on search.

10. Deployment Should Not Be a Single Happy Path

Vercel is a great default, but your customers or internal constraints may push you elsewhere. Look for:

Docker support.
CI/CD examples.
Environment variable reference.
Infrastructure-as-code examples.
Background job guidance.
Storage configuration.
Production checklist.

Final Decision Rule

The right question is not "how complex is my product today?" but "how expensive will it be to add what I need next?"

A minimal starter is fast to start and painful to grow. A modular starter lets you begin with only auth, billing,
and a dashboard — and add teams, admin, AI, or SSO when the product actually needs them.
With Codapult, you remove what you don't need via CLI. You don't add missing modules from scratch six months after launch.

The right boilerplate should help you launch faster without forcing a rewrite after the first serious customer.

Codapult was built against this checklist. If you want to verify it item by item, the compare page maps each capability to what ships in the box, including modules, adapters, infrastructure, and plugins.

ShipFast vs Supastarter vs MakerKit vs Codapult: Choosing a SaaS Starter in 2026

Vlad Zoff — Mon, 10 Aug 2026 18:33:44 +0000

SaaS starters are easy to compare badly.

The cheapest way is to count pages, components, or screenshots. That misses the part that decides whether the starter still helps after the first launch: how much of the product surface is already wired together, how much can be removed, and how painful it is to change providers later.

This comparison focuses on fit, not winner-takes-all scoring. ShipFast, Supastarter, MakerKit, and Codapult are built for different buyers.

Quick Positioning

ShipFast is optimized for solo founders who want to launch a simple product quickly. It is direct, lightweight, and intentionally close to the marketing-site-plus-checkout shape.

Supastarter is a polished modern starter with strong monorepo conventions and broad SaaS coverage. It is a good fit when you like its chosen stack and want a well-packaged application foundation.

MakerKit is strong when you want a mature starter ecosystem and multiple stack choices, especially if Supabase or Firebase is central to your plan.

Codapult is for builders who want to start lean and grow without a rewrite. The setup wizard removes the modules your MVP does not need — permanently, from the codebase. What you keep is fully integrated and can be toggled via environment variables as the product evolves. You decide the scope at setup time instead of bolting missing pieces on later.

The Real Buying Question

The question is not "which starter has the most features?"

The better question is:

Which starter removes the work you are least likely to differentiate on, without boxing in the work you do need to differentiate on?

If your product is a narrow one-person launch, a smaller starter can be better. Less code means fewer decisions.

If your product will need teams, support operations, billing changes, admin tools, and integrations, the smallest starter can become expensive after launch. You may spend the saved setup time rebuilding the operational layer.

Architecture

Look at what happens when the product changes.

Can you remove a module? Can you switch providers? Can you add a plugin? Can you keep the public marketing site, dashboard, admin panel, API routes, and database schema understandable?

Codapult is built around a few architecture choices:

App Router route groups for public, auth, dashboard, and admin surfaces.
Provider adapters for auth, payments, storage, jobs, notifications, embeddings, and vector search.
CLI setup wizard for permanently removing unused modules before you start building.
Environment variable flags for toggling kept modules on or off after setup.
MDX docs and blog on disk.
A plugin registry for larger optional capabilities.
Infrastructure paths for Vercel, Docker, Terraform, Pulumi, and Helm.

This is heavier than a minimal starter. The upside is that modules you keep are already integrated — no wiring needed when you turn them on.
Modules you remove are gone cleanly, with no dead code left behind.

Starting Simple with Codapult

Codapult ships with 70+ modules. That does not mean your project has to use all of them.

The CLI setup wizard lets you keep only what your MVP needs. A typical minimal start looks like:

Auth (email/password or OAuth)
Billing (one provider, one plan)
Dashboard (one route group for the logged-in user)
Admin (user list and subscription view)

Everything else — teams, AI, SSO, SCIM, audit logs, white-labeling — you either remove at setup via the CLI wizard (permanent, clean), or keep in the codebase and hide via an environment variable until the product needs it.

This is the difference between Codapult and a minimal starter: you are not adding missing modules after launch. You are removing modules you do not need yet.

Billing

Billing is where a lot of starters look similar until you need a second pricing model.

Basic subscription checkout is useful, but SaaS pricing often evolves:

One-time licenses.
Monthly and annual subscriptions.
Seats.
Add-ons.
Usage credits.
Trials.
Customer portal.
Webhooks.
Admin support workflows.

Codapult includes Stripe, LemonSqueezy, and Polar adapters. That matters less because of the provider names and more because billing code is not scattered across the app. The product can talk to a payment interface while the provider implementation stays behind it.

// Unified payment interface used across the entire application
export interface PaymentAdapter {
  createCheckoutSession(params: CheckoutParams): Promise<{ url: string }>;
  createCustomerPortal(customerId: string): Promise<{ url: string }>;
  handleWebhook(req: Request): Promise<WebhookResult>;
  refundPayment(params: RefundParams): Promise<RefundResult>;
}

Database

Database preference is personal and team-specific.

Turso and Drizzle are lightweight and fast to start with. PostgreSQL is familiar, widely hosted, and often preferred by teams selling to enterprise buyers. Prisma has a huge ecosystem. Supabase gives you a bundled platform.

The practical advice:

Pick Turso/Drizzle if you want a small TypeScript-first setup and like SQLite/libSQL ergonomics.
Pick PostgreSQL if your team or customers expect it.
Pick Supabase if managed auth/database/storage in one platform is the main value.
Pick Prisma if your team strongly prefers its schema/client workflow.

Codapult defaults to Turso/Drizzle but also documents PostgreSQL support through DB_PROVIDER=postgres. That makes the default opinionated without making the buyer feel locked in.

Plugins and Product Surface

Most SaaS products do not need every module on day one.

But many products eventually need one or more of these:

AI tooling.
CRM workflows.
Helpdesk workflows.
Email marketing.
Support analytics.
Admin operations.
Webhooks.
Feature requests.
Referrals.

Codapult treats larger optional capabilities as plugins where that boundary makes sense. The goal is not to turn every helper into a package.
The goal is to keep the core application usable while letting serious capabilities be added as plugins when the product needs them.
Plugins are separate from the core modules you select at setup — they can be installed independently at any point after launch.

When ShipFast Is the Better Choice

Choose ShipFast-style simplicity if:

You are a solo founder shipping one small app.
You do not expect enterprise workflows soon.
You value minimal code more than operational breadth.
You are comfortable adding missing modules yourself.
You want a fast marketing and checkout path.

That is a valid product strategy.

When Supastarter or MakerKit Is the Better Choice

Choose Supastarter or MakerKit when:

You like their stack choices.
You want a mature starter with strong conventions.
Supabase, Prisma, Firebase, or a specific monorepo shape is important.
You want a broad starter without Codapult's plugin-oriented packaging.

The best starter is often the one that matches your team's taste and habits.

When Codapult Is the Better Choice

Choose Codapult when:

You want to start with auth, billing, and a dashboard — and add teams, admin, AI, or SSO only when the product needs them.
You want AI, docs, blog, billing, webhooks, and infrastructure already represented.
You want to remove modules via CLI rather than add missing ones from scratch after launch.
You expect teams and organization-scoped data at some point.
You need admin operations for support, feature flags, or billing workflows.
You want swappable providers — auth, payments, storage — without rewriting app logic.
You may add CRM, helpdesk, email marketing, or AI platform features later (via plugins).

Codapult is less about the shortest path to a landing page and more about avoiding the second rebuild.

Decision Rule

Use the smallest starter that will survive the next version of your product.

If the next version is still one user, one plan, one dashboard, and one checkout, choose a smaller starter.

If the next version includes teams, operational support, provider changes, AI features, and customer-facing documentation, choose a starter that already has those boundaries.

If you are building a SaaS intended to evolve beyond a simple landing page without needing a complete rewrite down the road, explore the full architectural feature matrix and documentation on the Codapult comparison page.

I Spent $200 in API Credits Prompting an Agent to Build a Starter. Here’s Why I Still Clone Boilerplates.

Vlad Zoff — Thu, 30 Jul 2026 17:56:30 +0000

Last month I decided to test a simple hypothesis: with top-tier models like Claude Opus 4.8 and GPT-5.6 running inside CLI agents, is the SaaS boilerplate officially dead?

I opened a fresh directory, booted up an agentic loop, and asked it to scaffold a production-ready Next.js 16 app with Better-Auth, Stripe subscriptions, Tailwind v4, and Drizzle ORM.

Three hours and a $180 Anthropic invoice later, I had my answer.

The Brutal Math of Multi-File Context

When people say "AI coding is basically free," they are usually talking about generating a single UI component or a standalone utility function. That costs pennies.

That math completely falls apart the second you ask an agent to build a multi-page architecture across 30+ interconnected files.

Agentic workflows don't just write code—they inspect directory trees, run terminal checks, read type definitions, and edit files across multiple passes. Every time the agent makes a tool call, runs npm run build, or checks why a Server Component failed to re-render, it re-sends the entire repository context back into the model.

Add thousands of reasoning tokens per pass, and a single multi-turn session to wire up auth, session cookies, and Stripe webhooks easily burns through $150 to $300+ in raw API credits.

You are effectively paying AI providers hundreds of dollars to have an agent repeatedly re-invent standard authentication flows from scratch.

The Cohesion Problem: 70+ Modules Don't Just "Prompt" Together

Models like Opus 4.8 and GPT-5.6 are brilliant at generating localized logic. But a production SaaS isn't a collection of isolated files—it is a tightly coupled web of dependencies.

A real foundation requires 70+ modules and 30+ database tables all speaking the exact same language:

Auth & Identity: Better-Auth configured for Passkeys, 2FA, SSO, and multi-tenant Organizations.
Billing Lifecycles: Webhook handlers for both Stripe and LemonSqueezy, subscription seats, grace periods, and usage metering.
System Layer: Admin dashboards, granular RBAC, and i18n localization routing.

When you try to prompt an agent into building this graph from scratch, type drift is inevitable. The database schema slightly diverges from the session middleware; the RBAC checks miss an edge case in server actions; the payment webhooks break when a workspace ID is passed as undefined instead of a string.

Fixing these cross-module integration bugs requires constant back-and-forth prompts, burning through tokens just to get basic features to stop breaking each other.

The Day-2 Infrastructure Trap

Agents excel at building things that run on localhost:3000 via npm run dev. They are notoriously unreliable when preparing code for production infrastructure.

Getting a project ready for production means setting up Infrastructure as Code (IaC):

Valid Docker Compose files for local production mirrors.
Clean Terraform or Pulumi manifests.
Ready-to-deploy Kubernetes Helm charts.
Multi-database flexibility, like swapping between PostgreSQL and edge-ready Turso SQLite via an environment variable (DB_PROVIDER).

When you ask an agent to generate valid Helm charts or Terraform manifests alongside app code, it frequently hallucinates configuration keys or outputs outdated syntax. Debugging a failing deployment pipeline through an AI agent can cost $30 to $50 in API compute alone, purely spent fixing minor syntax errors in YAML and HCL files.

AI Code is a Dead-End Fork

Code generated by a prompt session is a static snapshot in time. It has no lineage and no upstream repository.

Six months from now, when Next.js introduces breaking API changes, Tailwind v4 releases a major patch, or security vulnerabilities surface in your auth dependencies, your AI-generated starter becomes instant technical debt. Your only recourse is to feed the whole codebase back into an agent and hope it doesn't break your custom business logic while refactoring.

A purpose-built boilerplate provides a Git upstream remote. When core security patches, framework migrations, or new features drop, you pull them directly with git pull upstream. You own a living codebase backed by an active maintainer, not an unmaintainable single-shot generation.

The Agent Baby-Sitting Tax

Even if API tokens were completely free, there is the time cost.

Current agents are fast, but they aren't autonomous enough for you to write one prompt and walk away while a full application builds itself. You are forced to sit at your terminal baby-sitting the process:

Reviewing diffs to make sure the agent didn't mess up Next.js 16's async request APIs (cookies(), headers(), or route params).
Approving terminal executions and watching builds fail because a webhook route missed a signature check.
Guiding the model through fixing subtle hydration mismatches between server and client states.

If you ever decide to customize the setup mid-build—for instance, removing multi-tenancy while keeping organization billing—asking an agent to refactor its own freshly written code usually results in broken imports and orphaned schema tables.

Compare that to running an interactive CLI installer like npx create-codapult, which prompts you for feature flags upfront and instantly outputs a clean, trimmed codebase in seconds.

Save Your Compute Budget for What Actually Matters

Top-tier models are incredible at writing complex, unique business logic that sets your product apart. Using high-reasoning compute to re-generate standard Stripe subscription lifecycles, Tailwind v4 configs, and DB schemas is a waste of capital.

You’re paying premium rates for the AI equivalent of laying a brick foundation.

Skip the Scaffolding Prompts

This is exactly why I built Codapult.

It is a clean, modular Next.js 16 SaaS starter designed to save you from prompt fatigue and context drain:

Complete Foundation: Better-Auth (Passkeys, SSO, 2FA), Stripe & LemonSqueezy billing, Tailwind v4, Drizzle ORM, and i18n out of the box.
Production Infrastructure: Pre-configured Docker, Terraform, Kubernetes Helm charts, and flexible DB routing (PostgreSQL / Turso SQLite).
Extensible Architecture: Need specialized capabilities later? Drop in official modules like the AI Kit, CRM, or Helpdesk without touching the core framework.
Maintainable Lifetime: Stay updated effortlessly via the Git upstream CLI workflow.

You run git clone or use npx create-codapult, drop in your .env variables, and start building actual features immediately.

Save your high-tier tokens for your core product.

Codapult includes a complete, production-ready Next.js 16 stack out of the box — Better-Auth, Stripe/LemonSqueezy billing lifecycles, Tailwind v4, Drizzle ORM, IaC configs, and modular plugins — saving you hundreds of dollars in API compute and hours of agent orchestration. Explore the architecture in the documentation.

How are you balancing agentic workflows with pre-built boilerplate architecture in your projects? Are you fully prompting, or cloning first?

SaaS Billing Models: Subscriptions, Seats, Credits, and Add-ons

Vlad Zoff — Tue, 07 Jul 2026 12:12:24 +0000

Billing is product strategy expressed in code. If your starter only handles a single checkout link, you will rebuild it as soon as pricing changes.

This article breaks down the billing models a SaaS foundation should support.

Flat Subscription

The simplest model is one plan, one recurring price.

Use it when:

The product has a clear single package.
Usage does not vary much across customers.
Support and infrastructure costs are predictable.

Implementation needs:

Checkout session.
Subscription created webhook.
Subscription updated webhook.
Subscription canceled webhook.
Customer portal.
Plan state in the database.

Tiered Plans

Most SaaS products need at least two paid tiers.

Typical differences:

Feature access.
Usage limits.
Support level.
Number of seats.
Data retention.
Integrations.

Store planId in your subscription table and map it to a local plan catalog. Do not rely on provider price IDs as your product logic.

Seat-Based Billing

Seat billing is common for B2B SaaS. It aligns price with customer team size.

You need:

Current seat count.
Optional max seat cap.
Member invite logic.
Checkout or subscription update flow.
Billing UI that explains renewal impact.

Usage Credits

Usage credits work well for AI, API calls, file processing, or metered workflows.

Track:

Total credits.
Used credits.
Reset date.
Usage events.
Budget alerts.
Overage policy.

Credits should be visible to the customer before they become a billing surprise.

Add-ons

Add-ons let you expand revenue without forcing every customer into a higher tier.

Examples:

Extra storage.
White-labeling.
Priority support.
Advanced analytics.
Additional AI credits.
Premium integrations.

Your checkout and subscription state need to support multiple line items, not just one plan.

Trials

Trials are useful when activation requires product usage. They are less useful when setup is complex and a sales conversation is needed.

If you support trials, store:

Trial end date.
Trial status.
Conversion events.
Reminder schedule.
Cancellation behavior.

One-Time Purchases

Some developer products sell lifetime access or source code licenses. That model needs different state than recurring SaaS:

License tier.
Project count.
Update period.
Support period.
Delivery workflow.
Receipt and access email.

Do not mix one-time license logic into recurring subscription code without clear types.

Webhooks Are the Source of Truth

Checkout success pages are not enough. Provider webhooks should update your database.

At minimum, handle:

Checkout completed.
Subscription created.
Subscription updated.
Subscription deleted.
Payment failed.
Refund.

Log webhook delivery and errors. Silent billing failures are expensive.

Admin Billing Support

Your admin panel should show:

User name and email.
Provider.
Plan ID.
Status.
Seat count.
Renewal date.
Cancellation state.

Support should not need direct database access to answer a billing question.

Pick the Model You Can Explain

The best billing model is not the most sophisticated one. It is the one customers understand and your system can enforce.

Start with the simplest model that matches value, but choose a codebase that can add seats, credits, add-ons, and trials when your pricing evolves.

Codapult ships billing adapters for Stripe, LemonSqueezy, and Polar with normalized webhook handling, subscription state in the database, seat tracking, usage credits, and a customer portal — switchable via PAYMENT_PROVIDER without touching application code. The payments docs show the integration points.

Auth, Teams, and RBAC in a Next.js SaaS App

Vlad Zoff — Tue, 07 Jul 2026 12:07:58 +0000

Authentication gets users into the app. Authorization decides what they can do once they are there. In SaaS products, the second part is where many starters are too thin.

This guide covers the practical model: platform roles, organization roles, protected routes, admin access, and future enterprise needs.

Start with the User Record

Keep the user record to identity only — id, name, email, verification state, avatar, platform role, 2FA state, timestamps. Nothing organization-specific belongs here, because the same person can be an owner in one workspace and a viewer in another. The moment you store a permission field directly on the user, you've hard-coded an assumption that breaks the first time someone joins a second organization.

Add Platform Roles

Platform roles are global. Most apps only need:

user.
admin.

The admin role controls platform screens such as /admin/users, /admin/subscriptions, and /admin/feature-flags.

Do not use platform admin for customer workspace permissions.

Add Organization Memberships

Organization roles should answer what a user can do inside one workspace:

owner: billing, members, settings, deletion.
admin: most management actions except ownership transfer.
member: normal product usage.
viewer: read-only access.

This gives you enough granularity without creating a complex permission system too early.

Protect Routes at Multiple Layers

Route protection should happen in more than one place:

Middleware or proxy redirects unauthenticated users.
Layouts block protected app areas.
Server actions verify the session.
API routes verify the session.
Admin operations verify platform role.
Organization operations verify membership and org role.

The UI can hide buttons, but the server must enforce permissions.

Keep Auth Pages Out of Search

Sign-in, sign-up, dashboard, and admin pages should not be indexed. They are not acquisition pages, and search engines do not need them.

Use:

robots metadata with index: false.
robots.txt disallow rules for protected paths.
Sitemap exclusion for auth-only pages.

This keeps SEO focus on marketing, docs, blog, pricing, and comparison pages.

Plan for Enterprise Auth Without Building It Too Early

Enterprise customers often ask for:

SAML SSO.
SCIM provisioning.
Enforced 2FA.
Audit logs.
Domain verification.
Custom session policies.

You do not need to ship every enterprise feature on day one. You do need a data model that can add them without rewriting auth and teams.

Support Impersonation Carefully

Impersonation is powerful for support, but it is sensitive.

Rules:

Only platform admins can impersonate.
Show a visible impersonation banner.
Log the impersonation start and end.
Never let impersonation bypass destructive confirmation steps silently.
Avoid using impersonation for billing provider actions when possible.

Test the Permission Matrix

Write tests for:

Anonymous user access.
Authenticated user access.
Admin-only routes.
Owner-only organization settings.
Member actions.
Viewer restrictions.
Locale-prefixed protected routes.

Auth regressions are high-risk because they often expose data, not just break UI.

The Practical Baseline

None of this is exotic. A real auth provider, protected routes at every layer, a platform admin role, an organization membership table with roles, server-side permission checks, audit logging, and noindex on anything that isn't marketing. That's the baseline that survives contact with a real customer — not an enterprise IAM project, just enough structure that adding SSO later doesn't mean rewriting how permissions work.

Codapult includes this full auth and teams layer out of the box — email/password, OAuth, magic links, TOTP 2FA, SAML SSO, organizations, RBAC, invitations, protected routes and audit logs — switchable between Better-Auth and Kinde via one environment variable. Explore the implementation map in the authentication docs.

Designing Removable Modules in a Next.js SaaS Starter

Vlad Zoff — Tue, 07 Jul 2026 12:03:15 +0000

Most SaaS starters say they are modular.

The useful question is: what happens when you remove a module?

If disabling a feature leaves dead navigation links, broken sitemap entries, missing imports, route handlers that still accept requests, or database tables nobody understands, the module was not really modular. It was just grouped in a folder.

Removable modules need boundaries.

Start With User-Facing Surfaces

A module usually shows up in more places than its main page suggests. Take a waitlist feature: there's the public signup route, sure, but also an admin view, an API route, a database table, an email template, a navbar link, a footer link, a sitemap entry. Delete the public page and the feature is still there — just invisible until someone hits the API route directly or wonders why waitlist_entry is sitting in the schema.

Feature Flags Are Not Enough

Feature flags hide behavior at runtime.

They do not remove code.

That distinction matters. Runtime flags are useful for:

Hiding navigation.
Returning 404 for disabled routes.
Removing sitemap entries.
Preventing API access.
Running one codebase in multiple modes.

But if a buyer wants a smaller codebase, the setup tool also needs to delete files and update references.

A good starter supports both:

Feature flags for runtime control.
Pruning for permanent removal.

Route Groups Help

Next.js App Router route groups are useful for keeping surfaces understandable:

src/app/[locale]/
  (marketing)/
  (auth)/
  (dashboard)/
  admin/

That structure makes it clear which pages are public, protected, authentication-only, or platform admin.

It also lets you reason about SEO. Marketing pages are indexable. Auth, dashboard, and admin pages should be noindex and blocked where appropriate.

Keep Shared Code Honest

The hardest modules to remove are the ones that leak into shared files.

Common leak points:

navigation.ts.
sitemap.ts.
robots.ts.
proxy.ts.
Shared schema files.
Shared validation schemas.
Shared server actions.
Shared dashboard layouts.

If a module needs entries in those files, make the entries obvious and grouped. If a setup wizard removes the module, it should know exactly what to prune.

API Routes Need Gates Too

Disabled UI is not security.

If a module has API routes, those routes need their own gates:

Auth check.
Permission check.
Rate limit.
Feature flag check.
Input validation.

The proxy can return 404 for disabled feature routes, but route handlers should still follow the same protected pattern. That keeps modules safe when moved, copied, or extended.

Database Tables Should Be Named by Domain

Module data should be easy to identify.

Good table names:

waitlist_entry.
feature_request.
audit_log.
outgoing_webhook.
workflow.

Ambiguous table names make removal riskier. If the table name tells you the module, migration work is easier to review.

Tests Should Prove Removal Boundaries

Useful tests include:

Disabled feature returns 404.
Disabled feature is absent from sitemap.
Disabled feature is absent from navigation.
API route rejects unauthenticated access.
Module-specific queries still work when enabled.

You do not need massive coverage for every module. You need enough tests to prevent obvious leaks.

Plugins Are for Bigger Boundaries

Not every removable feature should be a plugin.

A simple waitlist page can be a module.

A CRM with pages, routes, hooks, schema, components, AI helpers, and install commands is a better plugin candidate.

Use plugins when the feature has its own lifecycle and customer value. Use modules when the feature is part of the core application shape.

None of this needs to be exhaustive. It needs to be enough that "modular" describes the codebase instead of describing the marketing copy.

The Payoff

Removable modules give buyers confidence.

They can start broad, then strip what they do not need. Or they can keep a larger operational surface without building it themselves.

The codebase stays understandable because module boundaries are explicit.

Codapult documents removable features in the modules overview, including routes, dependencies, and manual removal notes.

Turso + Drizzle vs PostgreSQL + Prisma for a SaaS Boilerplate

Vlad Zoff — Tue, 07 Jul 2026 12:01:23 +0000

Database choices in SaaS starters are more emotional than they should be.

Turso, PostgreSQL, Drizzle, Prisma, Supabase, Neon, and SQLite all have real strengths. The right choice depends on what the starter optimizes for: local setup, operational familiarity, edge reads, schema control, ecosystem, or enterprise expectations.

This is not a purity argument. It is a trade-off map.

Turso + Drizzle

Turso is hosted libSQL, a SQLite-compatible database with cloud features. Drizzle is a lightweight TypeScript ORM with explicit schema definitions and SQL-like query builders.

The appeal:

Simple local development with file:local.db.
Fast setup for new projects.
Lightweight query layer.
TypeScript-first schema and query types.
Good fit for many SaaS workloads that do not need heavyweight relational operations on day one.
Multi-region read replica story through Turso.

The cost:

Some teams are less familiar with SQLite/libSQL in production.
PostgreSQL has a larger ecosystem.
Enterprise buyers may ask for Postgres by default.
Some third-party tools assume Postgres.

Turso + Drizzle is a strong default when you value small setup and explicit TypeScript code.

PostgreSQL + Prisma

PostgreSQL is the familiar production default for many SaaS teams. Prisma is widely adopted and has a comfortable schema/client workflow.

The appeal:

Very familiar to engineering teams.
Huge hosting ecosystem: Neon, Supabase, RDS, Railway, Render, Fly, and more.
Strong relational feature set.
Many analytics, BI, and integration tools support it directly.
Prisma has excellent discoverability and a large community.

The cost:

Prisma can add more abstraction than some TypeScript teams want.
Generated clients and migrations introduce their own workflow.
Local setup can be heavier than an SQLite file.
Switching away from Prisma later is rarely free.

PostgreSQL + Prisma is a strong default when team familiarity and ecosystem matter more than minimal setup.

PostgreSQL + Drizzle

This middle path is increasingly attractive precisely because it refuses to pick a side: you get PostgreSQL's familiar hosting story and Drizzle's thinner query layer. The trade-off is that you still need a real Postgres instance for local dev — no single-file convenience — and Drizzle's ecosystem, while growing, is smaller than Prisma's. For teams that think in SQL, this is often the most pragmatic option on the table.

What a SaaS Starter Should Do

A starter should make the default easy without pretending it is universal.

The docs should answer:

What database is default?
How do I run locally without a cloud account?
How do migrations work before and after production data exists?
Can I use PostgreSQL?
If PostgreSQL is supported, which env vars change?
Which schema file is the source of truth?
What are the trade-offs?

The worst answer is silence. Buyers interpret silence as lock-in.

Migration Workflow Matters

For a fresh database, db:push is convenient.

For production data, generated migrations are safer.

That distinction should be explicit:

# Fresh local database
pnpm db:push

# Production changes
pnpm db:generate
pnpm db:migrate

Most SaaS teams can start fast and become stricter when real data appears.

Query Code Should Stay Boring

Regardless of provider, application code should import one database client:

import { db } from '@/lib/db';

The app should not know whether the active provider is Turso or PostgreSQL. Provider selection belongs in database initialization, not in every route handler.

That boundary matters more than the default.

The Practical Recommendation

If fast local setup and multi-region reads matter most, start with Turso + Drizzle. If your team already knows Postgres, or your customers expect it, use Postgres — with Prisma if you want the generated-client ergonomics, or Drizzle if you'd rather write something closer to SQL. None of these is objectively correct. The mature answer isn't "this database is best" — it's picking a sensible default and documenting the escape hatch.

Codapult defaults to Turso + Drizzle and documents PostgreSQL via DB_PROVIDER=postgres; the database docs cover setup and migration paths.

The Payment Adapter Pattern in Next.js: Stripe, LemonSqueezy, and Polar Without App-Wide Rewrites

Vlad Zoff — Tue, 07 Jul 2026 11:33:39 +0000

Most SaaS apps start with one payment provider.

That is fine. The mistake is letting that provider become the architecture.

If Stripe-specific objects leak into pages, server actions, admin tools, and webhook handlers, switching to LemonSqueezy or Polar becomes a rewrite. Even adding one-time products next to subscriptions can become awkward.

The payment adapter pattern keeps provider details behind a small interface.

The Shape of the Problem

Payment code tends to sprawl fast: pricing CTAs, authenticated checkout, one-time marketing checkout, billing portal links, webhooks, refunds, seat changes, usage credits. Import a provider SDK directly in even half of these, and every feature becomes provider-aware — which means every provider migration becomes an app-wide grep.

If each layer imports a provider SDK directly, every feature becomes provider-aware.

That makes the code harder to test and harder to change.

A Small Interface Is Enough

You do not need a large abstraction. Start with the operations the app actually performs:

export interface PaymentAdapter {
  createCheckout(params: CheckoutParams): Promise<string>;
  createMarketingCheckout(params: MarketingCheckoutParams): Promise<string>;
  createPortalSession(customerId: string): Promise<string>;
  handleWebhook(payload: string, signature: string): Promise<WebhookResult>;
  refundPayment(params: RefundParams): Promise<RefundResult>;
}

The rest of the app imports getPaymentAdapter() instead of stripe, lemonsqueezy, or polar.

const adapter = await getPaymentAdapter();
const checkoutUrl = await adapter.createCheckout({
  planId: 'pro',
  interval: 'monthly',
  seats: 5,
  customerId,
});

That one boundary gives you room to change providers without changing every caller.

Keep Plans Provider-Neutral

Plan definitions should describe your product, not your provider.

export const plans = [
  {
    id: 'pro',
    name: 'Pro',
    price: { monthly: 19, yearly: 190 },
    limits: { projects: 'unlimited', aiCredits: 5000 },
  },
] as const;

Provider-specific IDs belong in environment variables or provider mapping code:

PAYMENT_PROVIDER="stripe"
STRIPE_PRICE_PRO_MONTHLY="price_..."

# or
PAYMENT_PROVIDER="polar"
CHECKOUT_VARIANT_PRO="..."

This lets the app reason about pro while the adapter handles provider IDs.

Marketing Checkout Is Different

Authenticated SaaS checkout usually attaches a customer, organization, subscription, and return URL.

Marketing checkout may sell source-code licenses or plugins before the buyer has an account.

That path needs its own method:

await adapter.createMarketingCheckout({
  productKey: 'plugin-ai-kit',
  successUrl,
  cancelUrl,
});

The pricing page can route to /api/checkout?product=plugin-ai-kit, and the route can call the active adapter.

If you prefer direct hosted checkout URLs, keep those as the simpler path:

CHECKOUT_URL_PLUGIN_AI_KIT="https://provider.example/buy/plugin-ai-kit"

In Codapult, CHECKOUT_VARIANT_* wins over CHECKOUT_URL_*, so API checkout is used when a provider variant exists and direct links remain available as fallback.

Webhooks Need Normalized Events

Provider webhooks are not interchangeable.

Stripe, LemonSqueezy, and Polar use different event names, payload shapes, signature headers, and product identifiers. The adapter should normalize those into app-level events.

type WebhookResult =
  | { type: 'subscription.updated'; subscriptionId: string; customerId: string }
  | { type: 'subscription.deleted'; subscriptionId: string }
  | { type: 'payment.refunded'; paymentId: string }
  | { type: 'ignored' };

The route validates rate limits and signature, then passes the normalized result to application code.

What Not to Abstract

Do not hide every provider feature.

Stripe Connect, LemonSqueezy licensing, and Polar's Merchant of Record model are not identical. If you need a provider-specific feature, keep it explicit at the edge of the adapter.

Good adapters remove duplication. Bad adapters pretend different products are the same.

The Payoff

With this boundary in place, pages don't import provider SDKs, webhook routes normalize events before they hit application code, and tests mock one interface instead of three. Switching providers becomes a config change and an adapter update — not a rewrite.

Codapult includes Stripe, LemonSqueezy, and Polar payment adapters; the payments docs show the provider switch and checkout paths.