Vehicula-Nextcloud

Vehicula is a Nextcloud app designed to help individuals and organizations track, manage, and maintain their vehicles with ease.

This application is new. I do have a clear view of what I want, but I'm not competent enough to make it real - it's were you can help. You can find below a list of features that I would like to have in my app, and a checklist to follow the achievement of it. Please be free to provide additional feature/improvment.

In order to not work for nothing, please warn me if you start working on the code. No need to have too much people working separately.

++ I do not have competency in coding, but I used AI to create a .html file, that shows what I have in mind. You will find this file in the root folder.

Vehicula - Development Roadmap

Nextcloud App for Vehicle Maintenance & Fleet Management

---

📌 1. General Information

1.1. App Name

• Primary Name: Vehicula

1.2. Description

A Nextcloud app designed to track vehicle maintenance, usage, and documentation for personal or professional use. Key features include:

• Centralized user manuals (auto/manual upload, preview in Nextcloud).
• Photo management (before/after repairs, damage tracking).
• Calendar integration (maintenance reminders, vehicle reservations).
• Collaboration (share access with internal/external users).
• Statistics dashboard (visual analytics for vehicles and fleets).

---

---

🚗 2. Core Features

2.1. Vehicle Management

2.1.1. Vehicle Profile

• Basic Info:
  • License plate (unique, required)
  • Brand, model, year
  • Vehicle type (car, truck, motorcycle, etc.)
  • Current mileage (manual/OBD API update)
  • VIN (Vehicle Identification Number)
  • Owner (user/department)
  • Status (active, in repair, retired, sold)
  • Location (default parking spot)
  • Acquisition date
  • Purchase value / current value
  • Insurance (policy number, expiry date, provider)
  • Fuel type (gasoline, diesel, electric, hybrid)
  • Average consumption (L/100km or kWh/100km)
  • Color
  • Free notes (e.g., "Reserved for deliveries")
• Associated Documents:
  • User Manuals:
    • Auto-upload: Internal database (user-contributed). Manuals are stored in a centralised server, and it is automatically loaded in user's Nextcloud and in the app. --> Not to be done in the first step, will be implemented later.
    • Manual upload: PDF or other formats.
    • Preview in Nextcloud (no forced download).
    • Tag important pages (e.g., "30,000 km maintenance").
    • Search within manuals (OCR for scanned PDFs).
  • Other documents: Registration, service history, warranties, etc.
• Photos:
  • Multiple photos per vehicle (interior, exterior, damage, etc.).
  • Albums (e.g., "Before Repair", "After Accident", "2026 Inspection").
  • Side-by-side comparison (before/after).
  • Annotations (e.g., arrows to highlight damage).

2.1.2. Vehicle History

• Event Log:
  • Date, event type (maintenance, accident, repair, etc.), description, cost, mileage, responsible person.
  • Attachments (invoices, quotes, photos).
  • Filtering by date, type, cost, etc.
• Cost Tracking:
  • Total maintenance cost, cost per km, annual cost.
  • Charts (cost trends, failure frequency, etc.).

---

2.2. Maintenance Management

2.2.1. Scheduling

• Integrated Calendar:
  • Sync with Nextcloud Calendar (or create a dedicated one).
  • Automatic reminders (e.g., "Oil change in 5,000 km" or "Inspection in 3 months").
  • Maintenance Types:
    • Preventive (oil change, filters, etc.).
    • Corrective (repairs).
    • Mandatory checks (technical inspection, insurance, etc.).
  • Custom frequency (every X km or X months).
  • Priority levels (low, medium, high, urgent).
• Shared Tasks:
  • Assign to a user/group.
  • Status (to-do, in progress, completed, cancelled).
  • Notifications (email, Nextcloud notification, SMS if configured).

2.2.2. Operation Tracking

• Checklists for routine maintenance (e.g., "Oil Change" = [oil, oil filter, air filter]).
• Intervention History:
  • Who performed the maintenance?
  • When?
  • What was the mileage?
  • Cost and replaced parts.
• Alerts for overdue maintenance.

---

2.3. User & Permission Management

• Roles:
  • Admin: Full access (add/remove vehicles, manage users).
  • Fleet Manager: Edit vehicles, schedule maintenance.
  • Standard User: View and add events (e.g., report an issue).
  • External Guest: Read-only or limited access (e.g., mechanic, insurer).
• Sharing:
  • Share vehicles/calendars with Nextcloud users or public links (password-protected if needed).
  • Fine-grained permissions (e.g., "User can only view photos of Vehicle X").

