Architecture Overview

FitFileViewer is built as a cross-platform desktop application using Electron with a modular, scalable architecture.

High-Level Architecture

Key Principles

🔐 Security-First

• Context isolation enabled
• Node integration disabled in renderer
• Secure IPC communication
• Input validation

📦 Modularity

• 50+ utility modules
• Clear separation of concerns
• Reusable components
• Single responsibility

⚡ Performance

• Lazy loading
• Efficient data processing
• Memory management
• Caching strategies

Technology Stack

Layer	Technology	Purpose
Framework	Electron	Cross-platform desktop
UI	HTML/CSS/JS	User interface
Charts	Chart.js, Vega-Lite	Data visualization
Maps	Leaflet	Geographic display
Tables	DataTables	Data grid
Parser	Garmin FIT SDK	FIT file parsing

Component Layers

Process Model

FitFileViewer uses Electron's multi-process architecture:

Process	Responsibilities
Main	App lifecycle, window management, file system, IPC
Renderer	UI rendering, user interaction, visualization
Preload	Secure bridge between main and renderer

Module Organization

electron-app/
├── main.ts           # Main process source entry
├── renderer.ts       # Renderer process source entry
├── preload.ts        # Security bridge source
├── main-ui.ts        # UI management source
├── fitParser.ts      # FIT file parsing source
└── utils/            # Utility modules
    ├── formatting/   # Data formatters
    ├── maps/         # Map utilities
    ├── charts/       # Chart utilities
    ├── state/        # State management
    └── ...           # More modules

Data Flow

Security Model

IPC Security

All communication between processes uses validated channels:

// Preload - Exposed API
contextBridge.exposeInMainWorld("electronAPI", {
 openFile: () => ipcRenderer.invoke("dialog:open-fit-file"),
 // Only specific, validated operations
});

Content Security

• No remote content loading
• Strict CSP headers
• Sandboxed renderer

---

Next: Process Architecture →