# sergio-deluich-kaufmann/traccio architecture

> Architecture diagram of the GitHub repository sergio-deluich-kaufmann/traccio, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sergio-deluich-kaufmann/traccio
- Repository: https://github.com/sergio-deluich-kaufmann/traccio

## Overview

Traccio is a local desktop running log: a user selects a name-matched Excel workbook, then explores summaries from year to month to day. The main process loads runs and computes summaries, pace, calendar data, and estimated calories; the React renderer presents those results through a back-stack navigation flow. The README documents the process boundary and workbook workflow; sampled source confirms the data calculations, IPC handler ownership, and screen routing. Some screen-to-API calls are not visible in the excerpts, so links across that boundary rely on the README.

Main entry points: [`src/renderer/src/App.tsx`](https://github.com/sergio-deluich-kaufmann/traccio/blob/main/src/renderer/src/App.tsx) (App router), [`src/preload/index.ts`](https://github.com/sergio-deluich-kaufmann/traccio/blob/main/src/preload/index.ts) (Typed preload bridge), [`src/main/ipcHandlers.ts`](https://github.com/sergio-deluich-kaufmann/traccio/blob/main/src/main/ipcHandlers.ts) (IPC handlers), [`src/renderer/src/screens/MonthDetailScreen.tsx`](https://github.com/sergio-deluich-kaufmann/traccio/blob/main/src/renderer/src/screens/MonthDetailScreen.tsx) (Month detail)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_renderer["Renderer experience"]
  node_verification["Name verification"]
  node_year_screen["Year selection"]
  node_month_screen["Month selection"]
  node_month_detail["Month detail"]
  node_day_screen["Day detail<br/>[DayViewScreen.tsx]"]
  node_app_router["App router<br/>[App.tsx]"]
  node_navigation["Navigation stack"]
  node_year_grid["Year grid<br/>[YearGrid.tsx]"]
  node_month_grid["Month grid<br/>[MonthGrid.tsx]"]
  node_calendar["Activity calendar<br/>[CalendarGrid.tsx]"]
  node_pace_chart["Pace trend chart<br/>[PaceTrendChart.tsx]"]
  node_theme["Theme controls<br/>[ThemeContext.tsx]"]
end

subgraph group_bridge["Desktop bridge"]
  node_preload["Typed preload bridge<br/>[index.ts]"]
  node_handlers["IPC handlers<br/>[ipcHandlers.ts]"]
end

subgraph group_domain["Run data domain"]
  node_data_service["Workbook analytics<br/>[dataService.ts]"]
end

subgraph group_persistence["Local persistence"]
  node_workbooks[("Excel workbooks")]
  node_settings[("Saved user name")]
end

node_runner(("Runner"))

node_runner -->|"enters name"| node_verification
node_app_router -->|"routes to"| node_verification
node_app_router -->|"routes to"| node_year_screen
node_app_router -->|"routes to"| node_month_screen
node_app_router -->|"routes to"| node_month_detail
node_app_router -->|"routes to"| node_day_screen
node_app_router -->|"uses state"| node_navigation
node_year_screen -->|"renders"| node_year_grid
node_month_screen -->|"renders"| node_month_grid
node_month_detail -->|"renders"| node_calendar
node_month_detail -->|"renders"| node_pace_chart
node_verification -->|"requests data"| node_preload
node_year_screen -->|"requests summaries"| node_preload
node_month_screen -->|"requests summaries"| node_preload
node_month_detail -->|"requests detail"| node_preload
node_day_screen -->|"requests detail"| node_preload
node_preload -->|"invokes IPC"| node_handlers
node_handlers -->|"loads and queries"| node_data_service
node_handlers -->|"reads or writes"| node_settings
node_data_service -->|"reads workbook"| node_workbooks
node_handlers -->|"returns results"| node_data_service
node_data_service -->|"returns summaries"| node_handlers

click node_verification "https://github.com/sergio-deluich-kaufmann/traccio/blob/main/src/renderer/src/screens/UserVerificationScreen.tsx"
click node_year_screen "https://github.com/sergio-deluich-kaufmann/traccio/blob/main/src/renderer/src/screens/YearSelectionScreen.tsx"
click node_month_screen "https://github.com/sergio-deluich-kaufmann/traccio/blob/main/src/renderer/src/screens/MonthSelectionScreen.tsx"
click node_month_detail "https://github.com/sergio-deluich-kaufmann/traccio/blob/main/src/renderer/src/screens/MonthDetailScreen.tsx"
click node_day_screen "https://github.com/sergio-deluich-kaufmann/traccio/blob/main/src/renderer/src/screens/DayViewScreen.tsx"
click node_app_router "https://github.com/sergio-deluich-kaufmann/traccio/blob/main/src/renderer/src/App.tsx"
click node_navigation "https://github.com/sergio-deluich-kaufmann/traccio/blob/main/src/renderer/src/navigation/NavigationContext.tsx"
click node_year_grid "https://github.com/sergio-deluich-kaufmann/traccio/blob/main/src/renderer/src/components/YearGrid.tsx"
click node_month_grid "https://github.com/sergio-deluich-kaufmann/traccio/blob/main/src/renderer/src/components/MonthGrid.tsx"
click node_calendar "https://github.com/sergio-deluich-kaufmann/traccio/blob/main/src/renderer/src/components/CalendarGrid.tsx"
click node_pace_chart "https://github.com/sergio-deluich-kaufmann/traccio/blob/main/src/renderer/src/components/PaceTrendChart.tsx"
click node_theme "https://github.com/sergio-deluich-kaufmann/traccio/blob/main/src/renderer/src/theme/ThemeContext.tsx"
click node_preload "https://github.com/sergio-deluich-kaufmann/traccio/blob/main/src/preload/index.ts"
click node_handlers "https://github.com/sergio-deluich-kaufmann/traccio/blob/main/src/main/ipcHandlers.ts"
click node_data_service "https://github.com/sergio-deluich-kaufmann/traccio/blob/main/src/main/dataService.ts"
click node_workbooks "https://github.com/sergio-deluich-kaufmann/traccio/tree/main/data"
click node_settings "https://github.com/sergio-deluich-kaufmann/traccio/blob/main/src/main/userSettingsService.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_verification,node_year_screen,node_month_screen,node_month_detail,node_day_screen,node_app_router,node_navigation,node_year_grid,node_month_grid,node_calendar,node_pace_chart,node_theme toneBlue
class node_preload,node_handlers toneAmber
class node_data_service toneMint
class node_workbooks,node_settings toneRose
class node_runner toneIndigo
```

## Components

### Renderer experience

- [Name verification](https://github.com/sergio-deluich-kaufmann/traccio/blob/main/src/renderer/src/screens/UserVerificationScreen.tsx): `src/renderer/src/screens/UserVerificationScreen.tsx`
- [Year selection](https://github.com/sergio-deluich-kaufmann/traccio/blob/main/src/renderer/src/screens/YearSelectionScreen.tsx): `src/renderer/src/screens/YearSelectionScreen.tsx`
- [Month selection](https://github.com/sergio-deluich-kaufmann/traccio/blob/main/src/renderer/src/screens/MonthSelectionScreen.tsx): `src/renderer/src/screens/MonthSelectionScreen.tsx`
- [Month detail](https://github.com/sergio-deluich-kaufmann/traccio/blob/main/src/renderer/src/screens/MonthDetailScreen.tsx): `src/renderer/src/screens/MonthDetailScreen.tsx`
- [Day detail](https://github.com/sergio-deluich-kaufmann/traccio/blob/main/src/renderer/src/screens/DayViewScreen.tsx): `src/renderer/src/screens/DayViewScreen.tsx`
- [App router](https://github.com/sergio-deluich-kaufmann/traccio/blob/main/src/renderer/src/App.tsx): `src/renderer/src/App.tsx`
- [Navigation stack](https://github.com/sergio-deluich-kaufmann/traccio/blob/main/src/renderer/src/navigation/NavigationContext.tsx): `src/renderer/src/navigation/NavigationContext.tsx`
- [Year grid](https://github.com/sergio-deluich-kaufmann/traccio/blob/main/src/renderer/src/components/YearGrid.tsx): `src/renderer/src/components/YearGrid.tsx`
- [Month grid](https://github.com/sergio-deluich-kaufmann/traccio/blob/main/src/renderer/src/components/MonthGrid.tsx): `src/renderer/src/components/MonthGrid.tsx`
- [Activity calendar](https://github.com/sergio-deluich-kaufmann/traccio/blob/main/src/renderer/src/components/CalendarGrid.tsx): `src/renderer/src/components/CalendarGrid.tsx`
- [Pace trend chart](https://github.com/sergio-deluich-kaufmann/traccio/blob/main/src/renderer/src/components/PaceTrendChart.tsx): `src/renderer/src/components/PaceTrendChart.tsx`
- [Theme controls](https://github.com/sergio-deluich-kaufmann/traccio/blob/main/src/renderer/src/theme/ThemeContext.tsx): `src/renderer/src/theme/ThemeContext.tsx`

### Desktop bridge

- [Typed preload bridge](https://github.com/sergio-deluich-kaufmann/traccio/blob/main/src/preload/index.ts): `src/preload/index.ts`
- [IPC handlers](https://github.com/sergio-deluich-kaufmann/traccio/blob/main/src/main/ipcHandlers.ts): `src/main/ipcHandlers.ts`

### Run data domain

- [Workbook analytics](https://github.com/sergio-deluich-kaufmann/traccio/blob/main/src/main/dataService.ts): `src/main/dataService.ts`

### Local persistence

- [Excel workbooks](https://github.com/sergio-deluich-kaufmann/traccio/tree/main/data): `data`
- [Saved user name](https://github.com/sergio-deluich-kaufmann/traccio/blob/main/src/main/userSettingsService.ts): `src/main/userSettingsService.ts`

### Other components

- **Runner**

## Connections

- Runner → Name verification: enters name (evidence: `README.md`)
- App router → Name verification: routes to (evidence: `src/renderer/src/App.tsx`)
- App router → Year selection: routes to (evidence: `src/renderer/src/App.tsx`)
- App router → Month selection: routes to (evidence: `src/renderer/src/App.tsx`)
- App router → Month detail: routes to (evidence: `src/renderer/src/App.tsx`)
- App router → Day detail: routes to (evidence: `src/renderer/src/App.tsx`)
- App router → Navigation stack: uses state (evidence: `src/renderer/src/App.tsx`)
- Year selection → Year grid: renders (evidence: `src/renderer/src/screens/YearSelectionScreen.tsx`)
- Month selection → Month grid: renders (evidence: `src/renderer/src/screens/MonthSelectionScreen.tsx`)
- Month detail → Activity calendar: renders (evidence: `src/renderer/src/screens/MonthDetailScreen.tsx`)
- Month detail → Pace trend chart: renders (evidence: `src/renderer/src/screens/MonthDetailScreen.tsx`)
- Name verification → Typed preload bridge: requests data (evidence: `README.md`)
- Year selection → Typed preload bridge: requests summaries (evidence: `README.md`)
- Month selection → Typed preload bridge: requests summaries (evidence: `README.md`)
- Month detail → Typed preload bridge: requests detail (evidence: `README.md`)
- Day detail → Typed preload bridge: requests detail (evidence: `README.md`)
- Typed preload bridge → IPC handlers: invokes IPC (evidence: `README.md`)
- IPC handlers → Workbook analytics: loads and queries (evidence: `src/main/ipcHandlers.ts`)
- IPC handlers → Saved user name: reads or writes (evidence: `src/main/ipcHandlers.ts`)
- Workbook analytics → Excel workbooks: reads workbook (evidence: `src/main/dataService.ts`)
- IPC handlers → Workbook analytics: returns results (evidence: `src/main/ipcHandlers.ts`)
- Workbook analytics → IPC handlers: returns summaries (evidence: `src/main/ipcHandlers.ts`)