---

2.4. Integrations & API

• Nextcloud Integration:
  • Use Nextcloud APIs for:
    • File management (manuals, photos).
    • Calendar sync.
    • Notifications.
    • Authentication (SSO).
  • Webhooks for external actions (e.g., send email when maintenance is due).
• External APIs:
  • OBD Device Connection: Fetch mileage and error codes in real-time.
  • GPS Tracking: Vehicle location history (for fleets).
  • Import/Export:
    • Export data as CSV/Excel (for accounting).
    • Import from CSV (migration from other software).
• Mobile Compatibility:
  • Responsive design for smartphones/tablets.
  • Optional mobile app (via Capacitor/React Native).

---

2.5. Advanced Features (Optional)

• Cost & Budget Tracking:
  • Annual budget per vehicle/fleet.
  • Alerts for budget overruns.
• Reservation System:
  • Vehicle booking calendar (who uses which vehicle and when).
  • Conflict detection.
• Performance Tracking:
  • Fuel consumption (manual or OBD API).
  • Trip analysis (distance, driving time, average speed).
• Spare Parts Management:
  • Inventory of spare parts.
  • Alerts for low stock.
• Automated Reports:
  • Generate PDF reports (e.g., "Monthly Maintenance Report").
  • Auto-send via email.
• Multi-Fleet Support:
  • Manage multiple fleets (e.g., vehicles in France and Germany).
• Customization:
  • Custom fields (e.g., "Foreign License Plate" for international fleets).
  • Templates for vehicle profiles (e.g., "Company Car" vs "Delivery Truck").

---

---

📊 3. Statistics Dashboard

A dedicated tab to visualize vehicle/fleet data with interactive charts and filters.

3.1. Overview

• Summary Cards:
  • Total vehicles in fleet.
  • Total maintenance cost (this year / all time).
  • Average mileage per vehicle.
  • Upcoming maintenance tasks (next 30 days).

3.2. Vehicle-Specific Statistics

Select a vehicle to see its dedicated stats.

• Mileage Over Time:
  • Line chart: Mileage progression (monthly/yearly).
• Maintenance History:
  • Bar chart: Number of maintenance tasks per month.
  • Pie chart: Maintenance types (preventive vs corrective).
• Cost Analysis:
  • Line chart: Cumulative maintenance cost over time.
  • Bar chart: Cost by category (oil, tires, repairs, etc.).
• Fuel Consumption (if tracked):
  • Line chart: Average consumption (L/100km) over time.
  • Bar chart: Fuel costs per month.
• Downtime:
  • Calendar view: Days vehicle was in repair.
  • Bar chart: Downtime per reason (accident, maintenance, etc.).

3.3. Fleet-Wide Statistics

Aggregate data for all vehicles or filtered groups (e.g., "Delivery Vehicles").

• Fleet Composition:
  • Pie chart: Distribution by vehicle type (cars, trucks, etc.).
  • Bar chart: Vehicles by brand/model.
• Maintenance Trends:
  • Heatmap: Maintenance frequency by vehicle.
  • Bar chart: Most common maintenance types across the fleet.
• Cost Comparison:
  • Bar chart: Total maintenance cost per vehicle (sorted high-to-low).
  • Line chart: Average cost per km for each vehicle.
• Usage Statistics:
  • Bar chart: Most used vehicles (by mileage or reservation count).
  • Calendar heatmap: Vehicle usage intensity (days with reservations).
• Alerts & Overdue Tasks:
  • List of vehicles with overdue maintenance.
  • Bar chart: Number of overdue tasks per vehicle.

3.4. Interactive Features

• Filters:
  • By vehicle, date range, maintenance type, cost range, etc.
• Export:
  • Download charts as PNG/PDF.
  • Export raw data as CSV/Excel.
• Custom Dashboards:
  • Save favorite chart configurations.
  • Share dashboards with other users.

---

---

🛠️ 4. Technical Requirements

4.1. Technology Stack

• Framework: Nextcloud App (PHP + JavaScript/TypeScript).
• Frontend:
  • Vue.js or React (integrated with Nextcloud).
  • UI/UX: Follow Nextcloud’s design system (light/dark theme).
• Backend:
  • PHP (for Nextcloud integration).
  • Database: SQLite or MySQL (Nextcloud-compatible).
• Storage:
  • Files (manuals, photos) stored in Nextcloud storage.
  • Metadata in the app’s database.

4.2. Architecture

• Modular:
  • Clear separation between:
    • Business logic (vehicle/maintenance management).
    • Data layer (database/file access).
    • API (for external integrations).
