Cortensor Portal V1 Detailed Spec 05 - Portal Backend / Control Plane
Status
Draft
Purpose
This document defines the custom backend responsibilities for Cortensor Portal V1.
Even with Clerk or Supabase Auth, Supabase DB, and Unkey, Portal V1 still needs a dedicated Portal backend / control plane that owns product logic and coordinates all major systems.
This backend is what turns the Portal from a set of services into a coherent product.
1. Summary
The Portal backend is the product brain for V1.
It should coordinate:
auth identity
durable Portal data
API key lifecycle
quota and entitlement checks
router-pool routing
usage emission
admin actions
The architecture is not:
client -> Unkey -> router
It is:
client -> Portal backend -> product logic + enforcement + routing -> router pool
This distinction matters because the Portal backend owns the Cortensor-specific product semantics, not Unkey and not the routers.
2. Goals
Portal Backend / Control Plane should aim to:
centralize Cortensor-specific business logic
keep the external API stable while the router fleet evolves
support quota, entitlement, and routing logic in one owned layer
support durable usage and billing write coordination
keep infrastructure details hidden from the customer-facing API surface
give the team a clean place to evolve product behavior over time
3. Core Responsibilities
The Portal backend should own:
authenticated dashboard APIs
API key create and revoke flows
key ownership checks
model entitlement checks
plan checks
quota checks
router-pool selection
request normalization
response normalization
request tracing
usage event emission
durable write orchestration
basic admin control surfaces
This means the Portal backend is the place where:
product logic lives
external request behavior is defined
infrastructure is translated into product behavior
4. Why This Layer Must Exist
Without a custom Portal backend:
business logic becomes fragmented
product semantics leak into infrastructure layers
routing becomes harder to evolve
durable usage ownership becomes unclear
auth, usage, API keys, and routing become spread across too many systems
the customer-facing API becomes harder to keep stable as backend topology changes
The custom backend is what makes Portal a real product, instead of a thin wrapper around third-party services and router pools.
5. Role in the Overall Architecture
The Portal backend sits between:
the user-facing Portal web app and hosted API surface, and
the backend Cortensor inference infrastructure
Conceptually:
Upstream
Portal web app
customer programmatic API clients
Lateral dependencies
Auth provider (Clerk or Supabase Auth)
Supabase DB
Unkey
Downstream
managed router pools
future fleet-health and admin systems
durable usage / billing pipelines
It is the coordination layer that translates:
user/account/product state into
request-time inference behavior
6. Backend Interfaces
The backend will likely expose two broad categories of APIs.
6.1 Dashboard / Control-Plane APIs
Used by the Portal web app for:
current user info
usage view
key list
create key
revoke key
billing or plan info
profile info
product metadata such as supported models
These are account- and product-facing APIs.
6.2 Hosted Inference Gateway APIs
Used by customers programmatically for:
hosted inference requests
key-authenticated API access
These APIs should:
accept Portal-issued keys
validate entitlement and quota
normalize product model names
forward requests to managed router pools
return product-stable responses
7. Coordination Responsibilities
The Portal backend should coordinate:
Auth provider
identity/session validation
user identity mapping
Supabase
durable product state
account data
key metadata
usage / billing ledger
request logs
pool metadata
Unkey
key verification
revocation-aware checks
rate-limiting support
fast request-path checks
Router pools
inference execution
request forwarding
backend pool selection
This coordination layer is essential because none of those systems alone represents the complete Portal product.
8. Request Normalization
One of the Portal backend’s most important responsibilities is normalization.
The backend should normalize:
incoming product model names
request metadata
request IDs
response shape if needed
error semantics
Why normalization matters
The Portal’s public API should stay stable even if:
router pool topology changes
model-to-session mapping changes
router response shape changes slightly
internal backend routing changes over time
That means the Portal backend should act as the compatibility layer between:
stable product semantics, and
evolving backend infrastructure
Examples of normalization
map:
gemma-4-26boss-20bqwen-...to internal router pool references
generate request IDs consistently for:
request logs
dashboard support views
future tracing / correlation
ensure customer-facing errors are:
stable
product-oriented
not raw router internals unless explicitly desired
9. Request Flow Ownership
For a hosted inference request, the Portal backend should own the product-facing request flow.
High-level V1 flow:
receive request
validate auth / key identity
check key ownership and status
check rate-limit state
check plan / quota
check model entitlement
resolve model alias to router pool
select backend target
forward request
receive backend response
normalize response if needed
emit usage event
coordinate durable writes
Even if some of these steps are delegated to helpers or services, the ownership of the overall flow remains Portal-side.
10. Durable Write Coordination
The backend should trigger or coordinate:
usage event writes
request log writes
billing ledger writes
last-used or activity updates when supported
Some writes may be synchronous, others asynchronous, but the ownership should still be Portal-side.
Why this matters
Usage and billing records must have a clear owner.
If the Portal backend does not own this coordination, then:
it becomes unclear which system is the source of truth
metering becomes harder to reconcile
account-level usage views become harder to trust
Synchronous vs Asynchronous
This is not fully decided yet, but likely:
synchronous or near-synchronous
request log seed / request ID creation
minimal usage event emission
asynchronous
billing ledger rollups
analytics enrichment
some “last used” decorations
The exact split can be refined later, but ownership should remain clear.
11. Product Logic That Must Stay in the Backend
The Portal backend should remain the place where the following product logic lives:
which account owns which keys
which models a user or org can access
what quota semantics apply
what a “free plan” means in practice
what router pool should serve a request
how errors should be presented to the user
how usage should be recorded
These are Portal product rules, not generic auth/gateway behaviors.
That is why they should not be pushed fully into:
routers
Unkey
Supabase-only logic
frontend-only logic
12. Admin Responsibilities
The backend should support basic operational actions such as:
disable key
disable account
disable model
drain pool
pause access
These actions do not all need full customer-facing UI in V1, but the backend should be structured with them in mind.
Why this matters in V1
Even if the frontend admin UI is limited at launch, the backend should already be capable of supporting basic operational controls so the system can be safely managed when:
a model misbehaves
a pool needs maintenance
an account must be paused
a key must be invalidated immediately
13. Backend Data Dependencies
The backend depends on durable data in order to behave consistently.
It likely needs direct or indirect access to:
users
organizations
organization membership
API key metadata
model access policy
plan/subscription state
router pool metadata
request logs
usage events
billing ledger
This does not mean all of these must be loaded synchronously on every request.
It means the backend is the owner of the logic that interprets these data structures.
14. Constraints for V1
The Portal backend should stay intentionally narrow in V1.
Good V1 constraints
one clear request flow
one primary hosted inference path
narrow model catalog
simple entitlement logic
simple quota model
lightweight admin controls
stable request and response shape
Avoid in V1
too many branching product rules
deeply dynamic backend behavior
multiple overlapping quota systems
full internal platform orchestration before the product core is stable
The first version should emphasize coherence over completeness.
15. Open Questions
Open questions for later refinement:
how much response normalization should Portal do vs pass through from routers?
which writes must be synchronous?
how much admin surface is required at launch?
how much router-pool health logic should live in this layer vs a separate fleet manager?
should some product checks be cached in fast state instead of recomputed from durable state every time?
These should be resolved while keeping the core backend responsibilities stable.
16. Relationship to Other Specs
This spec connects directly to:
02-auth.md03-api-key-management.md04-free-plan-rate-limits-and-gateway.md06-data-model-and-durable-state.md07-router-pools-and-model-product-layer.md08-usage-metering-and-billing.md09-admin-and-ops.md
The Portal backend is the layer that ties those concerns together, so this spec should be treated as one of the most central V1 backend docs.
17. Working Summary
The Portal backend is the product brain for Cortensor Portal V1.
It exists because the Portal cannot simply be:
auth + database + API key vendor + routers
It needs a layer that owns:
Cortensor-specific business logic
request-time product behavior
routing decisions
durable usage coordination
stable product semantics
In one sentence:
The Portal backend / control plane is the owned product logic layer that turns auth, API keys, quotas, and router pools into one coherent hosted Cortensor API experience.
Last updated