Dev.to WebDev 🛠 Dev 👁 0 📖 5 min read

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/clients returned 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:

  1. Client: Represents the long-term relationship (identity, contact details, company name, notes, and aggregate history).
  2. 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:

  1. Automated Data Backfill:

    • For every legacy Client record, we extracted the active job metadata into a new Order entity.
    • We preserved the exact ShareToken on the new Order record.
    • We linked Order.ClientId back to the existing Client.Id.
  2. Deduplication Pass:

    • When multiple legacy records shared the same workspace and contact email, we merged them into a single primary Client record and attached all resulting Orders to it.
  3. Routing & Resolution Layer:

    • The public portal endpoint GET /api/portal/{token} was updated to resolve against Orders:
   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 ClientId or 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

  1. 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.
  2. Decouple public tokens from entity IDs: By using an independent, randomly generated ShareToken column instead of raw database IDs, we could relocate the token from Clients to Orders without breaking external consumer URLs.
  3. 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!

📰 Read the original article on Dev.to WebDev

Originally published by Dev.to WebDev. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.