• Extensible:
  • Plugin system (e.g., GPS tracking module).

4.3. Security

• Authentication: Use Nextcloud’s auth system.
• Permissions: Respect Nextcloud’s ACL (Access Control Lists).
• Encryption:
  • Sensitive data (VIN, insurance numbers) encrypted in the database.
  • Files stored with Nextcloud’s encryption (if enabled).
• Audit Logs: Track all actions (who changed what and when).

---

---

📦 5. Development Requirements

5.1. Code Standards

• Languages:
  • PHP (backend, Nextcloud 20+ compatible). (if possible)
  • JavaScript/TypeScript (frontend).
• Coding Standards:
  • PSR-12 (PHP).
  • ESLint/Prettier (JS/TS).
• Comments:
  • PHPDoc for PHP functions/classes.
  • JSDoc for JavaScript/TypeScript.
  • Inline comments for complex logic.
• Naming Conventions:
  • Variables/functions: camelCase (JS) or snake_case (PHP).
  • Classes: PascalCase.
  • Constants: UPPER_SNAKE_CASE.

5.2. Testing

• Unit Tests: PHPUnit (PHP), Jest (JS).
• Integration Tests: Verify interactions with Nextcloud.
• End-to-End Tests: Cypress or Selenium.

5.3. Documentation

• README.md:
  • Installation, configuration, dependencies.
  • Usage examples.
  • Screenshots (if possible).
• Technical Docs:
  • Architecture (UML diagrams if useful).
  • API: Endpoints, request/response examples.
  • Database: Schema and relationships.
• User Guide:
  • Manual in Markdown or PDF (embedded in the app).
  • Video tutorials (optional).

5.4. Internationalization (i18n)

• Translations:
  • Language files for English, French, German, Spanish (minimum).
  • Use Nextcloud’s translation system ($l10n).
• Localization:
  • Date/number formatting based on user locale.

5.5. Performance

• Optimizations:
  • Optimized SQL queries (indexes on frequently queried fields).
  • Pagination for lists (e.g., vehicle list).
  • Caching for static data (e.g., vehicle brands list).
• Limits:
  • Configurable max upload size (default: 50 MB).

---

---

🚀 6. Installation & Deployment

6.1. Prerequisites

• Nextcloud 25 or higher.
• PHP 8.0 or higher.
• Database: MySQL 8.0+ or SQLite.
• Required PHP Extensions:
  • pdo_mysql (or pdo_sqlite).
  • gd (for image processing).
  • intl (for internationalization).
  • mbstring.

6.2. Installation

• Via Nextcloud App Store (ideal):
  • Package as a Nextcloud App (.tar.bz2 file).
• Manual Installation:
  • Copy app folder to nextcloud/apps/.
  • Enable via Nextcloud admin interface.

6.3. Configuration

• **config.php File**:
  • Configurable settings (e.g., max upload size, manual storage path).
• Admin Interface:
  • Configuration page in Nextcloud settings.

---

---

✅ Roadmap Checklist

Phase 1: Core Features

• Vehicle Profiles:
  • Basic info (license plate, brand, model, etc.).
  • Document management (manuals, registration).
  • Photo upload & albums.
• Maintenance Management:
  • Maintenance scheduling (calendar integration).
  • Reminders & notifications.
  • Maintenance history & checklists.
• User & Permissions:
  • Role-based access (admin, fleet manager, user, guest).
  • Sharing (vehicles, calendars).

Phase 2: Advanced Features

• Statistics Dashboard:
  • Overview cards (total vehicles, costs, etc.).
  • Vehicle-specific charts (mileage, maintenance, costs).
  • Fleet-wide charts (composition, trends, comparisons).
  • Interactive filters & exports.
• Integrations:
  • Nextcloud Calendar sync.
  • OBD API for real-time mileage.
  • GPS tracking (optional).
• Reports:
  • Automated PDF reports.
  • CSV/Excel export.

Phase 3: Polish & Deployment

• Testing:
  • Unit tests (PHPUnit, Jest).
  • Integration tests.
  • Manual testing.
• Documentation:
  • README.md.
  • Technical docs (API, database).
  • User guide.
• Deployment:
  • Package for Nextcloud App Store.
  • Submit to Nextcloud Apps.

---

---

📝 Notes

• Priority: Focus on Phase 1 first, then add Statistics and Advanced Features.
• Feedback: Adjust features based on user testing.
• Community: Consider open-sourcing the app for contributions.