backrest/webui/GEMINI.md

GEMINI.md

This document defines the architectural guidelines, file naming conventions, and coding standards for the WebUI project. All AI agents and developers should follow these rules when generating, refactoring, or analyzing code.

1. Project Architecture: Feature-Based

The project is transitioning from a flat file structure to a Feature-Based Architecture. All new development should follow this structure, and refactoring tasks should prioritize moving legacy files into their respective feature folders.

Directory Structure

.
├── dist/                       # Build artifacts (embed target)
├── gen/                        # Generated Protobuf/gRPC code (READ-ONLY)
├── public/                     # Static assets (favicon.ico, robots.txt)
├── webui.go                    # Go backend entry point
├── src/
│   ├── api/                    # API Layer & Interceptors (Wraps ../gen)
│   │   ├── client.ts           # Central API client configuration
│   │   └── ...                 # Domain specific API wrappers
│   ├── app/                    # App-wide Configuration
│   │   ├── App.tsx             # Root Component & Routing Logic
│   │   ├── main.tsx            # Entry point
│   │   └── provider.tsx        # Global Context Providers (Theme, Auth)
│   ├── components/             # SHARED / GENERIC Components (Atomic/Molecules)
│   │   ├── ui/                 # Design System primitives (Buttons, Inputs, Dialogs)
│   │   ├── layout/             # Structural components (PageTemplate, ActivityBar, Splitter)
│   │   └── common/             # Generic widgets (SyncStateIcon, SpinButton, ModalManager)
│   ├── features/               # DOMAIN SPECIFIC Logic (Organisms/Pages)
│   │   ├── auth/               # Authentication related components and logic
│   │   ├── dashboard/          # e.g., StatsPanel, SummaryDashboard
│   │   ├── operations/         # e.g., OperationListView, LogView, oplog.ts
│   │   ├── plans/              # e.g., PlanView, AddPlanModal
│   │   ├── repositories/       # e.g., RepoView, AddRepoModal, SnapshotBrowser
│   │   └── settings/           # e.g., SettingsModal
│   ├── hooks/                  # Global generic hooks (useWindowSize, useTheme)
│   ├── lib/                    # Stateless utilities (cronUtil, formatting, browserUtil)
│   ├── paraglide/              # Internationalization (Generated)
│   ├── state/                  # Truly Global State
│   ├── constants.ts            # Global constants
│   ├── custom.d.ts             # TypeScript declaration overrides
│   └── index.sass              # Global Styles
├── assets/                     # Source assets imported in code (svgs, logos)
├── vite.config.ts
└── tsconfig.json

---

2. Naming Conventions

Strictly adhere to these casing rules to ensure consistency.

File Type	Convention	Example	Reasoning
React Components	PascalCase	RunCommandModal.tsx	Must match JSX tag usage.
Hooks	camelCase	useAuth.ts	Required by React linter rules.
Utilities / Logic	camelCase	cronUtil.ts	Matches the primary export/instance.
Global State	camelCase	peerStates.ts	Matches the store instance.
Feature Folders	kebab-case	repo-management/	Avoids OS case-sensitivity issues.
Unit Tests	Match Target	cronUtil.test.ts
Go Files	snake_case	webui_test.go	Standard Go convention.

Specific Rules

• UI Components: src/components/ui/ may use kebab-case if generated by a CLI tool (e.g., shadcn), but PascalCase is preferred for custom components.
• Abbreviations: Treat abbreviations as words (e.g., apiClient.ts not APIClient.ts).

---

3. Coding Standards

TypeScript & React

• Components: Use Functional Components (const Component = () => {}).

• Types: Always use strict typing. Avoid any. Define interfaces/types for all Props.

• Naming: Variables and functions should be descriptive enough to avoid comments.

• Bad: const val = 10; // set max retry

• Good: const maxRetries = 10;

• Comments: Add relatively few comments. Focus on high-quality variable naming and separation of concerns. Only comment "Why", not "What".

• Helpers: Factor out complex logic into helper functions, but avoid over-abstraction (tiny helpers that disrupt reading flow).

Imports Ordering

1. External: React, Third-party libraries (import { useState } from 'react').
2. Internal (Aliased): Global components/hooks (import { Button } from '@/components/ui/button').
3. Local (Relative): Sibling files (import { SubComponent } from './SubComponent').

Internationalization (i18n)

• Library: Use Paraglide.
• Rule: Never hardcode user-facing strings.
• Usage: Import m from src/paraglide/messages.
• Example: <span>{m.welcome_message()}</span>
• Declaring: Declare new strings as keys in webui/messages/en.json and update generated code with npm run translate.

Generated Code (gen/)

• Status: READ-ONLY.
• Modification: Never modify files in gen/ or src/paraglide/. These are generated by build tools.
• Extensions: If you need to extend generated types, create wrapper functions in src/lib/ or src/api/.