Skip to main content

​
Welcome, Developer!

This section contains comprehensive technical documentation for developers who want to:
  • Understand the architecture
  • Contribute to the project
  • Extend functionality
  • Debug issues
  • Deploy Orphelix

​
Technology Stack

Frontend

  • Next.js 15 - React framework with App Router
  • React 19 - UI library
  • Material-UI v7 - Component library
  • TypeScript 5.7 - Type safety

State Management

  • TanStack Query v5 - Data fetching & caching
  • Zustand - Global state (theme, mode, namespace)
  • Context API - Search state management

Backend

  • Next.js API Routes - Serverless functions
  • @kubernetes/client-node - K8s API client
  • Server-Sent Events - Real-time updates

Testing

  • Vitest - Unit testing framework
  • Playwright - E2E testing
  • React Testing Library - Component testing

​
Architecture Overview

Orphelix follows a modern, scalable architecture:

​
Key Design Patterns

​
1. API Route Architecture

All Kubernetes operations are server-side to prevent credentials exposure: 
// app/api/deployments/route.ts
export async function GET(request: Request) {
  const kc = getKubeConfig()
  const k8sApi = kc.makeApiClient(AppsV1Api)

  const { data } = await k8sApi.listNamespacedDeployment({
    namespace: 'default'
  })

  return NextResponse.json(deployments)
}

​
2. TanStack Query Hooks

Consistent data fetching pattern with caching: 
export function useDeployments() {
  return useQuery({
    queryKey: ['deployments', namespace],
    queryFn: () => fetch('/api/deployments').then(r => r.json()),
    refetchInterval: 30000, // Auto-refresh every 30s
  })
}

​
3. Real-time Updates with SSE

Server-Sent Events for live cluster updates: 
// Server
const stream = new ReadableStream({
  start(controller) {
    watcher.on('ADDED', (obj) => {
      controller.enqueue(`data: ${JSON.stringify(obj)}\n\n`)
    })
  }
})

// Client
useEffect(() => {
  const eventSource = new EventSource('/api/realtime')
  eventSource.onmessage = (event) => {
    queryClient.invalidateQueries(['deployments'])
  }
}, [])

​
4. Component Structure

Consistent component organization: 
app/
  components/
    common/          # Reusable components
    layout/          # Layout components
    [resource]/      # Resource-specific components
  [resource]/        # Pages
    page.tsx         # List view
    [name]/
      page.tsx       # Detail view

​
Getting Started

1

Set up your environment

See Getting Started for setup instructions
2

Understand the architecture

Read Architecture for detailed system design
3

Review the tech stack

Check Tech Stack for technology decisions
4

Run tests

Follow Testing Guide to run and write tests
5

Start contributing

See Contributing for contribution guidelines

API Reference

REST API documentation

Testing

Testing strategy and guides

Contributing

How to contribute code

​
Development Principles

  • Never expose cluster credentials to browser
  • All K8s operations are server-side
  • Secrets values are never displayed
  • GitHub App tokens in HTTP-only cookies
  • Aggressive caching with TanStack Query
  • Server-Side Rendering (SSR) for initial load
  • Code splitting with Next.js dynamic imports
  • Optimistic UI updates
  • Strict TypeScript configuration
  • Full type coverage for K8s resources
  • Type-safe API routes
  • No any types allowed
  • 214+ unit tests with Vitest
  • 93+ E2E tests with Playwright
  • Mock data for demo mode
  • Test coverage reporting

​
Repository Structure

orphelix/
├── app/                    # Next.js app directory
│   ├── api/               # API routes
│   ├── components/        # React components
│   └── [resources]/       # Page routes
├── lib/                   # Utilities & hooks
│   ├── hooks/            # TanStack Query hooks
│   ├── utils/            # Helper functions
│   └── store/            # Zustand store
├── types/                 # TypeScript definitions
├── __tests__/            # Unit tests
├── e2e/                  # E2E tests
└── docs/                 # Documentation

​
Next Steps

Choose your path:

I want to contribute code

Read the contributing guide

I want to understand the architecture

Explore the architecture

I want to add tests

Learn about testing

I want to deploy Orphelix

See deployment options