Codebase Skill — Complete Operational Guide

KEEP THIS FILE UP TO DATE. When architectural decisions change, files move, new patterns are adopted, or conventions shift, update this file immediately. Stale guidance is worse than no guidance. After any structural change (new store, renamed file, new dependency, changed workflow), check if this file needs updating.

Quick Reference Commands

pnpm dev              # Dev server → localhost:5173
pnpm build            # tsc && vite build → dist/
pnpm lint             # ESLint (--max-warnings 0, zero tolerance)
pnpm test             # Playwright E2E (full suite, ~10 min)
pnpm test:headed      # E2E with visible browser
pnpm test:ui          # E2E Playwright UI debug mode
pnpm test:unit        # Vitest unit tests (src/**/*.test.ts)
npx tsx scripts/take-screenshots.ts      # All 8 showcase screenshots
npx tsx scripts/take-screenshots.ts 2    # Single screenshot by index
npx tsx scripts/take-screenshots.ts composite  # Re-composite from existing raws

File Map — Where to Find Everything

By Purpose

src/components/

src/components/LogChart.tsx

src/components/logChart/

src/components/LogChart.styles.ts

src/domain/rules/

src/domain/engine/RuleEngine.ts

src/domain/types/Analysis.ts

src/domain/utils/CliExport.ts

src/lib/betaflight/cliOptions.ts

src/domain/blackbox/

src/workers/logParser.worker.ts

src/stores/

src/stores/RootStore.ts

src/theme/lightTheme.ts

src/theme/darkTheme.ts

src/theme/types.ts

src/theme/GlobalStyles.tsx

src/lib/mobx-reactivity/

src/serial/

src/domain/profiles/quadProfiles.ts

src/domain/utils/issueChartDescriptions.ts

src/data/changelog.ts

src/data/glossary.ts

vite.config.ts

.github/workflows/deploy.yml

vite-plugins/changelogPlugin.ts

e2e/

src/**/*.test.ts

playwright.config.ts

eslint.config.js

tsconfig.json

useDefineForClassFields: false

Key Files (Sorted by Importance)

src/App.tsx

src/stores/RootStore.ts

src/stores/AnalysisStore.ts

src/stores/LogStore.ts

src/stores/UIStore.ts

src/stores/SettingsStore.ts

src/stores/SerialStore.ts

src/stores/FlashDownloadStore.ts

src/domain/engine/RuleEngine.ts

src/domain/types/Analysis.ts

src/domain/types/LogFrame.ts

src/domain/types/TuningRule.ts

src/components/RecommendationsPanel.tsx

src/components/LogChart.tsx

src/components/logChart/useChartData.ts

src/components/logChart/useChartInteractions.ts

src/components/logChart/useIssueLabels.ts

src/components/logChart/useIssuePopover.ts

src/components/LogChart.styles.ts

src/components/FileUpload.tsx

src/workers/logParser.worker.ts

src/domain/utils/CliExport.ts

set

src/domain/utils/FrequencyAnalysis.ts

src/domain/utils/SignalAnalysis.ts

src/lib/betaflight/cliOptions.ts

Architecture at a Glance

User uploads .bbl/.bfl/.txt/.csv file
    ↓
LogStore.uploadFile() → spawns Web Worker
    ↓
Worker parses binary/text → postMessage({ type: 'complete', frames, metadata })
    ↓
LogStore sets frames + metadata → triggers AnalysisStore.analyze()
    ↓
RuleEngine.analyzeLog():
  1. Segment log into 100ms windows (50% overlap)
  2. Classify flight phase per window (idle/hover/cruise/punch/propwash/flip/roll)
  3. Run each rule: condition() → detect() → recommend()
  4. Temporal dedup issues (100ms gap merge, then collapse by type+axis)
  5. Cross-axis correlation (annotate patterns, generate hardware recs)
  6. Frequency issue merge (collapse same-freq frameResonance/bearingNoise across axes)
  7. Temporal progression analysis (annotate trends, generate meta-issues)
  8. Generate recommendations (settings-aware, with currentValue populated)
  9. Dedup recommendations (key on parameter:axis, not title)
  10. Generate summary + flight segments
    ↓
