Upstreams vs Domains

One of the first concepts to understand in Hostgrid is the difference between upstreams and custom domains.

They work together, but they represent two very different parts of the system.

The simple distinction

At a high level:

A domain is what your customers type in the browser
An upstream is where your application actually runs

customer.com  →  your application (via Hostgrid)

Hostgrid sits in between and connects the two.

What is a custom domain?

A custom domain is the public URL your users visit.

For example:

customer.com
crm.customer.com
app.client-site.com

This is what appears in the browser.

A domain is responsible for:

Receiving incoming traffic
Being verified via DNS
Having SSL enabled (automatically in Hostgrid)
Being mapped to an upstream

A domain does not run your application — it only points to it through Hostgrid.

What is an upstream?

An upstream is your actual application endpoint.

For example:

app.saas.com
api.yourapp.com
backend.internal.service

This is where Hostgrid sends requests after processing them.

An upstream is responsible for:

Running your application
Handling business logic
Returning responses to Hostgrid

Hostgrid never replaces your upstream — it connects traffic to it.

How they work together

A domain is always connected to exactly one upstream.

But an upstream can serve many domains.

                Upstream
            app.saas.com
                  │
     ┌────────────┼────────────┐
     │            │            │
     ▼            ▼            ▼
customer.com   client.com   portal.com

All these domains can point to the same application.

Request flow (end-to-end)

When a user visits a domain, this is what happens:

Visitor
   │
   ▼
customer.com (custom domain)
   │
   ▼
Hostgrid (reverse proxy)
   │
   ▼
app.saas.com (upstream)
   │
   ▼
Response returned via Hostgrid
   │
   ▼
Visitor sees customer.com

Important detail:

The browser always stays on the custom domain. The upstream is never exposed directly to the user.

Why this separation exists

Splitting domains and upstreams gives you flexibility:

1. Multiple domains → one app

You can serve many customer domains from one application.

customer-a.com → app.saas.com
customer-b.com → app.saas.com

This is common in multi-tenant SaaS.

2. Multiple upstreams → different systems

You can route different domains to different backends.

store.com → store-backend.saas.com
docs.com  → docs-backend.saas.com

This is useful when services are separated.

3. Independent lifecycle

Domains and upstreams change at different rates:

Domains are added/removed by customers
Upstreams are managed by your engineering team

Hostgrid keeps them decoupled.

What Hostgrid actually does

Hostgrid is the layer that connects domains and upstreams by:

Verifying domain ownership (DNS)
Issuing SSL certificates
Accepting HTTPS requests
Applying routing rules
Forwarding requests to the upstream
Returning responses to the browser

Common mental model

If you’re new to this, this analogy helps:

Domain = address (what users type)
Upstream = building (where your app lives)
Hostgrid = postal system + security + routing layer

Key takeaway

Domains and upstreams are separate by design:

Domains are how users access your app
Upstreams are where your app actually runs
Hostgrid connects the two securely and dynamically

Next steps

To go deeper: