Maintenance Tracker

Maintenance Tracker is a self-hosted Nextcloud app for recurring maintenance, usage meters, service history, costs, vehicle mileage, and supporting documents.

The project is in its early 0.1-series implementation phase. The current vertical slices provide the Nextcloud 34 foundation plus inventory, relationships, meters, work definitions, activity history, due/forecast workflow, and validated local or bundled profile installation into canonical domain records. The architecture deliberately supports a future offline-first mobile client without making the first release depend on it.

Repository authority

The authoritative development repository is:

https://forgejo.argentwolf.org/alan/maintenance_tracker_for_nextcloud

GitHub is maintained as a downstream mirror. The private GitHub security advisory endpoint documented in SECURITY.md remains an explicit vulnerability reporting channel, but GitHub is not the source, CI, or release authority.

Platform targets

• Nextcloud 34
• PHP 8.2 through 8.5, with PHP 8.5 as the primary deployment target
• nginx with PHP-FPM is supported by Nextcloud; the app adds no nginx routes
• PostgreSQL, MariaDB/MySQL, and SQLite through Nextcloud's database APIs
• Node.js 24 for frontend builds
• Future mobile client: Vue offline-first PWA with Capacitor packaging for Android/iOS when native capabilities are needed

The repository directory may have any name. When installed in Nextcloud, the app directory must be named maintenance_tracker so it matches appinfo/info.xml.

Current foundation

• Classic Nextcloud PHP app using only public OCP APIs
• Vue 3 web shell based on the current Nextcloud app template
• Authenticated, versioned OCS API under /ocs/v2.php/apps/maintenance_tracker/api/v1
• Private workspace created lazily for each Nextcloud user
• Asset records with stable UUIDs, revisions, timestamps, and tombstones
• Custom categories, broad asset classes, nested component instances, and structured specifications
• Typed class-compatible asset relationships and effective-dated assignments
• Workspace-wide mutation serialization for invariants that span multiple members
• Capability-based Owner/Manager/Contributor/Viewer workspace authorization
• Shared-workspace membership API with lifecycle-safe grants and role changes
• Append-only audit events for implemented domain and membership mutations
• Asset/component meters with immutable distance, runtime, and usage-count readings
• Work groups and common work definitions with explicit calendar, business-day, and meter schedules
• Maintenance activity ledger with immutable performed-work items and meter snapshots
• Configurable maintenance forecasting plus a materialized one-open-occurrence work queue
• Bounded cursor pagination and account-lifecycle cleanup
• Change journal foundation for future mobile delta synchronization
• Validated profile-v2 installation from bundled or local JSON, with immutable SHA-256 revision provenance, source bindings, preview/conflict checks, and a generic starter profile
• Common work-definition/scheduling foundation with required explicit schedule; schedule: none means unscheduled/ad-hoc work
• Architecture, domain, API, security, licensing, and delivery roadmap

The UI and API are explicitly pre-release. Do not treat the current API as a stable third-party contract yet.

Maintenance due state is derived from schedules, completed activities, and effective meter readings; it is not persisted. Forecast/reminder policy may classify an upcoming item as due_soon, while occurrence rows materialize workflow attention without copying due truth into storage.

Development

Install PHP dependencies:

composer install

Install frontend dependencies and build:

npm ci
npm run build

Run the deterministic local checks:

composer validate --strict
composer test
npm run validate:project
bash tests/validate-project-selftest.sh
npm run validate:profiles
npm run typecheck
npm run lint
npm run stylelint
npm run build
git diff --check
git diff --exit-code -- js css

Run the disposable Nextcloud 34 integration suite when Docker is available:

NC_SMOKE_DATABASE=sqlite bash tests/integration/nextcloud34-smoke.sh
NC_SMOKE_DATABASE=pgsql bash tests/integration/nextcloud34-smoke.sh

The integration harness stages the runtime app and transfers it with docker cp; it does not require the Docker daemon to bind-mount the source checkout. This makes the same harness usable with a local daemon and with the isolated Docker daemon used by the Forgejo workstation runners.

Authoritative Forgejo CI repeats the PHP/frontend checks, exercises the app on Nextcloud 34 with SQLite and PostgreSQL, and publishes an explicitly unsigned install-candidate archive plus checksum. App Store releases need a separate integrity-signing step and must not treat that unsigned candidate as a published release.

Live package-registry advisory queries are intentionally separate from normal CI because registry availability and advisory state are external inputs. Run the Forgejo Dependency advisories workflow before release and investigate real findings without treating a registry outage as a product regression.

For development, clone or mount this repository at:

<nextcloud>/custom_apps/maintenance_tracker

Then enable it:

sudo -u www-data php occ app:enable maintenance_tracker

Production deployments should use Nextcloud's recommended system cron, not AJAX background jobs, before calendar synchronization and reminders are enabled. Environment-specific deployment details belong in infrastructure management, not this public application repository.

Documentation

• Project/agent guidance
• Architecture
• Product architecture
• Domain model
• OCS API
• Profile format
• Security and privacy
• Nextcloud app engineering guidance
• Licensing and distribution
• Roadmap

License

The Nextcloud server app is licensed under AGPL-3.0-or-later. Profile data can carry a separate compatible data license and must declare its provenance.

v0.1.10 fitment foundation (in progress)

The current v0.1.10 checkpoint implements portable fitment compatibility packs through canonical JSON and a bounded normalized CSV/ZIP spreadsheet projection: standardized service-position slots, canonical parts, immutable import provenance, reasoned equipment matching with explicit Owner/Manager mapping, source export, and privacy-minimized community export. This does not complete v0.1.10: profile-v2 part materialization, activity parts-used records, vendor management/store-link editing, and the central cost ledger remain pending.