Control Plane Tour

odock-ui is the browser control plane for configuring the gateway. It has two main workspaces.

Admin Workspace

Path prefix:

/admin

The admin workspace is for SUPER_ADMIN users. Its API routes live under:

/api/admin

Admin navigation contains:

• Dashboard
• Organisations
• Teams
• Users
• Providers
• Models
• MCP Servers
• API Keys
• Budgets
• Quotas
• Usage Records
• Invoices
• AI Playground
• Settings

Admin list pages can search, filter, paginate, sort, create records, open detail views, and run resource actions such as API key reveal, rotation, and revocation.

Organisation Workspace

Path prefix:

/:organisation

The organisation workspace is scoped to one organisation ID in the URL. Its API routes live under:

/api/organisations/:organisationId

Organisation navigation depends on user role:

The root organisation path redirects to the dashboard:

/:organisation -> /:organisation/dashboard

Authentication Flow

The UI uses Better Auth with GitHub social login and Prisma persistence.

Relevant pages:

• /auth/login
• /auth/register
• /auth/post-auth
• /auth/no-organisation
• /auth/pending-access
• /auth/revoked-access
• /auth/error
• /invite/:token

The Next.js proxy redirects protected page routes to /auth/login if a session cookie is missing. API routes use withAuthorisation, withAdminAuth, or withOptionalAuth.

RBAC Summary

The RBAC engine maps:

• HTTP method to action.
• API route path to resource.
• Route params and database lookups to target organisation, team, user, API key, model, provider, or MCP server.
• User role and team memberships to conditional permissions.

Admin API routes are fast-failed unless the user is SUPER_ADMIN.

Organisation API routes are fast-failed unless:

• the user is SUPER_ADMIN, or
• the user's organisationId matches the organisation ID in the path.

After that, can(action, resource, context) evaluates role rules.

Detail Pages

Resource detail pages use reusable resource-detail and custom cards. The custom cards expose domain-specific operations that a plain CRUD table cannot show well, for example:

• API key reveal and access grants.
• Provider API key preview.
• Model pricing and policies.
• MCP transport, policy, rate-limit, and pricing cards.
• Usage breakdown and routing metadata.
• Budget schedule and projection cards.

Playground

The playground is available in both admin and organisation workspaces.

It lets users choose:

• an Odock API key,
• a model that key can access,
• a gateway URL,
• streaming or non-streaming chat.

The UI uses the Vercel AI SDK provider adapters and sends requests through the gateway. It checks that:

• the API key exists,
• the key is not revoked,
• the model exists,
• the API key has explicit access to the model,
• organisation-scoped playground requests only use models and keys in the current organisation.

Streaming responses are returned to the browser as newline-delimited JSON.

Invoices

The current invoicing feature is a preview and export surface over usage data. It aggregates UsageRecord and McpUsageRecord into nested organisation, team, API key, model, and MCP cost views. It does not currently persist immutable invoice documents.