Cortensor Portal V1 – Top-Level Specification

Status

Draft

Purpose

This document is the top-level specification for Cortensor Portal V1.

It is intended to:

• define the product shape of Portal V1 at a high level

• separate the work into clear implementation areas and workstreams

• provide a stable base for later detailed specs

This document is intentionally high level. It should be read as the product and system framing for V1, not as the final implementation detail for every component.

---

Public TL;DR

Portal V1 is shaping up as a hosted inference product built on top of managed Cortensor router infrastructure.

The first version is expected to focus on a simple developer-facing surface:

• sign in

• create and revoke API keys

• view usage and limits

• call a hosted Cortensor API

Under the hood, the likely V1 stack is:

• Clerk or Supabase Auth for auth

• Supabase for durable product data

• Unkey for API key issuance, verification, rate limiting, and basic usage visibility

• a custom Portal backend / gateway

• managed router pools backed by dedicated sessions

The goal is to launch a clean, narrow, productized API experience first, then evolve the gateway, billing, and fleet management layers over time.

---

1. Product Summary

Portal V1 should be treated as a separate hosted product surface, not as a thin extension of the existing mining or router dashboard.

The core user promise is:

use Cortensor through a simple hosted API product without having to run your own router nodes or manage the surrounding infrastructure

The V1 product should feel:

• simple

• hosted

• productized

• predictable

• developer-friendly

It should not feel like:

• an infra console for raw router nodes

• a direct session-management interface

• a network-operator dashboard

The intended V1 framing is:

A hosted inference API backed by managed Cortensor router pools

---

2. Portal V1 Goals

Portal V1 should aim to:

• provide a clean sign-in and account flow

• let users create and revoke API keys

• expose a small curated model surface

• show basic usage, quota, and plan state

• forward requests through a managed backend instead of exposing raw routers

• reuse a practical free-plan and sliding-window rate-limit model

Portal V1 should also reduce friction for:

• developers who want hosted inference access quickly

• teams who do not want to operate router infrastructure

• future productization of usage, plans, and billing

---

3. Non-Goals for V1

Portal V1 should not try to solve everything in the first release.

The following are explicitly non-goals or low-priority goals for V1:

• exposing every possible model or every network capability

• exposing raw router topology, session IDs, or infra internals to customers

• building a full enterprise gateway platform from day one

• launching complex multi-dimensional billing semantics immediately

• supporting advanced routing controls for end users

• building a heavy internal admin platform before the core flow is stable

V1 should stay intentionally narrow so it can launch coherently.

---

4. High-Level User Experience

The V1 web app should be minimal and straightforward.

The intended UI/UX direction is:

• clean auth experience

• lightweight account shell

• simple left navigation or equivalent account navigation

• quiet usage page

• focused API key management page

• minimal billing and profile surfaces

The current best V1 mental model for the UI is:

• auth first

• API keys second

• usage visibility third

If something does not clearly support those flows, it is probably not essential for V1.

Recommended V1 navigation

• Usage

• API Keys

• Billing or Plan

• Docs

• Profile

If scope needs to stay tighter, Billing and Profile can be simplified or deferred.

---

5. V1 Product Surface

5.1 User-Facing Web App

The initial web app should cover:

• sign in / sign up

• session handling

• account shell

• API key management

• usage / quota visibility

• simple billing / plan status

• docs or getting-started links

5.2 Hosted API Surface

The external API should:

• accept Portal-issued API keys

• expose stable product-facing model names

• apply quota and rate-limit enforcement

• route requests through managed router pools

• emit usage events for durable writeback

5.3 Supporting Product Surfaces

The following may exist in a limited form in V1:

• simple docs pages

• getting-started examples

• basic upgrade / plan messaging

• lightweight support or contact entry points

---

6. High-Level Architecture

The intended high-level request path is:

client -> Portal backend / gateway -> key + policy + quota checks -> router pool -> dedicated-backed session(s)

The important separation is:

Product Layer

