car-tracker/DESIGN.md

Vehicle Tracker Application Design

Goal

A web application to replace manual spreadsheet tracking of vehicle maintenance and fuel usage of a shared fleet.

Architecture & Philosophy

• Language: Ruby on Rails
• Style: Snake_case
• Principle: Keep it simple. Do not over-optimize. CRUD is the priority.
• Database: Relational, tracking "Events" linked to specific "Entities."
• Tests: We should be test driven in our development. No feature should be created without a test.

Data models

1. User

This table will contain information about the users of the app. Mostly used to know who updated what. This table will include:

• Fields: name, email
• Required uniqueness: email is unique case-insensitively.

2. Vehicle

This table will contain information about the vehicles (assets) that we track. They have no strict ownership relationship as they can be used/driven by multiple operators. The vehicle information will include:

• Fields: make, model, year, color, vin, licence_plate, current_odometer, fuel_tank_size, active
• Required uniqueness: vin is unique and normalized to uppercase; licence_plate is unique case-insensitively.

3. MaintenanceSchedule

Configures the maintenance rules for a specific vehicle. This allows the "overdue" check to be automated by comparing the current schedule against the actual history.

• Fields: vehicle_id, maintenance_type, mileage_interval, time_interval
• Note: time_interval is stored as integer days. The UI can display the value as months or days later.
• Relationship: Belongs to Vehicle

4. FuelEntry

Records specific refueling events.

• Fields: vehicle_id, odometer (at time of fill), gallons_pumped, price_paid, date, updated_by_user_id (Tracks who submitted)
• Relationship: Belongs to Vehicle

5. MaintenanceEntry

Records maintenance and repair history.

• Fields: vehicle_id, odometer (at time of service), name (Should match a maintenance_type value from the MaintenanceSchedule), notes, cost, date, updated_by_user_id (Tracks who submitted)
• Relationship: Belongs to Vehicle

Data Relationships

• Vehicle has_many MaintenanceSchedules
• Vehicle has_many FuelEntries
• Vehicle has_many MaintenanceEntries
• User has_many FuelEntries (as the actor)
• User has_many MaintenanceEntries (as the actor)

Data Flow

Scenario A: Fueling

1. User navigates to Vehicle#show.
2. User fills form with Odometer, Gallons, Price.
3. User submits -> FuelEntry is saved to DB.
4. current_odometer is updated on the Vehicle record.

Scenario B: Maintenance

1. User navigates to Vehicle#show.
2. User fills form with Name, Notes, Cost, Date.
3. User submits -> MaintenanceEntry is saved to DB.

Scenario C: Overdue Alerts

1. On Vehicle#show, query the most recent MaintenanceEntry.
2. Compare MaintenanceEntry.date vs Date.today.
3. If difference > 6 months, display alert message to User.

Note that there is in the MaintenanceSchedule data, there is a time_interval field that defines the length of time for maintenance. There is also a milage that should be used as well and it is an or operation for them.

User Authentication

Because this is an internal application, I plan on something like this:

The server will every month generate a key. This key will be printed out in a QR code format. The users will then scan the QR code to collect the key. When they make a request, this key is sent along with it and is used to verify the user. Ideally each user would use the QR code to prove that I know them, enter a name and then get a session token that is used instead of sending the raw QR code. The idea is that it is proof that I know who they are by them posessing information that only I have (the QR code) and then in the future they should use the token to prove who they are.

Again, because this is an internal application, there should not be any passwords. Users are not really created to be logged in, more because I need to track who is doing what with the equipment.

Database choice

I have no hard requirements. I would prefer the database to be easy to use for development. This application will really only ever have up to 100 users so I do not need high performance. SQLite should work fantastic in this case.

Test framework

The test framework is rspec. You can run the tests with bundle exec rspec.

Vehicle ownership

Vehicles can be used by multiple operators. We do not need to track who is driving though. We just want to know about who is submitting updates and enteries.

Rails information

$ rails --version
Rails 8.1.3.1

Deployment

This will be a local development deployment. Once we are ready, it will be packaged into a Docker container and put on a production server. This container is designed to run behind a reverse proxy that is already in place.

Final notes

The relationship between the user and vehicle is minimal. This is on purpose because we really are only using the user to track who is making changes. We do not really care if it is the actual driver or not.

For overdue alerts, we will send notifications to the users using a notification service. This is not yet set up so we will not worry about it. We can leave stubs though for that to happen. The notification service just requires a curl request so it is simple to add later. For now, just log it into the console so that we can test it is working.

Vehicles should not be deleted because maintenance and fuel history must be preserved. If a vehicle should no longer appear in normal workflows, mark it inactive instead.

For data access, it would be nice to have 'admin' and 'regular' users however that is a distinction that we do not yet need. Remember to keep things simple but flexible in the future. Do not wall us in with how code is done.

Each edit by the users will be a seperate database entry. There should be no user editing the same entry at any time. The only possible issue that I can see is if we have two users in the same vehicle and they both submit a fuel entry. In this case, we would just delete one of the entries. At no point in time should two users be editing the same record.

Platform information

Note that we are using Ruby 4.0.6 which is still "experimental" with Rails 8. This means that sometimes odd isues can come from gem version issues. For example, I already had to fix an error with the csrf_meta_tags in the erb templates. The error was nothing to do with the code but with the JSON gem which Rails requires to be less than version 3 and we had 3.0.2 installed. This caused the signatures to be mis-matched and made things wrong.