dasomel — OSS Workbench

Project Overview

Narwhal Portal is the management portal and developer workbench for the Narwhal Kubernetes Internal Developer Platform.

Narwhal provides the underlying GitOps, SSO, observability, storage, security, and platform services. The Portal provides the day-2 operational surface that makes those services understandable and usable as one platform.

The portal does not try to replace every upstream UI. Kubernetes, Argo CD, Keycloak, and other systems remain authoritative; the Portal aggregates platform signals and exposes them through platform-level concepts.

Core Areas

Area	Purpose
Dashboard	Cluster health, Argo CD applications, alerts, and overall platform status
Onboarding	Getting-started workflow and kubeconfig issuance
Catalog / My Apps	Service catalog and per-user application view
Nodes	Node inventory and status
Cost	Namespace/workload cost visibility
Security / Compliance	Security posture, policies, RBAC, and audit-related information
Governance	Scorecards, DORA-related information, and platform maturity signals
Architecture	Platform and service relationships
Templates / Tools	Developer-oriented platform utilities
Settings	Users, routes, certificates, and policy settings

Position in Narwhal

                    Narwhal IDP
┌───────────────────────────────────────────────────────┐
│ Kubernetes                                             │
│ GitOps · SSO · Observability · Storage · Security      │
└─────────────────────────┬─────────────────────────────┘
                          │ platform state / APIs
                          ▼
                ┌──────────────────────┐
                │   Narwhal Portal     │
                │   Next.js + React    │
                ├──────────────────────┤
                │ Dashboard            │
                │ Catalog / My Apps     │
                │ Nodes / Cost          │
                │ Security / Governance│
                │ Architecture / Tools │
                └──────────┬───────────┘
                           │
                           ▼
                  Developer / Operator

Technology Stack

Next.js 16 / React 19 — App Router application
TypeScript — typed frontend/API boundaries
Tailwind CSS 4 / shadcn/ui — reusable admin UI
TanStack Query / Zustand — server/client state
Keycloak OIDC — authentication and sessions
Valkey — application cache
OpenBao Agent Injector — runtime secrets injection
Skaffold / Kaniko — Kubernetes inner-loop development and in-cluster image builds

Deployment Model

The production portal is served inside the Narwhal cluster at https://portal.local.narwhal.internal through the APISIX gateway.

A local development loop is available with:

git clone https://github.com/dasomel/narwhal-portal.git
cd narwhal-portal
pnpm install
pnpm dev

For cluster-based development, the project also supports Skaffold HMR. Production image workflows can use the in-cluster Gitea → Kaniko → Harbor path, avoiding a local Docker daemon for the normal deployment flow.

Design Principles

Preserve authoritative sources

Argo CD, Kubernetes, Keycloak, and other platform services keep ownership of their resources. The Portal is a user-facing integration layer, not a competing source of truth.

Use platform domains

Users should not need to understand every upstream product to answer platform questions. Concepts such as Application, Service, Catalog, Security, and Governance create a consistent IDP vocabulary.

Expose operational boundaries

GitOps ownership, policy violations, authentication state, certificate state, and failure conditions should be visible in the UI rather than hidden behind an upstream product boundary.

Connect Day-0 and Day-2

Onboarding, Catalog, Templates, Tools, and operational dashboards are part of the same workbench so the portal spans from initial access to ongoing operations.

Documentation Index

Topic	Document	Purpose
Overview	Portal Overview	Role and user scenarios
Architecture	Portal Architecture	Application/data flow
Getting Started	Development Setup	pnpm, environment, Skaffold
Operations	Deployment & Operations	Build, deployment, health
ADR	Architecture Decision Records	Technical decisions and trade-offs

Project Relationship

kube-ready-box
       ↓
   Narwhal Cluster
       ├── GitOps / SSO / Observability / Storage / Security
       │
       └── Narwhal Portal
              ↓
       Developer / Operator UX