Owns:

• auth

• dashboard UI

• API key lifecycle

• usage views

• account / org semantics

Control / Gateway Layer

Owns:

• key verification

• rate limiting

• model entitlement checks

• quota checks

• request normalization

• router-pool resolution

• response normalization

• usage event emission

Inference Layer

Owns:

• managed router pools

• pool health and availability

• dedicated-backed inference sessions

• backend inference execution

This separation keeps Portal V1 productized while allowing the router layer to evolve independently later.

---

7. Proposed V1 Stack

The current recommended V1 stack is:

• Clerk or Supabase Auth for auth

• Supabase for durable product state

• Unkey for API key issuance / verification / rate limiting

• custom Portal backend for Cortensor-specific logic

• managed router pools for inference

• dedicated-backed sessions underneath for predictable serving

Why this stack fits V1

• it is fast enough to get to MVP

• it avoids building every primitive from scratch

• it keeps the request hot path practical

• it preserves room to move to a more custom gateway later

Current Auth Direction

Auth is still being finalized, but Clerk currently looks stronger than Supabase Auth from an early product-surface point of view.

This is not finalized yet.

For now, the V1 top-level assumption should remain:

• Clerk or Supabase Auth as the auth layer

• final choice to be resolved as part of the auth workstream

---

8. Main Workstreams

Portal V1 can be split into a set of major workstreams.

8.1 UI / UX / Web App

Owns:

• auth screens

• app shell and navigation

• usage page

• API keys page

• billing / plan page

• profile page

• docs links and onboarding states

• empty states, errors, and quota messaging

8.2 Auth

Owns:

• Clerk or Supabase Auth integration

• sign in / sign up

• protected routes

• user session handling

• account identity

• future org support boundaries if needed

8.3 API Key Management

Owns:

• create key

• reveal-once flow

• revoke key

• key metadata

• key ownership checks

• key list and management UX

8.4 Free Plan / Rate Limits / Gateway

Owns:

• sliding-window allowance logic

• request caps

• reset windows

• per-key rate limits

• per-account or per-org quota checks

• gateway request path

• fast hot-path enforcement

8.5 Portal Backend / Control Plane

Owns:

• product business logic

• auth/account mapping

• model alias mapping

• router pool selection

• request and response normalization

• usage event emission

• durable write coordination

8.6 Data Model / Durable State

Owns:

• users

• organizations

• organization members

• API keys

• model access policies

• usage events

• request logs

• plan subscriptions

• billing ledger

• router pools

• router pool models

8.7 Router Pool and Model Product Layer

Owns:

• initial model catalog

• product model naming

• pool-to-model mapping

• dedicated-backed capacity assumptions

• pool health and drain behavior

8.8 Admin / Ops

Owns:

• disable key

• disable account

• disable model

• drain a pool

• inspect request logs

• inspect usage and quota state

---

9. V1 Functional Scope

In Scope

• hosted sign-in experience

• account-level web app

• API key create / revoke

• minimal usage dashboard

• simple free-plan or quota visibility

• narrow launch model set

• hosted inference API in front of managed router pools

• basic request logging and usage writeback

Likely in Scope If Simple Enough

• simple docs links

• billing / upgrade placeholder state

• basic plan badge or usage badge

• lightweight admin visibility

Out of Scope Unless Needed Later

• advanced user-controlled routing

• deep infra observability in the customer UI

• full enterprise billing dimensions

• full organization admin suite

• broad marketplace-style capacity exposure

---

10. UI / UX Direction

The current V1 mock direction is a good fit.

The Portal should feel:

• minimalist

• readable

• straightforward

• productized

• account-centered

The UI should emphasize:

• first key creation

• usage clarity

• low-friction onboarding

• low-noise account management

The UI should avoid:

• exposing too many network-native concepts

• looking like an internal monitoring tool

• making infra topology part of the normal user journey

---

11. Usage, Limits, and Plan Model

Portal V1 should keep usage semantics simple.

