# vennarbank/fueltracker architecture

> Architecture diagram of the GitHub repository vennarbank/fueltracker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vennarbank/fueltracker
- Repository: https://github.com/vennarbank/fueltracker

## Overview

1. This repository is a client-side fuel tracking app built as a React + TypeScript frontend and packaged for Android with Capacitor. There is no backend service in the tree, so the main architecture is a single UI application plus a native Android host.

2. The web application is the primary runtime. `src/main.tsx` mounts the app into `index.html`, and `src/App.tsx` is the top-level composition root. Global styling lives in `src/index.css` and `src/App.css`.

3. The UI is split into feature-oriented components under `src/components/`: `FuelForm`, `LogList`, `Dashboard`, `Analytics`, and `Settings`. These names suggest a domain centered on fuel-entry capture, history review, summary metrics, and user preferences.

4. `src/types.ts` is the shared domain contract for the app. It likely defines the data shapes passed between the form, list, dashboard, and analytics views, keeping the feature components aligned around the same fuel-log model.

5. `App.tsx` is the orchestration boundary: it likely owns the shared app state and routes data between the feature components. The expected flow is user input in `FuelForm`, state updates in the app root, then derived views in `Dashboard`, `LogList`, and `Analytics`, with `Settings` influencing display or behavior.

6. `AndroidFrame.tsx` indicates there is some platform-aware UI layering on top of the core React app. It likely helps adapt the interface or layout when running inside the Android/Capacitor container versus a plain browser build.

7. The Android side under `android/` is a Capacitor wrapper, not a separate business-logic implementation. `MainActivity.java` is the native entry point, while `AndroidManifest.xml`, resource folders, `activity_main.xml`, and `file_paths.xml` provide the standard Android app shell and platform configuration.

8. The Android wrapper contains the generated Gradle build structure (`android/app/build.gradle`, `android/build.gradle`, `gradle.properties`, Gradle wrapper files). This layer’s role is packaging, permissions, and runtime hosting of the web assets in an Android WebView.

9. Test scaffolding exists on both sides: `src` has no visible test files, but Android includes unit and instrumented test placeholders under `android/app/src/test` and `android/app/src/androidTest`. That indicates the repo currently relies mostly on component-level development plus template Android test harnesses.

10. The build/tooling stack is Vite for the web app (`vite.config.ts`), TypeScript (`tsconfig*.json`), and ESLint (`eslint.config.js`). `capacitor.config.ts` connects the web build to the native Android packaging step.

11. Architecturally, the important boundary is between the pure React domain/UI layer and the Capacitor Android host. All domain behavior appears to live in TypeScript components; Android mostly serves as a container unless additional native plugins are added later.

12. There is no sign of remote API integration, state server, or database layer in the repository tree. For an architecture diagram, this should be treated as a mostly self-contained offline-capable client app with optional native Android packaging.

