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

Key Files (Sorted by Importance)

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

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:

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

Critical Constraints

Zoom System

Zoom is percentage-based (0–100%). UIStore.zoomStart / zoomEnd define the visible window.

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

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 computes this and passes it to RangeSlider via the minWindow prop. The chart scroll handler in useChartInteractions computes the same value from 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]