# 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

```

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

  Details/

    ChargedDeviceDetailView.swift

  Sessions/

    ChargedDeviceActiveSessionView.swift

    ChargedDeviceSessionDetailView.swift

    ChargedDeviceSessionsView.swift

  Sheets/

    ChargeSession/

      BatteryCheckpointEditorSheetView.swift

      ChargeSessionCompletionSheetView.swift

    Editors/

      ChargedDeviceEditorSheetView.swift

      ChargerEditorSheetView.swift

    Library/

      ChargedDeviceLibrarySheetView.swift

```

  ChargedDeviceSidebarCardView.swift

  SidebarChargedDeviceLibraryView.swift

  SidebarChargedDevicesSectionView.swift

Views/Chargers/

  ChargerEditorSheetView.swift

  ChargerStandbyPowerWizardView.swift

Note: sidebar-specific views for the app live in `USB Meter/Views/Sidebar/`, not under feature-specific subfolders.

Note: charger-specific views live in `USB Meter/Views/Chargers/` when they represent charger-only screens or flows. There is no `USB Meter/Views/Sidebar/Chargers`; sidebar charger views are still part of the shared `Views/Sidebar/` section because the sidebar is a global navigation area.

- `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.