AnalysisStore.result populated → observer() components re-render
    ↓
LogChart shows traces + issue markers
RecommendationsPanel shows issues + recommendations + CLI export

Layer Rules

• Domain (

  src/domain/

  ): Pure TypeScript. NO React imports, NO MobX imports. Testable in isolation.
• Stores (

  src/stores/

  ): MobX

  makeAutoObservable

  . Business logic orchestration. Can reference domain layer.
• Components (

  src/components/

  ): React +

  observer()

  . Access stores via hooks. Emotion styled components.
• Workers (

  src/workers/

  ): Background threads. Can import domain layer. Communicate via

  postMessage

  .

How to Implement Common Tasks

New Tuning Rule

1. Create

   src/domain/rules/YourRule.ts

   conforming to

   TuningRule

   interface:

   export const YourRule: TuningRule = {
     id: 'your-rule',
     name: 'Your Rule',
     description: '...',
     baseConfidence: 0.7,
     issueTypes: ['yourIssueType'],
     applicableAxes: ['roll', 'pitch', 'yaw'],
     condition(window, frames) { return /* should this window be checked? */ },
     detect(window, frames, profile) { return /* DetectedIssue[] */ },
     recommend(issues, frames, profile) { return /* Recommendation[] */ },
   }
   

2. Add issue type to

   IssueType

   union in

   src/domain/types/Analysis.ts

3. Register rule in

   src/domain/engine/RuleEngine.ts

   constructor:

   this.registerRule(YourRule)

4. Add chart description in

   src/domain/utils/issueChartDescriptions.ts

5. If new parameters: add to

   BetaflightParameter

   union in

   Analysis.ts

   , map in

   CliExport.ts

6. Add thresholds per quad profile in

   src/domain/profiles/quadProfiles.ts

New React Component

import { observer } from 'mobx-react-lite'
import styled from '@emotion/styled'
import { useStores } from '../stores/RootStore'
import { useObservableState, useComputed, useAutorun } from '../lib/mobx-reactivity'

const Wrapper = styled.div`
  color: ${p => p.theme.colors.text.primary};
`

export const MyComponent = observer(() => {
  const { uiStore, analysisStore } = useStores()
  const [localState, setLocalState] = useObservableState(false)
  const derived = useComputed(() => analysisStore.issues.filter(i => i.severity === 'high'))

  useAutorun(() => {
    if (analysisStore.selectedIssue) {
      // side effect reacting to observable change
    }
  })

  return <Wrapper>...</Wrapper>
})

Rules:

• ALWAYS wrap with

  observer()

• NEVER use

  useState

  ,

  useEffect

  ,

  useMemo

  ,

  useCallback

• ALWAYS use

  useObservableState

  ,

  useComputed

  ,

  useAutorun

• ALWAYS use Emotion styled components (no inline styles, no CSS files, no Tailwind)
• Keep under 300 lines — split by domain/concern

New MobX Store

import { makeAutoObservable, runInAction } from 'mobx'

export class MyStore {
  publicField: string = ''
  private privateField: SomeType | null = null

  constructor() {
    makeAutoObservable<this, 'privateField'>(this, {
      privateField: false,  // exclude from observation
    })
  }

  get computed(): string {
    return this.publicField.toUpperCase()
  }

  someAction = (value: string): void => {
    this.publicField = value
  }

  someAsyncAction = async (): Promise<void> => {
    const result = await fetch(...)
    runInAction(() => {
      this.publicField = result
    })
  }

  reset = (): void => {
    this.publicField = ''
  }
}

Then wire in

src/stores/RootStore.ts

1. Add field:

   myStore: MyStore

2. Instantiate in constructor:

   this.myStore = new MyStore()

3. Add hook:

   export function useMyStore() { return useStores().myStore }

4. Add to

   reset()

   if applicable

