Cortensor Portal V1

Architecture & Implementation Approach

Status: Draft V1 page Scope: First production-oriented version of Cortensor Portal Goal: Define the initial implementation shape for a hosted Cortensor API product

---

1. Overview

Cortensor Portal V1 is intended to be the first hosted product surface for Cortensor.

Instead of asking users to run their own router nodes and surrounding infrastructure, Portal V1 provides a managed developer experience where users can:

• sign up and authenticate

• create and revoke API keys

• call a hosted inference API

• access a small curated model catalog

• view usage, limits, and basic account state

The V1 mental model is:

A hosted inference API backed by managed Cortensor router pools

---

2. V1 Architecture Summary

The recommended V1 implementation shape is:

• Auth layer: Clerk or Supabase Auth

• Durable product/control-plane DB: Supabase

• API key issuance, verification, rate limiting, and basic per-key usage visibility: Unkey

• Custom Portal backend for product/business logic

• Managed router pools as the inference backend

• Dedicated-backed sessions underneath for predictable model serving

In one line:

Portal V1 = Clerk or Supabase Auth + Supabase DB + Unkey + custom business logic + managed Cortensor router pools

This is a good fit for the first version because it balances:

• speed to MVP

• reasonable productization

• fast hot-path enforcement

• enough architectural flexibility for later evolution

It also avoids:

• putting business logic inside router nodes

• exposing raw routers directly to customers

• relying on raw DB reads on every inference request

• overbuilding a heavy gateway stack too early

---

3. V1 Component Roles

3.1 Auth Layer – Clerk or Supabase Auth

Portal V1 can reasonably use either Supabase Auth or Clerk for authentication.

Option A – Supabase Auth

Supabase Auth is a strong choice if Portal V1 wants a more unified stack where auth and durable product data live close together.

This makes Supabase attractive if the team wants:

• fewer vendors in the first version

• tighter integration between auth and Portal data

• a simpler platform footprint early on

Option B – Clerk

Clerk is a strong choice if Portal V1 wants a more specialized authentication layer with polished auth UX.

This makes Clerk attractive if Portal V1 wants:

• strong out-of-the-box auth UX

• a more productized auth experience from day one

• support for both Web2 and Web3 login paths

Practical V1 Interpretation

This means Portal V1 can be built in one of two main ways:

• Supabase Auth + Supabase DB + Unkey + custom Portal backend

• Clerk + Supabase DB + Unkey + custom Portal backend

The choice mostly depends on whether the team prefers:

• a more unified platform stack early (Supabase Auth), or

• a more specialized auth layer early (Clerk).

---

3.2 Supabase DB

Supabase should be used for durable product and account state.

Good V1 uses:

• user and organization records

• API key metadata

• plan / entitlement records

• usage events

• request logs

• billing ledger

• model access policies

• admin/internal metadata

In short:

Supabase is the source of truth for Portal-side product data.

V1 entities likely stored in Supabase

• users

• organizations

• organization_members

• api_keys

• model_access_policies

• usage_events

• request_logs

• billing_ledger

• plan_subscriptions

• router_pools

• router_pool_models

Important caveat

Supabase should not be the only hot-path enforcement layer.

It should store durable truth, but request-time checks should not depend on multiple raw DB reads for every call.

---

3.3 Unkey

Unkey should be used in V1 for API key issuance, verification, rate limiting, and basic per-key usage visibility.

Good V1 uses:

• key issuance / lifecycle integration

• key existence / validity checks

• revocation-aware key verification

• per-key rate limiting

• fast request-time enforcement

• basic usage / analytics visibility per key

In short:

Unkey helps make the hot path fast and product-ready without requiring the team to build every key/rate-limit primitive from scratch on day one.

What Unkey does not replace

Unkey does not replace Portal business logic.

It should not be treated as the full control plane for:

• plan logic

• model entitlement logic

• quota semantics

• router pool selection

• durable usage/billing records

• product-specific response shaping

It is a supporting enforcement layer, not the full product brain.

---

3.4 Custom Portal Backend

Even in V1, Cortensor Portal still needs its own backend / business-logic layer.

This is important.

The Portal backend should be responsible for:

• handling product/business logic

• coordinating auth + Supabase + Unkey + router fleet

• exposing stable Portal APIs and dashboard APIs

V1 responsibilities of the custom backend

• API key creation / revoke flow

• key metadata lookup / ownership checks

• model entitlement checks

• quota checks

• router-pool resolution

• request normalization

• response normalization

• usage event emission

• billing/event writes to durable storage

• admin controls

• request ID generation and tracing

So even in V1, the architecture is not:

client → Unkey → router

It is:

client → Portal backend → Unkey + product logic → router pool

---

3.5 Managed Router Pools

The backend inference layer should be made of managed router pools.

V1 should use a small number of router pools, each aligned to a product-facing model family.

Example conceptual pools:

• oss-20b pool

• oss-120b pool

• gemma4 pool

• qwen pool

