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:

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

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.