Architecture

Understanding Gyre's architecture helps you deploy, configure, and extend it effectively.

High-Level Overview

┌─────────────────┐
│   User Browser  │
└────────┬────────┘
         │ HTTPS/SSE
         ▼
┌─────────────────┐
│   Gyre Pod      │
│  ┌───────────┐  │
│  │  SvelteKit│  │
│  │    UI     │  │
│  └───────────┘  │
│  ┌───────────┐  │
│  │  API      │  │
│  │  Routes   │  │
│  └───────────┘  │
│  ┌───────────┐  │
│  │   SQLite  │  │
│  │   (auth,  │  │
│  │   config) │  │
│  └───────────┘  │
└────────┬────────┘
         │ Kubernetes API
         ▼
┌─────────────────┐
│ Kubernetes API  │
│    Server       │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   FluxCD        │
│   Resources     │
└─────────────────┘

Components

Frontend (SvelteKit)

• Framework: Svelte 5 with Runes API
• Styling: TailwindCSS v4 with custom zinc/gold theme
• Components: shadcn-svelte + bits-ui
• State Management: Svelte 5 runes-based stores
• Real-time Updates: SSE client (src/lib/stores/events.svelte.ts) connected to src/routes/api/v1/events/+server.ts

Backend (SvelteKit API Routes)

• Runtime: Node.js (via adapter-node)
• API: RESTful endpoints in src/routes/api/v1/
• Kubernetes: @kubernetes/client-node for K8s API
• Authentication: bcrypt + jose (JWT)
• Database: SQLite with Drizzle ORM

Server-Side Architecture

src/lib/server/
├── kubernetes/       # K8s client and Flux utilities
│   ├── client.ts    # K8s API client
│   └── flux/        # FluxCD resource helpers
├── db/              # Database
│   ├── schema.ts    # Drizzle schema
│   └── migrate.ts   # Migration runner
├── auth/            # Authentication
│   ├── oauth/       # OAuth providers
│   └── session.ts   # Session management
├── rbac.ts          # RBAC policies
├── clusters.ts      # Multi-cluster config
└── audit.ts         # Audit logging

Data Flow

Resource List Request

1. User requests resource list
2. API route validates session
3. RBAC check for permissions
4. Query Kubernetes API for resources
5. Transform and cache response
6. Return JSON to client

Real-time Updates

1. Client opens an SSE stream to /api/v1/events
2. Server polls Kubernetes resources and emits normalized events
3. Resource changes trigger SSE events
4. Client receives updates and refreshes UI
5. Audit log records actions

Database Schema

Core Tables

• users - User accounts and credentials
• sessions - Active user sessions
• audit_logs - Action audit trail
• clusters - Multi-cluster configurations
• rbac_policies - Access control policies
• rbac_bindings - User-policy assignments
• auth_providers - SSO/OAuth configurations

Deployment Model

Helm/GitOps First

Production deployments are designed to run inside the Kubernetes cluster via Helm/GitOps:

• Uses pod ServiceAccount for authentication
• No kubeconfig file needed
• Accesses K8s API via in-cluster config
• Runs in flux-system namespace by default

Local out-of-cluster operation is supported for development/testing by mounting a kubeconfig file.

Resource Requirements

Minimum:

• CPU: 100m
• Memory: 128Mi
• Storage: 1Gi

Recommended:

• CPU: 500m
• Memory: 512Mi
• Storage: 5Gi

Security Model

Authentication

• Local: Username/password with bcrypt hashing
• SSO: OAuth 2.0 / OIDC (GitHub, Google, GitLab, Generic)
• Sessions: Secure HTTP-only cookies

Authorization (RBAC)

• Roles: admin, editor, viewer
• Resources: Per-type permissions
• Namespaces: Per-namespace access
• Clusters: Per-cluster permissions

Audit

All actions logged to audit_logs table:

• Timestamp
• User
• Action type
• Resource affected
• Success/failure status

Caching Strategy

Multi-layer caching reduces K8s API calls:

1. Server Memory: 30s TTL for dashboard data
2. API Responses: 15s TTL for individual requests
3. Client-side Event Stream: SSE keeps UI state fresh between cache refresh cycles

Technology Stack

Layer	Technology
Frontend	SvelteKit 2, Svelte 5, TailwindCSS v4
Backend	Node.js, SvelteKit API routes
Database	SQLite (better-sqlite3)
ORM	Drizzle ORM
K8s Client	@kubernetes/client-node
Auth	bcrypt, jose, arctic
Icons	@lucide/svelte
UI	bits-ui, shadcn-svelte

Extensibility

Adding New Flux Resources

1. Define types in src/lib/server/kubernetes/flux/types.ts
2. Add utilities in src/lib/server/kubernetes/flux/resources.ts
3. Create API routes in src/routes/api/v1/flux/[type]/
4. Add UI components in src/lib/components/flux/resources/
5. Update navigation in sidebar

Performance Considerations

• Large Clusters: Consider increasing resources
• Multi-cluster: Each cluster adds API overhead
• Real-time: SSE connections have limits
• Database: SQLite sufficient for most use cases