Main entry points: [`src/App.tsx`](https://github.com/vennarbank/fueltracker/blob/master/src/App.tsx) (App root), [`src/types.ts`](https://github.com/vennarbank/fueltracker/blob/master/src/types.ts) (Domain types), [`android/app/src/main/java/com/fuelflow/app/MainActivity.java`](https://github.com/vennarbank/fueltracker/blob/master/android/app/src/main/java/com/fuelflow/app/MainActivity.java) (Main activity), [`src/main.tsx`](https://github.com/vennarbank/fueltracker/blob/master/src/main.tsx) (Entry point)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["React app"]
  node_main(("Entry point<br/>React boot<br/>[main.tsx]"))
  node_app["App root<br/>UI orchestration<br/>[App.tsx]"]
  node_types["Domain types<br/>shared model<br/>[types.ts]"]
  node_fuelform["Fuel form<br/>entry feature<br/>[FuelForm.tsx]"]
  node_loglist["Log list<br/>history feature<br/>[LogList.tsx]"]
  node_dashboard["Dashboard<br/>summary feature<br/>[Dashboard.tsx]"]
  node_analytics["Analytics<br/>insights feature<br/>[Analytics.tsx]"]
  node_settings["Settings<br/>preferences feature<br/>[Settings.tsx]"]
  node_androidframe["Android frame<br/>platform shell<br/>[AndroidFrame.tsx]"]
  node_styles["Global styles<br/>css<br/>[index.css]"]
  node_appstyles["App styles<br/>css<br/>[App.css]"]
end

subgraph group_android["Android host"]
  node_activity(("Main activity<br/>Android entry<br/>[MainActivity.java]"))
  node_manifest["Android manifest<br/>android config"]
  node_layout["Main layout<br/>android layout<br/>[activity_main.xml]"]
  node_filepaths["File paths<br/>android config<br/>[file_paths.xml]"]
  node_appgradle["App gradle<br/>android build<br/>[build.gradle]"]
  node_rootgradle["Root gradle<br/>android build<br/>[build.gradle]"]
end

subgraph group_tooling["Build tooling"]
  node_capacitorcfg["Capacitor config<br/>bridge config"]
  node_vite["Vite config<br/>web build<br/>[vite.config.ts]"]
  node_tsconfig["TypeScript config<br/>ts config<br/>[tsconfig.json]"]
  node_eslint["ESLint config<br/>[eslint.config.js]"]
end

node_main -->|"mounts"| node_app
node_app -->|"uses"| node_types
node_app -->|"coordinates"| node_fuelform
node_app -->|"feeds"| node_loglist
node_app -->|"derives"| node_dashboard
node_app -->|"derives"| node_analytics
node_app -->|"applies"| node_settings
node_app -.->|"adapts"| node_androidframe
node_app -->|"styles"| node_styles
node_app -->|"styles"| node_appstyles
node_fuelform -->|"reads/writes"| node_types
node_loglist -->|"reads"| node_types
node_dashboard -->|"reads"| node_types
node_analytics -->|"reads"| node_types
node_settings -->|"reads"| node_types
node_activity -->|"declares"| node_manifest
node_activity -->|"hosts"| node_layout
node_activity -->|"relies on"| node_filepaths
node_appgradle -->|"inherits"| node_rootgradle
node_capacitorcfg -.->|"bridges"| node_appgradle
node_vite -->|"builds"| node_main
node_tsconfig -->|"compiles"| node_main
node_eslint -->|"checks"| node_app

click node_main "https://github.com/vennarbank/fueltracker/blob/master/src/main.tsx"
click node_app "https://github.com/vennarbank/fueltracker/blob/master/src/App.tsx"
click node_types "https://github.com/vennarbank/fueltracker/blob/master/src/types.ts"
click node_fuelform "https://github.com/vennarbank/fueltracker/blob/master/src/components/FuelForm.tsx"
click node_loglist "https://github.com/vennarbank/fueltracker/blob/master/src/components/LogList.tsx"
click node_dashboard "https://github.com/vennarbank/fueltracker/blob/master/src/components/Dashboard.tsx"
click node_analytics "https://github.com/vennarbank/fueltracker/blob/master/src/components/Analytics.tsx"
click node_settings "https://github.com/vennarbank/fueltracker/blob/master/src/components/Settings.tsx"
click node_androidframe "https://github.com/vennarbank/fueltracker/blob/master/src/components/AndroidFrame.tsx"
click node_styles "https://github.com/vennarbank/fueltracker/blob/master/src/index.css"
click node_appstyles "https://github.com/vennarbank/fueltracker/blob/master/src/App.css"
click node_activity "https://github.com/vennarbank/fueltracker/blob/master/android/app/src/main/java/com/fuelflow/app/MainActivity.java"
click node_manifest "https://github.com/vennarbank/fueltracker/blob/master/android/app/src/main/AndroidManifest.xml"
click node_layout "https://github.com/vennarbank/fueltracker/blob/master/android/app/src/main/res/layout/activity_main.xml"
click node_filepaths "https://github.com/vennarbank/fueltracker/blob/master/android/app/src/main/res/xml/file_paths.xml"
click node_appgradle "https://github.com/vennarbank/fueltracker/blob/master/android/app/build.gradle"
click node_rootgradle "https://github.com/vennarbank/fueltracker/blob/master/android/build.gradle"
click node_capacitorcfg "https://github.com/vennarbank/fueltracker/blob/master/capacitor.config.ts"
click node_vite "https://github.com/vennarbank/fueltracker/blob/master/vite.config.ts"
click node_tsconfig "https://github.com/vennarbank/fueltracker/blob/master/tsconfig.json"
click node_eslint "https://github.com/vennarbank/fueltracker/blob/master/eslint.config.js"

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_main,node_app,node_types,node_fuelform,node_loglist,node_dashboard,node_analytics,node_settings,node_androidframe,node_styles,node_appstyles toneBlue
class node_activity,node_manifest,node_layout,node_filepaths,node_appgradle,node_rootgradle toneAmber
class node_capacitorcfg,node_vite,node_tsconfig,node_eslint toneMint
```

## Components

### React app

Client-side fuel tracking UI and shared domain logic.

- [Entry point](https://github.com/vennarbank/fueltracker/blob/master/src/main.tsx): React boot · Mounts the application into the browser DOM. · `src/main.tsx`
- [App root](https://github.com/vennarbank/fueltracker/blob/master/src/App.tsx): UI orchestration · Top-level composition root and shared state boundary. · `src/App.tsx`
- [Domain types](https://github.com/vennarbank/fueltracker/blob/master/src/types.ts): shared model · Common fuel-log data contracts used across features. · `src/types.ts`
- [Fuel form](https://github.com/vennarbank/fueltracker/blob/master/src/components/FuelForm.tsx): entry feature · Captures new fuel log input from the user. · `src/components/FuelForm.tsx`
- [Log list](https://github.com/vennarbank/fueltracker/blob/master/src/components/LogList.tsx): history feature · Shows saved fuel entries and history views. · `src/components/LogList.tsx`
- [Dashboard](https://github.com/vennarbank/fueltracker/blob/master/src/components/Dashboard.tsx): summary feature · Presents high-level status and key totals. · `src/components/Dashboard.tsx`
- [Analytics](https://github.com/vennarbank/fueltracker/blob/master/src/components/Analytics.tsx): insights feature · Derives trends and aggregate metrics from logs. · `src/components/Analytics.tsx`
- [Settings](https://github.com/vennarbank/fueltracker/blob/master/src/components/Settings.tsx): preferences feature · Controls app behavior and display preferences. · `src/components/Settings.tsx`
- [Android frame](https://github.com/vennarbank/fueltracker/blob/master/src/components/AndroidFrame.tsx): platform shell · Adapts the React UI for the Android/Capacitor container. · `src/components/AndroidFrame.tsx`
- [Global styles](https://github.com/vennarbank/fueltracker/blob/master/src/index.css): css · Shared application styling for the React UI. · `src/index.css`
- [App styles](https://github.com/vennarbank/fueltracker/blob/master/src/App.css): css · Component-level styling for the app shell. · `src/App.css`

### Android host

Capacitor wrapper and native Android packaging layer.

- [Main activity](https://github.com/vennarbank/fueltracker/blob/master/android/app/src/main/java/com/fuelflow/app/MainActivity.java): Android entry · Native Android entry point hosting the web view. · `android/app/src/main/java/com/fuelflow/app/MainActivity.java`
- [Android manifest](https://github.com/vennarbank/fueltracker/blob/master/android/app/src/main/AndroidManifest.xml): android config · Declares the Android application and its runtime setup. · `android/app/src/main/AndroidManifest.xml`
- [Main layout](https://github.com/vennarbank/fueltracker/blob/master/android/app/src/main/res/layout/activity_main.xml): android layout · Defines the native activity container layout. · `android/app/src/main/res/layout/activity_main.xml`
- [File paths](https://github.com/vennarbank/fueltracker/blob/master/android/app/src/main/res/xml/file_paths.xml): android config · Configures native file access paths for the wrapper. · `android/app/src/main/res/xml/file_paths.xml`
- [App gradle](https://github.com/vennarbank/fueltracker/blob/master/android/app/build.gradle): android build · Module-level Android build configuration. · `android/app/build.gradle`
- [Root gradle](https://github.com/vennarbank/fueltracker/blob/master/android/build.gradle): android build · Project-level Android build configuration. · `android/build.gradle`

### Build tooling

Frontend and Android build configuration.

- [Capacitor config](https://github.com/vennarbank/fueltracker/blob/master/capacitor.config.ts): bridge config · Connects the web build to the Android wrapper. · `capacitor.config.ts`
- [Vite config](https://github.com/vennarbank/fueltracker/blob/master/vite.config.ts): web build · Frontend build and dev-server configuration. · `vite.config.ts`
- [TypeScript config](https://github.com/vennarbank/fueltracker/blob/master/tsconfig.json): ts config · TypeScript compiler settings for the app and tooling. · `tsconfig.json`
- [ESLint config](https://github.com/vennarbank/fueltracker/blob/master/eslint.config.js): lint config · Code quality and linting rules for the frontend. · `eslint.config.js`

## Connections

- Entry point → App root: mounts · Bootstraps the root React tree.
- App root → Domain types: uses · Shares domain contracts across the UI.
- App root → Fuel form: coordinates · Receives user input and updates shared state.
- App root → Log list: feeds · Passes log data to history display.
- App root → Dashboard: derives · Supplies summary metrics and totals.
- App root → Analytics: derives · Supplies aggregated data for insights.
- App root → Settings: applies · Distributes user preferences through the app.
- App root → Android frame: adapts · Wraps the UI for Android-specific presentation.
- App root → Global styles: styles · Uses global CSS for base presentation.
- App root → App styles: styles · Uses app-specific CSS rules.
- Fuel form → Domain types: reads/writes · Uses shared fuel-log data shapes.
- Log list → Domain types: reads · Renders fuel entries using shared types.
- Dashboard → Domain types: reads · Computes summary views from the domain model.
- Analytics → Domain types: reads · Computes trends and aggregates from the domain model.
- Settings → Domain types: reads · Uses shared state and preference-related domain data.
- Main activity → Android manifest: declares · Android activity and app entry are registered in the manifest.
- Main activity → Main layout: hosts · Uses the native layout as the activity container.
- Main activity → File paths: relies on · Native file access configuration supports the wrapper.
- App gradle → Root gradle: inherits · Module build depends on project-level Android build setup.
- Capacitor config → App gradle: bridges · Capacitor connects the web build to the Android package.
- Vite config → Entry point: builds · Bundles the React entry for browser and mobile web views.
- TypeScript config → Entry point: compiles · TypeScript settings govern the frontend source.
- ESLint config → App root: checks · Linting targets the React application code.