canmetry

Architecture

Canmetry Community is a fully client-side CAN log analysis app built with React, TanStack Router, and browser-side parsers for BLF / ASC / CSV / MF4 plus DBC decoding.

The repository is organized around one core idea:

Load raw CAN logs and DBC files in the browser, build an in-memory analysis session, then expose the same session through three UI surfaces: Graph, Trace, and DBC.

High-level flow

User files
  ├─ CAN log (.blf / .asc / .csv / .log / .mf4)
  └─ DBC files (.dbc)
        ↓
Browser file reads
        ↓
Format-specific parsers in src/lib/can/
        ↓
ClientAnalysisSession (single local workspace state)
        ├─ rawFrames
        ├─ decoded signal points
        ├─ DBC metadata
        ├─ channel ↔ DBC mapping
        └─ saved workspace layout
        ↓
UI tabs
  ├─ Graph  (decoded signals / chart workspace)
  ├─ Trace  (raw frames / decoded row detail)
  └─ DBC    (DBC browser / bit layout / attributes)

Runtime model

Single-page app shell

• src/router.tsx creates the TanStack Router instance
• src/routes/index.tsx is the main analysis screen
• The root route keeps the app inside one workspace and switches between:
  • graph
  • trace
  • dbc

This means all three views share the same loaded files and session state.

Session-first architecture

The main client-side state container is ClientAnalysisSession in src/modules/analyses/client-session.ts.

It owns:

• loaded log file name, size, and raw ArrayBuffer
• loaded DBC files
• detected CAN channels
• channel mapping
• extracted raw frame rows
• parsed signal catalog
• decoded point series
• trace rows and DBC lookup indices
• parse status / progress / error state

The session is exposed to React through useSyncExternalStore, so the app can keep one mutable analysis workspace without adding a global client state library.

Core modules

1. Log parsing

Location: src/lib/can/

Parsers are implemented in the browser and do not require a backend.

• blf-reader.ts — Vector BLF reader
• asc-reader.ts — Vector ASC / .log reader
• csv-reader.ts — CSV reader
• mf4-reader.ts — ASAM MDF4 reader
• iterate-log.ts — chooses parser by filename / extension

Shared frame shape:

• timestamp
• channel
• arbitration ID
• extended/remote/error flags
• CAN FD flags
• data bytes

The parser stage is intentionally loss-light: it first turns every supported format into a common frame model before higher-level decoding happens.

2. DBC loading and decoding

Location: src/lib/can/client-decode.ts

Responsibilities:

• load and normalize DBC text
• index DBC messages by CAN ID
• map selected DBC files to selected CAN channels
• decode matching frames into signal values
• build raw frame rows for Trace
• build signal catalogs and point series for Graph

Important behavior:

• parsing is channel-aware, so the same arbitration ID can decode differently on different channels
• raw frames stay available even when no DBC matches
• Graph points and Trace names are derived from the same underlying mapping

3. DBC catalog / viewer model

Location: src/lib/can/dbc-catalog.ts

This module builds a richer inspection model from DBC text for the DBC tab:

• messages
• signals
• nodes
• comments
• attributes
• value tables
• global/network metadata

This is separate from the runtime decode index because the DBC tab needs browse-oriented structures, not just ID lookup.

4. Project/workspace persistence

Location:

• src/lib/analysis-project.ts
• src/lib/analysis-workspace-layout.ts
• src/lib/analysis-workspace.ts

Project export/import stores:

• loaded log filename + size hint
• DBC filename list
• channel mapping
• added signals
• visible signals
• groups
• chart mode and zoom mode
• view window and Y ranges
• cursor positions
• current viewer tab

The exported file is .blfproject.json.

UI architecture

Main route and tab layout

src/routes/index.tsx renders a shared top toolbar and one of three panes:

• SignalViewer for Graph
• FrameViewer for Trace
• DbcViewer for DBC

The active tab is persisted into the layout snapshot so imported projects can reopen in the same view.

Graph

