OpFix

OpFix is a cloud-based Maintenance Management System: stores raise maintenance jobs, admins triage them, contractors and engineers carry out the work, and an accounts office handles invoicing — all tracked through one auditable workflow.

I built it as my BSc Computer Science final-year project and dissertation: a FastAPI backend over PostgreSQL with SQLAlchemy and Alembic, a React + Vite + Tailwind single-page app, JWT authentication with TOTP two-factor, a pytest suite, and a deployment on Render backed by Supabase Postgres.

Maintenance work in a multi-site business passes through many hands — the store that reports a fault, the admin who approves it, the contractor and engineer who fix it, and the accounts team who get paid. Run that on phone calls and spreadsheets and jobs stall, accountability blurs, and there is no reliable record.

OpFix needed to make the correct path the only path: a single system where every job moves through defined stages, every role sees exactly what it should, and every significant action is logged.

A FastAPI backend organises the domain into models, Pydantic schemas, routers and a services layer, with dependencies for the database session, the current user and role requirements.

Every maintenance job is driven by an explicit status enum — from NEW → ASSIGNED → IN_PROGRESS → ON_HOLD → COMPLETED/CANCELLED, extended with the full contractor-and-accounts flow (approval, sent-to-contractor, engineer-on-site, confirmed-by-store, sent-to-accounts, queried, paid) and post-completion states like reopened, recalled and reassigned.

Access is governed by roles and permissions checked in FastAPI dependencies, and new users go through an approval step before they can act. Sensitive changes write to an `audit_logs` table.

A React SPA consumes the API, holding the JWT in context and rendering role-specific dashboards, job boards, comments and exports.

The backend is a FastAPI application factory with CORS and modular routers. Business logic lives in a services layer (auth, jobs, users, audit), data access goes through SQLAlchemy models, and requests are shaped by Pydantic schemas. Alembic manages migrations.

Authentication issues JWTs; a `require_role` dependency resolves the caller's role and permissions on every protected route, and a `get_current_user` dependency loads the account. TOTP provides two-factor auth, and real-time updates are pushed over WebSockets.

The frontend is a React + Vite + Tailwind SPA that keeps the JWT in an auth context and calls the API through typed axios wrappers. The whole system is deployed on Render with Supabase-managed PostgreSQL.

A user has a role and belongs to an organisational structure (company, store, contractor department, region) and can report to another user. Maintenance jobs carry a priority and a status, and accumulate assignments, comments, attachments and activity. Audit events reference the acting user and the affected job.

Roles and permissions are first-class tables, so access rules are data rather than scattered conditionals — and jobs, users and most entities support soft deletion for a recoverable history.