The Portal backend resolves product model names into these pools.

Example:

• customer requests gemma-4-26b

• Portal backend maps this to gemma4 pool

• request is forwarded to a healthy router in that pool

• underlying dedicated sessions serve inference

This keeps internal router/session topology hidden from users.

---

3.6 Dedicated-Backed Sessions

For V1, the recommendation is to use dedicated-backed sessions underneath router pools.

Reasons:

• more predictable latency

• more stable output behavior

• easier debugging

• easier quota and billing design

• easier support and customer expectation setting

Ephemeral capacity can come later, but should not be the primary foundation for the first hosted product surface.

---

4. V1 Request Flow

The recommended V1 request flow is:

1. client sends request with Portal API key

2. Portal backend receives the request

3. Portal backend verifies the key through Unkey

4. Portal backend checks:

   • key status

   • model entitlement

   • plan rules

   • quota allowance

5. Portal backend / gateway applies rate limit using Unkey

6. Portal backend resolves the requested model to a router pool

7. request is forwarded to the selected managed router pool

8. router pool serves inference via dedicated-backed session(s)

9. Portal backend emits usage / metering events

10. Supabase-backed durable usage / billing records are updated

In simplified form:

Client → Portal backend → Unkey + Portal business logic → router pool → usage / billing writeback

---

5. What Business Logic Still Exists in V1

Even with Clerk or Supabase Auth, Supabase DB, and Unkey, the Portal still needs product logic that is specific to Cortensor.

V1 business logic examples

• determine which models a user/org can access

• map product model aliases to backend router pools

• decide whether the request is within quota

• normalize backend router responses into a stable Portal API response

• emit usage events to the Portal ledger

• support admin actions such as:

  • disabling a model

  • draining a pool

  • pausing access for a key/account

This is why V1 still needs a real Portal backend rather than only “auth provider + Supabase + Unkey + routers”.

---

6. Why This V1 Stack Fits

This combination works well for the first version because:

Auth layer gives you

• standard user/session handling

• Web2-style login flows

• optional Web3 wallet login support

• product-grade account UX

Supabase DB gives you

• durable relational product data

• straightforward internal/admin workflows

• a practical source of truth for plans, orgs, usage, and billing

Unkey gives you

• API key issuance / verification support

• rate limiting

• fast hot-path checks

• basic per-key usage visibility and analytics positioning

Custom backend gives you

• Cortensor-specific business logic

• model routing

• quotas

• usage and billing orchestration

• admin and operational controls

Together, that gives V1 a strong practical shape without forcing the team to build every primitive from scratch immediately.

---

7. Limitations of This V1 Shape

This is a good V1 architecture, but it is not necessarily the final architecture.

Over time, limitations may appear:

• dependence on a third-party key/rate-limit layer

• need for deeper custom routing behavior

• more complex quota/billing semantics

• desire for tighter control over request-time enforcement

• more advanced fleet management and failover logic

That is expected.

The point of V1 is not to solve everything permanently. The point is to launch a coherent hosted product with a solid path forward.

---

8. Expected Evolution After V1

A likely next step after V1 is:

• keep Supabase as durable product data

• keep either Clerk or Supabase Auth depending on what was chosen in V1

• move toward a more custom lightweight gateway

• add Redis / Upstash / equivalent for runtime counters and short-window state

• preserve the same router-pool architecture underneath

That would shift the architecture toward:

Auth layer + Supabase DB + custom gateway + runtime fast-state layer + managed router pools

But for V1, the simpler implementation path remains:

Clerk or Supabase Auth + Supabase DB + Unkey + custom Portal backend + managed router pools

---

9. V1 Scope Recommendation

Portal V1 should stay intentionally narrow.

User-facing V1 scope

• sign-in / auth

• org/account handling

• API key create / revoke

• simple docs / API reference

• small launch model set

• minimal usage dashboard

• basic quota and error messaging

Backend V1 scope

• key verification

• revocation

• per-key rate limiting

• quota checks

• model allowlist / entitlement checks

• request logging

• router pool routing

• usage event writes

• admin visibility

Billing V1 scope

Keep billing simple:

• prepaid credits, or

• monthly quota

Avoid too many billing dimensions in the first release.

---

10. Working Summary

The intended first version of Cortensor Portal would use:

• Clerk or Supabase Auth

• Supabase DB

• Unkey

• and a custom business-logic backend

with managed router pools underneath.

The practical V1 architecture is:

Clerk or Supabase Auth + Supabase DB + Unkey + custom Portal backend in front of managed Cortensor router pools

Where:

• Auth layer = user login / identity

• Supabase DB = durable product/account/control-plane state

• Unkey = API key issuance / verification / rate limiting / basic per-key usage visibility

• Custom backend = Cortensor-specific business logic, routing, quota, and usage handling

• Router pools = managed inference backend

• Dedicated-backed sessions = stable serving foundation for the first release

That gives Cortensor Portal a realistic V1 implementation path while preserving room to evolve into a more customized gateway architecture later.