New Betaflight Parameter

1. Add to

   BetaflightParameter

   union in

   src/domain/types/Analysis.ts

2. Add CLI mapping in

   src/domain/utils/CliExport.ts

   :
   • Per-axis →

     PER_AXIS_PARAMS

     map
   • Global →

     GLOBAL_PARAM_MAP

3. Add display name in

   PARAMETER_DISPLAY_NAMES

4. Add CLI option metadata in

   src/lib/betaflight/cliOptions.ts

5. Add value lookup in

   getPidValue()

   or

   getGlobalValue()

New Theme Color

1. Add to

   ThemeColors

   interface in

   src/theme/types.ts

2. Add values in

   src/theme/lightTheme.ts

   and

   src/theme/darkTheme.ts

3. Use in styled components:

   ${p => p.theme.colors.your.new.color}

New Modal

1. Add boolean toggle to

   UIStore

   :

   yourModalOpen = false

2. Add open/close actions in UIStore
3. Create component in

   src/components/YourModal.tsx

4. Render conditionally in

   src/App.tsx

   based on

   uiStore.yourModalOpen

Store Access Hooks

useStores()              // Full RootStore (all stores)
useLogStore()            // Parsed frames, metadata, parse status
useAnalysisStore()       // Analysis results, issues, recommendations, selection
useUIStore()             // Axis, zoom, panel state, modals, toasts
useThemeStore()          // Dark/light mode, theme object
useSettingsStore()       // Imported Betaflight settings
useSerialStore()         // USB serial connection state
useFlashDownloadStore()  // Flash download progress

8 Registered Tuning Rules

src/domain/rules/BouncebackRule.ts

bounceback

src/domain/rules/PropwashRule.ts

propwash

src/domain/rules/WobbleRule.ts

midThrottleWobble

src/domain/rules/TrackingQualityRule.ts

lowFrequencyOscillation

src/domain/rules/MotorSaturationRule.ts

motorSaturation

src/domain/rules/DTermNoiseRule.ts

dtermNoise

src/domain/rules/HighThrottleOscillationRule.ts

highThrottleOscillation

src/domain/rules/GyroNoiseRule.ts

gyroNoise

Testing Guide

Unit Tests (Vitest)

• Co-located with source:

  src/**/*.test.ts

• Run:

  pnpm test:unit

• Key test files:

  • src/domain/blackbox/BblParser.test.ts

    — Binary parser

  • src/domain/engine/RuleEngine.test.ts

    — Deduplication, segmentation

  • src/domain/engine/RuleEngineProfiles.test.ts

    — Profile thresholds

  • src/domain/rules/TrackingQualityRule.test.ts

    — Specific rule

  • src/domain/utils/CliExport.test.ts

    — CLI generation

  • src/components/logChart/useIssueLabels.test.ts

    — Label collision

E2E Tests (Playwright)