Main modules:

• src/blocks/signal-viewer/index.tsx
• src/blocks/signal-workspace/use-signal-workspace.ts
• src/blocks/signal-workspace/signal-chart.tsx
• src/blocks/signal-workspace/signal-table-panel.tsx

The Graph tab is a small workspace inside the app:

• left side: plotted signals table
• right side: custom SVG chart
• dialog: searchable signal picker
• toolbar actions: shortcuts/help and chart controls

The chart implementation is custom rather than Recharts-driven, because the app needs:

• stacked vs overlay modes
• cursor-driven inspection
• diff cursor
• per-series Y ranges
• box zoom / axis zoom / pan
• stepped signal rendering
• value-label axes for enumerated signals

Trace

Main modules:

• src/blocks/frame-viewer/index.tsx
• src/blocks/frame-viewer/FrameTable.tsx
• src/blocks/frame-viewer/FrameDetailPanel.tsx
• src/blocks/frame-viewer/frame-filter.ts
• src/blocks/frame-viewer/frame-bit-heatmap.ts
• src/blocks/frame-viewer/frame-sparkline.ts

Trace uses pre-extracted rawFrames from the session and layers on:

• filtering
• search matches
• table selection
• DBC-aware row decoding
• message-level sparkline summaries
• bit-flip heatmap for repeated frames of one message ID

DBC

Main modules:

• src/blocks/dbc-viewer/index.tsx
• src/blocks/dbc-viewer/message-list.tsx
• src/blocks/dbc-viewer/signal-table.tsx
• src/blocks/dbc-viewer/bit-matrix.tsx
• src/blocks/dbc-viewer/detail-panel.tsx
• src/blocks/dbc-viewer/bit-layout.ts

The DBC tab is independent from signal parsing in the sense that:

• you can browse DBC content without parsing a log
• it provides a documentation / reverse-engineering view of the database itself

The layout is optimized for fast inspection:

• message list
• signal table
• bit matrix
• collapsible detail panel
• alternate node/network scopes

Data lifecycle

Loading a log

1. User selects a log file
2. ClientAnalysisSession.loadLog() validates size and format
3. extractRawFramesFromLog() scans frames into a common raw row model
4. Channels are detected from the parsed frames
5. Graph/Trace reset to uploaded state

Loading DBC files

1. User adds one or more .dbc files
2. DBC text is read in-browser
3. Files are stored in session by generated local IDs
4. No decode happens yet until channel mapping + parse

Parsing

1. User maps DBC files to channels on the Channel Mapping card
2. Clicking Start parsing on that card applies the mapping and starts decode (no separate menu step required)
3. decodeLogWithDbcs() iterates log frames again
4. Matching frame IDs are decoded into signal values
5. A signal catalog + point arrays are built
6. Trace rows are annotated with frame/message names
7. Graph becomes ready and auto-adds the first signal when appropriate

Deployment model

The app is designed for static hosting.

• local development: pnpm dev
• production build: pnpm build
• GitHub Pages build: pnpm build:pages

No server-side parsing, database, queue, or worker is required for the community edition.

Important implementation constraints

• Large files are bounded by client-side limits to avoid freezing the tab
• Parsing progress is surfaced to the UI during long browser-side decode
• Raw frame extraction and decoded signal generation are separated so Trace can still work well
• Channel mapping is explicit and persisted in project files
• The app intentionally keeps file contents local for privacy

Key files

Path	Purpose
src/routes/index.tsx	Main page and Graph/Trace/DBC tab switching
src/modules/analyses/client-session.ts	Local analysis session state
src/lib/can/client-decode.ts	DBC decode pipeline, raw rows, parse results
src/lib/can/iterate-log.ts	Format detection and parser dispatch
src/lib/analysis-project.ts	Project export/import schema
src/blocks/signal-workspace/	Graph workspace
src/blocks/frame-viewer/	Trace UI
src/blocks/dbc-viewer/	DBC browser UI

This site is open source. Improve this page.