# 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

```text
.
├── 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/`.