Fuelog

---

📖 About The Project

Fuelog is a mobile-first Progressive Web App designed for logging fuel fill-ups, tracking efficiency trends, and managing costs across multiple vehicles. With features like AI receipt scanning via Gemini, real-time geolocation, and multi-currency support, it transforms the chore of tracking fuel into a seamless, automated experience.

Whether you're managing a single daily driver or a small fleet, Fuelog provides the analytics you need to build a comprehensive picture of your fuel spend over time.

---

✨ Features

• ⚡ Frictionless Logging: Log cost, litres, and distance in a single screen.
• 🧠 AI Receipt Scanning: Snap a photo of your receipt and Gemini extracts the data automatically.
• 📍 Geolocation: Captures the fill-up position for map and station tracking.
• 🚗 Multi-Vehicle Support: Manage unlimited vehicles (make, model, year, fuel type).
• 💱 Multi-Currency: Log fills in 30+ currencies with automatic exchange rates via Frankfurter API.
• 📊 Rich Analytics: Efficiency metrics (km/L, L/100km, MPG), trend charts with Recharts, and lifetime totals.
• 🗺️ Station Tracking: Track every filling station, view average prices, and see a cluster map of all locations.
• 🌍 Internationalisation: Available in English, Irish (Gaeilge), German, Spanish, French, Finnish, Japanese, Korean, Norwegian, and Swedish.

---

🛠 Tech Stack

Built with modern web technologies:

• Frontend: React 19, TypeScript, Vite
• Styling: Tailwind CSS v4
• Backend / DB: Firebase (Auth, Firestore, Storage, Remote Config, FCM)
• AI Integration: Google Gemini
• Maps: Leaflet, react-leaflet
• Charts: Recharts
• Testing: Vitest, Playwright

---

🚀 Getting Started

Follow these instructions to get a copy of the project up and running on your local machine.

Prerequisites

• Node.js (LTS)
• npm
• A Firebase project with Authentication (Google provider), Firestore, and Storage enabled.

Installation

1. Clone the repository:

   git clone https://github.com/Irishsmurf/fuelog.git
   cd fuelog
   

2. Install dependencies:

   npm install
   

3. Configure environment variables: Copy the example below into a .env file at the project root. Never commit this file to version control.

   # Firebase — required
   VITE_FIREBASE_API_KEY=
   VITE_FIREBASE_AUTH_DOMAIN=
   VITE_FIREBASE_PROJECT_ID=
   VITE_FIREBASE_STORAGE_BUCKET=
   VITE_FIREBASE_MESSAGING_SENDER_ID=
   VITE_FIREBASE_APP_ID=
   
   # Google Gemini — optional, enables AI receipt scanning
   VITE_GEMINI_API_KEY=
   VITE_GEMINI_MODEL=gemini-2.5-flash
   VITE_GEMINI_THINKING_LEVEL=low
   
   # CARTO basemaps — optional. Maps work without it; the log-card thumbnails
   # fall back to CARTO's keyless raster tiles, which carry an "API KEY
   # REQUIRED" watermark. Free key (no account needed):
   # https://carto.com/basemaps/apikey
   VITE_CARTO_API_KEY=
   

4. Start the development server:

   npm run dev
   

Open http://localhost:5173 to view it in your browser.

---

📚 Documentation

For deep-dives into the architecture, APIs, and integrations, explore our documentation:

• Architecture - System design, Firestore schema, service layers
• REST API - API endpoints & authentication
• MCP Server - Connect LLMs to your fuel data
• Firebase Setup - Firestore rules, Storage config, FCM setup
• Gemini Integration - AI receipt extraction configuration
• Features & Roadmap - Full reference and planned milestones
• User Flows - End-to-end user journey documentation

---

🎨 Branding & Design Guidelines

Fuelog's visual identity is built around the petrol forecourt at night — the amber glow of price boards and the industrial precision of pump readouts.

• Primary Colour: Amber 600 (#D97706) / Amber 400 (#FBBF24)
• Surface: Petroleum (#0A0F1E) for dark mode, Near white (#F9FAFB) for light mode.
• Typography: Space Grotesk (Display), Inter (Body), Space Mono (Data).
• Wordmark: Lowercase fuelog set in Space Grotesk Bold, with a split tone (#F59E0B / #374151).

Every design decision should serve legibility and functional confidence, not decoration. Numbers always use tabular-numeric mono rendering for clean, dashboard-like alignment.

---

🤝 Contributing

Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'feat: Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Please ensure all PRs include tests, follow the commitlint conventional format, and pass the existing suite (npm test).

---

📝 License

Distributed under the MIT License. See LICENSE for more information.