The best current assumption is:

• free plan first

• sliding-window allowance model

• clear reset timing

• request or task cap visibility

• minimal but understandable quota messaging

The first implementation should optimize for:

• easy explanation

• easy enforcement

• easy debugging

• easy later evolution

Billing should stay intentionally simple in V1, such as:

• free plan only at first

• prepaid credits, or

• one simple monthly quota plan

---

12. Router Pool Strategy

Portal V1 should sit in front of managed router pools, not expose raw router nodes directly.

The likely early model groups are:

• oss-20b

• oss-120b

• gemma4

• qwen

The customer should request stable product model names.

The Portal backend should:

• map product model names to router pools

• pick a healthy router target

• keep internal session and fleet layout hidden

For V1, dedicated-backed pools remain the preferred default because they are easier to support and reason about commercially.

---

13. Top-Level Risks

The main V1 risks to keep in mind are:

• overbuilding the gateway too early

• underdesigning usage and billing writeback

• exposing router-native complexity in the product surface

• making every request depend on raw durable DB reads

• unclear entitlement or quota semantics

• insufficient pool health awareness

• over-scoping the customer UI before the core API path is stable

---

14. Recommended Build Sequence

A practical build order for V1 is:

1. finalize top-level product and architecture framing

2. build auth and minimal Portal shell

3. implement API key lifecycle flows

4. implement gateway hot-path checks and routing

5. implement usage visibility and durable metering writes

6. add simple plan / billing surface

7. add lightweight admin / operational controls

This keeps the product anchored around the core value:

• auth

• key

• hosted request

• usage visibility

---

15. Planned Detailed Docs Pages

These are the planned follow-up documents that will be created one by one from this top-level Portal V1 spec.

• 01-ui-ux-web-app.md Defines the Portal web app experience, navigation, page structure, key user flows, onboarding states, and overall UI/UX direction.

• 02-auth.md Defines the authentication layer, login/session model, protected-route behavior, and the expected role of Clerk or Supabase Auth in Portal V1.

• 03-api-key-management.md Defines API key lifecycle behavior, including create, reveal-once flow, revoke, metadata, ownership rules, and product-facing key UX.

• 04-free-plan-rate-limits-and-gateway.md Defines free-plan behavior, sliding-window limits, quota semantics, request-time enforcement, and the gateway’s hot-path responsibilities.

• 05-portal-backend-control-plane.md Defines the Portal backend as the product/control-plane layer that handles routing, model alias resolution, request normalization, and business logic.

• 06-data-model-and-durable-state.md Defines the core Portal data model, durable entities, and the expected shape of product-side state stored in Supabase.

• 07-router-pools-and-model-product-layer.md Defines the model catalog, router-pool grouping, product model naming, dedicated-backed capacity assumptions, and backend model-to-pool mapping.

• 08-usage-metering-and-billing.md Defines usage event capture, quota accounting, billing ledger expectations, and the staged direction for pricing and payment.

• 09-admin-and-ops.md Defines internal/admin controls, operational workflows, pool disable/drain actions, request inspection, and support/ops visibility.

• 10-docs-and-developer-experience.md Defines the developer-facing docs surface, onboarding flow, API reference expectations, examples, and how the Portal should be explained to users.

---

16. Relationship to Existing Notes

This document is the top-level spec.

The existing architecture note remains useful as a deeper supporting reference:

• cortensor-portal-architecture-reference.md

That document contains more exploratory architecture discussion.

This document should be treated as the cleaner V1 planning surface for execution and future spec splits.

---

17. Working Summary

Portal V1 is shaping up as:

• a hosted inference product

• a standalone portal surface

• auth + API key + usage visibility

• a Portal backend in front of managed router pools

• dedicated-backed capacity first

• a narrow model catalog first

• product logic separated from routers

In one sentence:

Portal V1 is the first managed Cortensor product surface: a hosted inference API with API keys, quotas, and curated models, backed by managed router pools rather than raw user-operated router nodes.