Cortensor Portal V1 Detailed Spec 01 - UI / UX / Web App
Status
Draft
Purpose
This document defines the frontend product surface for Cortensor Portal V1.
It translates the top-level Portal V1 framing into a concrete web app shape:
what pages exist
what each page is responsible for
what the user journey should feel like
what should be visible in V1
what should stay hidden behind the backend and gateway layers
This spec is intentionally focused on the customer-facing web app, not the full backend or gateway implementation.
1. Summary
Portal V1 should present a minimal hosted API console for users who want to:
sign in
create and revoke API keys
view usage and limits
understand their current plan
get started with the hosted API quickly
The UI should feel:
quiet
clear
lightweight
productized
account-centered
The UI should not feel like:
an internal operations dashboard
a raw router-node management panel
a network topology explorer
a session-level control surface
The overall V1 design direction should be:
simple auth, simple account shell, simple keys, simple usage
2. Design Principles
2.1 Minimal First
Portal V1 should avoid visual and conceptual clutter.
The interface should emphasize only the core tasks:
sign in
create key
copy key
revoke key
check usage
understand plan or free-tier limits
2.2 Hosted-Product Framing
The interface should reinforce that Portal is a hosted API product.
That means:
stable product naming
account-focused navigation
simple docs entry points
no requirement to understand router topology
2.3 Developer Clarity
A user should quickly understand:
where to create a key
how much usage remains
what plan they are on
how to start making requests
2.4 Narrow V1 Scope
The web app should stay intentionally narrow.
If a page or component does not clearly support:
auth
API keys
usage
plan visibility
docs onboarding
it should be questioned before inclusion.
3. UX Direction
The reviewed mock direction is the right baseline for V1:
straightforward sign-in
simple account shell
left-side navigation
large, clean content area
soft card surfaces
minimal decoration
3.1 General Feel
Portal V1 should feel:
modern
restrained
readable
neutral
high-signal
3.2 What to Avoid
Avoid:
heavy gradients
flashy dashboard chrome
too many nested panels
infra-centric language
dense operational tables by default
3.3 Visual Tone
Recommended visual tone:
light background by default
dark auth screen is acceptable if using Clerk-hosted styling
soft borders
generous whitespace
low-saturation neutral palette
one restrained brand accent
4. Primary User Journeys
4.1 First-Time User Journey
user lands on Portal
user signs in
user reaches the Portal shell
user is guided to create their first API key
user copies the key
user sees quick-start docs or an example request
user understands where to check usage later
4.2 Returning User Journey
user signs in
user lands on usage overview or API keys
user checks remaining allowance
user creates or revokes a key if needed
user leaves
4.3 Free-Plan Awareness Journey
user opens the usage page
user sees current plan badge
user sees current window usage
user sees weekly usage
user sees reset timing
user sees a simple upgrade or plan note if needed
5. Information Architecture
5.1 Recommended Authenticated Navigation
UsageAPI KeysBillingorPlanDocsProfile
5.2 Recommended Unauthenticated Surface
Unauthenticated V1 can be very small:
landing or auth wrapper
sign in
sign up
maybe one short product statement
5.3 Navigation Order
Recommended order:
UsageAPI KeysBillingDocsProfile
If Docs is not a primary left-nav item, it should still exist in a clearly visible top-right location.
6. Route Structure
Recommended initial route structure:
//sign-in/sign-up/portal/portal/usage/portal/keys/portal/billing/portal/docs/portal/profile
6.1 Route Behavior
/should route users into the appropriate auth or portal entry path/portalshould redirect to/portal/usageor/portal/keysprotected routes should require a valid auth session
unauthenticated users should be redirected to sign-in
6.2 Suggested Default Landing After Auth
Preferred initial behavior:
existing users land on
Usagefirst-time users may land on
API Keysif they have no keys yet
This can be determined later by account state.
7. Page Specs
7.1 Auth
Purpose
Handle sign in and sign up cleanly with minimal distraction.
Content
Portal product title
short supporting text
auth component
social sign-in if enabled
email-based sign-in
sign-up prompt
UX Notes
this can use hosted or embedded auth UI
should feel polished and familiar
should not include too much product detail
V1 Success Criteria
user can sign in quickly
auth flow feels stable and trustworthy
transition into the Portal shell is smooth
7.2 Usage
Purpose
Show a user:
what plan they are on
how much allowance they have used
when limits reset
whether they are near quota
Core Content
page title
current plan badge
short explanation of what usage means in V1
current window usage bar
weekly usage bar
reset timing
optional notification preference
Data Shown in V1
plan name
percentage used
current allowance
reset timing
simple warning state near limit
Avoid in V1
complex analytics
dense request log exploration
too many charts
deep model-by-model usage breakdowns
V1 Success Criteria
user immediately understands remaining headroom
reset timing is obvious
no ambiguity about whether usage is near exhaustion
7.3 API Keys
Purpose
This is the most important V1 page after auth.
It should let the user:
view existing keys
create a new key
copy a key
revoke a key
Core Content
page title
short explanation of what API keys are for
list of keys
create-key button
per-key revoke action
key metadata such as:
name
masked value
created time
optional last used later
Create-Key Flow
The create flow should include:
key name
create action
reveal-once confirmation view
copy button
warning that the raw secret will not be shown again
Revoke-Key Flow
The revoke flow should include:
clear destructive confirmation
key name reference
simple explanation that revoked keys stop working
Empty State
If no keys exist:
clear message
single prominent
Create API KeyCTAoptional quick-start doc link
V1 Success Criteria
user can create a usable key in under a minute
user can clearly distinguish active keys
user understands revoke behavior
7.4 Billing / Plan
Purpose
Give users a simple place to understand current plan state.
V1 Stance
Billing should be intentionally light in V1.
If final payment flow is not yet fully scoped, this page can still exist as:
plan summary
upgrade placeholder
invoice placeholder
pricing / availability note
Core Content
current plan
simple upgrade CTA if relevant
invoice placeholder or empty state
short explanation of current billing status
Avoid in V1
complex invoice UI
many billing dimensions
advanced payment methods matrix
V1 Success Criteria
user understands whether they are on free or paid access
user can see where upgrades will happen later
7.5 Docs
Purpose
Help the user get from:
signed in
to key created
to first API request
Core Content
quick-start snippet
example curl request
base API URL
where to find or create API keys
short model list or supported model aliases
link to fuller reference docs if separate
Importance
Even if the docs page is small in V1, some docs entry point is essential.
Portal without a quick-start path creates friction immediately after key creation.
V1 Success Criteria
user can find a request example without leaving the Portal
7.6 Profile
Purpose
Show and lightly manage the authenticated user identity.
V1 Stance
Profile can be much simpler than a mature account app.
Minimal profile is enough:
display name
email
basic avatar or auth identity
maybe organization context later
Optional Fields
username
first name
last name
bio
links
These are not essential for the hosted API product itself.
Recommendation
Keep this page lightweight unless there is a strong product reason to expand it.
8. Layout System
8.1 Auth Layout
Auth should use a focused, centered layout:
constrained width
one main card
little peripheral content
8.2 Portal Shell Layout
Recommended structure:
left rail with navigation
top-left account identity
large main content column
content cards inside the main column
8.3 Mobile Behavior
For mobile:
left nav should collapse into a drawer or compact top menu
cards should stack naturally
key rows and usage cards should remain readable
create and revoke actions should remain obvious
9. Shared Components
Recommended reusable components:
PortalShellSidebarNavAccountSummaryPageHeaderUsageMeterCardPlanBadgeKeyListKeyCardCreateKeyDialogRevokeKeyDialogEmptyStateQuickstartCard
These components should keep the V1 UI consistent without overbuilding a large design system.
10. Content and Language Guidelines
Portal copy should be:
clear
direct
non-technical where possible
still credible to developers
Preferred Language
Use:
API KeysUsagePlanLimitsResetModel
Avoid Unless Necessary
Avoid front-facing overuse of:
router node
session topology
validator
miner
pool internals
network-native contract semantics
Those concepts belong behind the product abstraction in V1.
11. Empty States and Edge States
The V1 app must handle a few states well.
Important Empty States
no API keys yet
no usage yet
no invoices yet
no profile extras yet
Important Edge States
quota nearly exhausted
quota exhausted
API key revoked
auth session expired
temporary backend issue
UX Rule
Each state should:
explain what happened
explain what the user can do next
avoid internal jargon
12. Error and Limit Messaging
Portal V1 should present limits in a calm and understandable way.
Examples of supported messages:
limit reached for current window
weekly allowance exhausted
key revoked
model not available on current plan
Messages should always prefer:
plain language
immediate cause
obvious next step
13. What Should Stay Out of the UI
The following should remain backend or admin concerns in V1:
raw router hostnames
router pool internals
dedicated session IDs
pool drain controls in the normal user UI
low-level metering reconciliation data
infra health dashboards
This is important to keep Portal positioned as a clean hosted product.
14. Dependencies on Other Specs
This spec depends on:
top-level Portal V1 framing
auth decision
API key model and lifecycle rules
free-plan and usage semantics
docs and API surface decisions
It will later connect directly to:
02-auth.md03-api-key-management.md04-free-plan-rate-limits-and-gateway.md08-usage-metering-and-billing.md
15. Open Questions
Open questions for later refinement:
should
Docsbe primary nav or top-right utility link?should first post-auth landing be
UsageorAPI Keys?how much of
Profileshould exist in V1?should
Billingbe visible at launch if payment is still not finalized?should a small launch-model list appear directly in the web app?
should onboarding guide users directly into first key creation?
16. Recommended Next Implementation Notes
The most practical next frontend execution order is:
auth screen and protected route shell
Portal shell layout
API keys page
usage page
docs quick-start page
lightweight billing page
lightweight profile page
If scope pressure appears, prioritize in this order:
auth
API keys
usage
docs
billing
profile
17. Relationship to Other Docs
This document should be read alongside:
Portal V1 Top-Level Specificationcortensor-portal-architecture-reference.md
The top-level spec defines the broader Portal V1 frame.
This document narrows that down into the concrete web app and UI/UX responsibilities.
Last updated