KubeStellar Console Development Rules

Project Structure

• Frontend: React + TypeScript in /web/
• Backend: Go (Fiber v2) in root directory
• Build: cd web && npm run build && npm run lint before every commit
• Cards: Dashboard card components in web/src/components/cards/
• Hooks: Data fetching hooks in web/src/hooks/

Card Development

• All data fetching MUST go through useCache/useCached* hooks
• Always destructure and pass isDemoData and isRefreshing to useCardLoadingState()
• Never use demo data during loading: isDemoFallback && !isLoading
• Hook ordering: useCardLoadingState AFTER hooks providing isDemoData

Array Safety

• NEVER call .join(), .map(), .filter(), .forEach(), for...of on values that might be undefined
• Always guard: (data || []).map(...) or (data || []).join(', ')

No Magic Numbers

• Numeric literals should be named constants, except trivial literals (0, 1, -1) in clear local contexts
• Use constants from lib/constants/ (time.ts, network.ts, ui.ts)

Styling

• Tailwind CSS with cn() utility for merging classNames
• Never use raw hex colors — use semantic Tailwind classes (text-foreground, bg-primary, bg-card)
• Status colors: text-green-400/bg-green-500/10 (success), text-yellow-400/bg-yellow-500/10 (warning), text-red-400/bg-red-500/10 (error), text-cyan-400/bg-cyan-500/10 (info) — these map to the design system's semantic status tokens and are the only permitted palette classes

Internationalization

• All user-facing strings use t() from react-i18next
• Keys in web/src/locales/en/ JSON files
• Never use raw strings for UI text

Go Backend

• Fiber v2 handlers: func(c *fiber.Ctx) error
• Use fiber.NewError(statusCode, message) for errors
• Always make([]T, 0) not var x []T (nil → null in JSON)
• Use log/slog for structured logging
• Multi-cluster queries use goroutines + sync.WaitGroup

Cluster Deduplication

• Always use DeduplicatedClusters() when iterating clusters
• Multiple kubeconfig contexts can point to same physical cluster