# Project Structure and Naming

This document defines how we name SwiftUI views and how we place files in the project so the codebase matches the product language and the UI hierarchy.

## Core Rules

- Name folders after the feature or navigation surface the user sees.
  - Example: the Home tab lives in `Views/Meter/Tabs/Home/`, not in `Connection/`.
- Name the main view in a folder after the feature it owns.
  - Example: `MeterHomeTabView.swift` is the root view for the meter Home tab.
- Keep the file name and the Swift type name identical.
  - Example: `MeterOverviewSectionView.swift` contains `MeterOverviewSectionView`.
- Prefer product language over implementation history.
  - If the app says "Home", use `Home` in code instead of older terms like `Connection`.
- Use `Components/` only for reusable building blocks.
  - A component is used in multiple views or is clearly meant to be reused.
  - Example: `MeterInfoCardView` and `MeterInfoRowView`.
- Use `Subviews/` for views that belong to a single parent feature.
  - A subview is used once or is tightly coupled to one screen/tab.
  - Example: `Views/Meter/Tabs/Home/Subviews/MeterOverviewSectionView.swift`.
- Use `Sheets/` for modal flows presented from another screen.
  - Example: `Views/Meter/Sheets/AppHistory/AppHistorySheetView.swift`.
- Keep reusable components close to the narrowest shared owner.
  - If a component is reused only inside Meter screens, keep it in `Views/Meter/Components/`.
  - Do not move it to app-wide `Views/Components/` unless it is truly generic.
- Keep small support types next to their owner.
  - If a helper type exists for one view only, keep it in the same file or the same feature subfolder.
- Avoid vague verbs or placeholder names.
  - Prefer `MeterNameEditorView` over `EditNameView`.
  - Prefer `MeterConnectionActionView` over `ConnectionPrimaryActionView`.
- A folder should describe ownership, not implementation detail.
  - `Home/Subviews/` is better than `Connection/Components/` when the views are single-use parts of the Home tab.

## Naming Checklist

Before adding or renaming a file, check:

- Can someone guess the file location from the screen name?
- Does the type name say what the view renders?
- Is this reused enough to deserve `Components/`?
- If it is single-use, does it live under the parent feature's `Subviews/` folder?
- Does the code use the same words as the UI?

## Current Meter Tab Pattern

Use this structure for Meter tab work:

```text
Views/Meter/
  Components/
    MeasurementChartView.swift
    MeterInfoCardView.swift
    MeterInfoRowView.swift
  Sheets/
    AppHistory/
      AppHistorySheetView.swift
      Subviews/
        AppHistorySampleView.swift
    ChargeRecord/
      ChargeRecordSheetView.swift
      Subviews/
        ChargeRecordMetricsTableView.swift
    DataGroups/
      DataGroupsSheetView.swift
      Subviews/
        DataGroupRowView.swift
  Tabs/
    Home/
      MeterHomeTabView.swift
      Subviews/
        MeterConnectionActionView.swift
        MeterConnectionStatusBadgeView.swift
        MeterOverviewSectionView.swift
    Live/
      MeterLiveTabView.swift
      Subviews/
        LoadResistanceIconView.swift
        MeterLiveContentView.swift
        MeterLiveMetricRange.swift
    Chart/
      MeterChartTabView.swift
    Settings/
      MeterSettingsTabView.swift
      Subviews/
        MeterCurrentScreenSummaryView.swift
        MeterNameEditorView.swift
        MeterScreenControlButtonView.swift
        MeterScreenControlsView.swift
        ScreenBrightnessEditorView.swift
        ScreenTimeoutEditorView.swift
```

## Current Charged Device Pattern

Use the same root categories as Meter work: shared components first, screen/detail roots next, then sheets and sidebar-specific views.

```text
Views/ChargedDevices/
  Components/
    ChargedDeviceDetailTabBarView.swift
    ChargedDeviceEditorScaffoldView.swift
    ChargedDeviceIdentityViews.swift
    ChargedDeviceLibraryRowView.swift
    ChargedDeviceQRCodeView.swift
    ChargedDeviceSidebarCardView.swift
  Details/
    ChargedDeviceDetailView.swift
  Sessions/
    ChargedDeviceActiveSessionView.swift
    ChargedDeviceSessionDetailView.swift
    ChargedDeviceSessionsView.swift
  Sheets/
    ChargeSession/
      BatteryCheckpointEditorSheetView.swift
      ChargeSessionCompletionSheetView.swift
    Editors/
      ChargedDeviceEditorSheetView.swift
      ChargerEditorSheetView.swift
    Library/
      ChargedDeviceLibrarySheetView.swift
  Sidebar/
    SidebarChargedDeviceLibraryView.swift
    SidebarChargedDevicesSectionView.swift
```

## Refactor Examples

- `Connection/` -> `Home/`
- `MeterConnectionTabView` -> `MeterHomeTabView`
- `ConnectionHomeInfoPreviewView` -> `MeterOverviewSectionView`
- `ConnectionPrimaryActionView` -> `MeterConnectionActionView`
- `EditNameView` -> `MeterNameEditorView`
- `MeasurementsView` -> `AppHistorySheetView`
- `RecordingView` -> `ChargeRecordSheetView`
- `ControlView` -> `MeterScreenControlsView`

## Decision Rule

If a new name makes a teammate look in the right folder on the first try, it is probably a good name.
