Why We Decoupled Clients from Orders: Architecture Lessons from Building a SaaS Portal
When building an MVP, speed is everything. You take shortcuts, design flat schemas, and ship as fast as possible. In our early iterations of ClientStatus - a platform designed to provide lightweight, zero-login project
When building an MVP, speed is everything. You take shortcuts, design flat schemas, and ship as fast as possible.
In our early iterations of ClientStatus - a platform designed to provide lightweight, zero-login project and order tracking portals for clients - we made a classic architectural assumption:
1 Client = 1 Portal / Order.
It seemed clean at the time: a business creates a "client", sets a status, shares a private token link, and syncs updates via Google Sheets.
Within a month of real usage, that assumption completely broke down. Here is how it failed, why we had to decouple our core domain model, and the lessons learned along the way.
1. The Naive Model: Why It Looked Fine at First
In version 1.0, our data model treated the client and their active job as the exact same record:
// The initial naive model (1.0)
public class Client
{
public Guid Id { get; set; }
public Guid WorkspaceId { get; set; }
public string Name { get; set; } = string.Empty;
public string Email { get; set; } = string.Empty;
public string Status { get; set; } = "In Progress";
public int ProgressPercentage { get; set; }
public string ShareToken { get; set; } = string.Empty; // Public link
public List<Milestone> Milestones { get; set; } = new();
public List<Attachment> Deliverables { get; set; } = new();
}
This let us ship quickly:
- One API endpoint:
GET /api/clientsreturned everything. - One public endpoint:
GET /api/portal/{token}served the client view. - Single row in Google Sheets per job.
2. Where the Naive Model Broke Down
The moment real agencies, repair workshops, and freelancers started using the platform with real clients, three major friction points emerged:
Friction A: Returning Clients
What happens when an agency finishes a website for Acme Corp, and three weeks later Acme Corp orders an SEO audit?
- Under the old model, the agency had to either overwrite the old project (wiping historical deliverables and timelines) or create a duplicate client named "Acme Corp (SEO)".
- The user list became cluttered with duplicates:
Acme Corp,Acme Corp 2,Acme Corp - Q4.
Friction B: Multiple Concurrent Jobs
A design studio often works on multiple simultaneous deliverables for the same client (e.g., "Brand Guidelines" and "Packaging Design"). Having multiple independent statuses for the same client contact became impossible without clunky workarounds.
Friction C: Integration & Sync Mismatches
Our Google Sheets connector allows teams to sync statuses directly from their spreadsheets. Because clients and orders were merged, changing a client's email or phone number in one row caused desynchronization across other rows for the same client.
3. The New Architecture: Clients vs. Orders
In version 1.1, we decoupled the domain into two distinct aggregates:
- Client: Represents the long-term relationship (identity, contact details, company name, notes, and aggregate history).
- Order / Project: Represents the transient deliverable (status timeline, milestones, progress percentage, attachments, and the unique public share token).
// Decoupled Domain Architecture (1.1+)
public class Client
{
public Guid Id { get; set; }
public Guid WorkspaceId { get; set; }
public string Name { get; set; } = string.Empty;
public string Email { get; set; } = string.Empty;
public string Company { get; set; } = string.Empty;
public DateTime CreatedAt { get; set; }
// Navigation collection
public ICollection<Order> Orders { get; set; } = new List<Order>();
}
public class Order
{
public Guid Id { get; set; }
public Guid WorkspaceId { get; set; }
public Guid ClientId { get; set; }
public Client? Client { get; set; }
public string Title { get; set; } = string.Empty;
public string Status { get; set; } = "Draft";
public int ProgressPercentage { get; set; }
public string ShareToken { get; set; } = string.Empty; // Scoped public token
public ICollection<Milestone> Milestones { get; set; } = new List<Milestone>();
public ICollection<Attachment> Attachments { get; set; } = new List<Attachment>();
public DateTime UpdatedAt { get; set; }
}
4. Solving the Migration: Zero Broken Links
The biggest challenge when refactoring a live SaaS database is backwards compatibility.
Hundreds of active client portals (https://clientstatus.cloud/c/{token}) were already shared via WhatsApp, emails, and SMS with real end-clients. We could not allow a single link to return a 404.
Here is how we executed the migration safely:
-
Automated Data Backfill:
- For every legacy
Clientrecord, we extracted the active job metadata into a newOrderentity. - We preserved the exact
ShareTokenon the newOrderrecord. - We linked
Order.ClientIdback to the existingClient.Id.
- For every legacy
-
Deduplication Pass:
- When multiple legacy records shared the same workspace and contact email, we merged them into a single primary
Clientrecord and attached all resultingOrdersto it.
- When multiple legacy records shared the same workspace and contact email, we merged them into a single primary
-
Routing & Resolution Layer:
- The public portal endpoint
GET /api/portal/{token}was updated to resolve againstOrders:
- The public portal endpoint
app.MapGet("/api/portal/{token}", async (string token, AppDbContext db) =>
{
var order = await db.Orders
.Include(o => o.Client)
.Include(o => o.Milestones)
.Include(o => o.Attachments)
.AsNoTracking()
.FirstOrDefaultAsync(o => o.ShareToken == token);
if (order is null)
return Results.NotFound(new { message = "Portal not found." });
return Results.Ok(PortalDto.FromEntity(order));
});
Every previously generated token resolved immediately to the corresponding order without any change required from end users or their clients.
5. What This Unlocked
Separating clients from orders immediately unlocked several high-value features:
- Repeat Orders in 1 Click: Users can open any client profile and immediately click "New Order", with client branding and contact details auto-filled.
-
Dedicated Order Dashboards: Users can now filter by order status (
Draft,In Progress,Review,Completed) independently of client lists. -
Cleaner Google Sheets Sync: Spreadsheets now map cleanly to order rows, linked by
ClientIdor customer email. - Granular Access Control: Permissions and comments can be scoped to individual orders rather than exposing an entire client history.
6. Key Takeaways for SaaS Builders
- Never conflate an actor with a transaction: A customer is an enduring entity; a project or order is an ephemeral state machine. Even if you think "my users only ever have one active project at a time", they will eventually have repeat business.
-
Decouple public tokens from entity IDs: By using an independent, randomly generated
ShareTokencolumn instead of raw database IDs, we could relocate the token fromClientstoOrderswithout breaking external consumer URLs. - Keep public links frictionless: The biggest strength of ClientStatus is that end-clients don't need to log in to see where their order stands. If you build client-facing tools, minimize authentication friction wherever possible.
You can check out how the portal experience works in our live demo portal (no login or signup required).
Have you had to perform similar entity splits in your production databases? How did you handle schema migration and legacy URL routing? Let's discuss in the comments!
Originally published by Dev.to WebDev. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.