• Located in

  e2e/*.spec.ts

• Helpers:

  e2e/helpers.ts

  ,

  e2e/data-verification-helpers.ts

• Sample log:

  test-logs/shortLog.BFL

• Run:

  pnpm test

  (full),

  pnpm test:headed

  (visible browser)
• Config:

  playwright.config.ts

  — Chromium only, 1920x1080, 60s timeout
• Selectors: Use

  data-testid

  attributes
• No mocking: Real file uploads, real parsing, real analysis
• Upload helper:

  uploadAndAnalyze(page, filePath?)

  — uploads BFL and waits for analysis

Key test files:

file-upload.spec.ts

analysis-summary.spec.ts

analysis-details.spec.ts

chart-rendering.spec.ts

chart-interaction.spec.ts

issue-*.spec.ts

navigation-*.spec.ts

settings-review.spec.ts

data-verification-*.spec.ts

When to run tests:

• After changing domain logic → run unit tests + targeted E2E
• After changing UI → run targeted E2E spec
• Don't re-run ALL tests unless there's a strong reason they might fail

Commit Workflow

Writing Commit Messages

• Plain language for non-technical users
• One concern per commit — split unrelated changes
• Good: "Show build time in user's timezone on What's New modal"
• Bad: "Emit full ISO datetime from changelogPlugin and add formatBuildDate"

After Committing

If the change is user-facing, add an entry to

src/data/changelog.ts

{
  hash: 'abc1234',      // git short hash
  date: '2026-02-19',   // ISO date
  message: 'What the user sees changed',
  category: 'feature' | 'improvement' | 'fix',
}

CI/CD Pipeline

Push to

main

.github/workflows/deploy.yml

1. build —

   tsc && vite build

2. unit-tests —

   pnpm test:unit

3. integration-tests — Playwright across 16 shards
4. deploy — GitHub Pages (all 3 above must pass)

Key Deduplication Logic

Understanding this prevents confusion when working on analysis:

Issue Deduplication (RuleEngine)

1. Temporal merge: Issues of same type+axis within 100ms gap are merged into one
2. Collapse: Multiple occurrences become

   occurrences[]

   array with count
3. Result: One

   DetectedIssue

   per type+axis with occurrence count

Recommendation Deduplication (RuleEngine)

1. Key:

   parameter:axis

   from

   changes[]

   array (NOT title string)
2. Multiple rules recommending same parameter change are merged
3. Conflicting changes use weighted merge based on confidence

Dependencies

react

react-dom

mobx

mobx-react-lite

observer()

@emotion/react

@emotion/styled

recharts

@playwright/test

vitest

vite

vite-plugin-pwa

typescript

Critical Constraints

useDefineForClassFields: false

makeAutoObservable

observer()

any

useChartData.ts

Zoom System

Zoom is percentage-based (0–100%).

UIStore.zoomStart

zoomEnd

Minimum zoom window is enforced in 3 places — all must agree:

UIStore.setZoom()

useChartInteractions.ts

RangeSlider.tsx

The minimum is dynamic based on log duration so that full zoom always shows a 0.2s window:

const minZoomPct = (0.2 / totalDuration) * 100

LogChart.tsx

RangeSlider

minWindow

useChartInteractions

logStore.duration

Mobile Layout

• Breakpoint:

  max-width: 1599px

  → mobile layout

• UIStore.isMobileLayout

  observable (media query listener)
• Mobile: 3-tab bottom bar (Upload / Chart / Tune) via

  BottomTabBar

• Desktop: 3-panel layout (left / chart / right) with drag-to-resize
• Touch targets: minimum 36x36px, 18px font on

  pointer: coarse

• No serial options on mobile (WebSerial is desktop Chrome/Edge only)

Serial Communication (USB)

• src/serial/SerialPort.ts

  — WebSerial API wrapper

• src/serial/MspProtocol.ts

  — MSP protocol (read FC state)

• src/serial/CliProtocol.ts

  — Enter/exit CLI, read/write settings

• src/serial/DataflashReader.ts

  — Download blackbox from FC flash memory
• Chrome/Edge only (WebSerial API)
• Flow: connect → enter CLI → dump settings → parse → show in SettingsImportModal

Vite Plugins

changelogPlugin (

vite-plugins/changelogPlugin.ts

)

• Provides

  virtual:changelog

  module
• Injects:

  entries[]

  ,

  buildDate

  (ISO),

  buildHash

  (git short hash)
• Watches

  src/data/changelog.ts

  for HMR
• Used by ChangelogModal for "What's New" feature

Panel Resize Pattern (Drag Performance)

When resizing panels adjacent to the chart (expensive Recharts component):

1. Freeze inner chart wrapper at current pixel width on drag start
2. During drag: only change panel width via direct DOM (no MobX, no React re-renders)
3. On mouseup: clear inline styles, commit final width to MobX in single

   runInAction

4. Result: zero ResizeObserver fires, zero React re-renders during drag

Quad Profiles

5 profiles in

src/domain/profiles/quadProfiles.ts

actualThreshold = baseThreshold * profile.thresholds[issueType]