# coachpapa — brief

**What:** A maintenance ticket app built around one idea — **capture takes five
seconds or it never happens.** A worker walking past a machine snaps a photo,
dictates a sentence, picks the asset, and a permanently-numbered, timestamped
ticket exists. A planner then works that ticket through parts, scheduling, and
close-out. Everything exports to CSV.

**Why:** Mike McPhee (rian's uncle) is a plant maintenance advisor with ~30 years
in the trade. His observation — techs with dirty gloves will not peck at a phone,
so every CMMS that requires typing silently loses its data — is the whole product.
He wants a simple, self-hosted, low-cost alternative to the bloated CMMS market
(his term: "PAPA"). The realistic business shape is a leave-behind tool for his
own consulting practice, not a startup competing with MaintainX.

**Who:** Mike (domain expert, source of requirements, eventual seller). Rian
(owner, builder). End users: plant floor technicians (capture) and maintenance
planners (triage, scheduling, parts). Reference plant: Britco Pork.

**Current goal:** A working prototype Mike can open on his phone, seeded with his
real Britco asset and parts data, that proves the capture loop. Milestones P0-P2
in the plan. Nothing is blocked on him — his existing documents contain enough to
build from.

**Status:** **Working prototype live at <https://coachpapa.demoing.info> (v0.2.0),
behind the id-auth shared-password gate.** P0 and P1 complete and gated; P2
partial (both CSV exports shipped, Pattern B auth not yet wired — identity is
still a name picker). Deliverable lives in `main/`; this directory is the
workspace. Current state and what is next: `.logs/handoff.md`.

## Where everything is

| Role | Lives in |
|---|---|
| Build plan, milestones, gates, data model | [`.logs/planning/coachpapa-prototype-2026.md`](.logs/planning/coachpapa-prototype-2026.md) |
| Operating rules for build sessions | [`agents.md`](agents.md) |
| Session state — what last happened, what's next | [`.logs/handoff.md`](.logs/handoff.md) |
| Session summaries | [`.logs/diary.md`](.logs/diary.md) |
| Friction hit in the v8 substrate (compiles into the server plan later) | [`.logs/v8-feedback.md`](.logs/v8-feedback.md) |
| The app itself | `main/` (code only; runtime state sits at workspace root) |
| Mike's source material | `notes/` — see below |
| Coding standards | `/srv/projects/standards/` (coding.md -> react.md -> frontend.md) |

## Mike's source material — what's worth reading

`notes/` is ~480 MB, mostly video that restates the documents. Only these matter:

| File | Why |
|---|---|
| `notes/Executive Summary/COACHPAPA FLOW CHART.docx` | **The actual spec.** The ticket lifecycle in his own words, plus the two reports he wants. |
| `notes/Maintenance Planning/Britco Equipment List COGZ.xlsx` | 377 real assets — seed data, and the asset field shape |
| `notes/Maintenance Planning/MAINTAINX/5 MX Parts Inventory Import File.xlsx` | The parts field shape (barcode, U/M, unit cost, min qty, lead time) |
| `notes/Maintenance Planning/MAINTAINX/BP Parts Report.xlsx` | 1,015 real transactions — this *is* the "item movement report" he's asking for; the CSV export should match its shape |
| `notes/Maintenance Planning/MAINTAINX/CMMS 101.docx` | His domain thinking on parts labelling and work-order flow. Useful background, not a spec. |
| `notes/Maintenance Planning/COGS WORK ORDER.JPG` | The paper form this replaces |

Everything else — the market research, the competitor tables, the SATO/NiceLabel
label-printing video, the HindSite archive — is context, not requirements.

## Domain

- Dev: <https://coachpapa.demoing.info> (id-auth gated, shared password)
- Live: TBD

## Stack

FastAPI + SQLAlchemy 2/Alembic + Postgres 17 sidecar, serving a Vite React 19 SPA
as a PWA. Per `/srv/projects/standards/react.md`. Mike independently asked for an
iOS PWA in his own exec summary, so this satisfies his requirement and the house
standard at once — no App Store, no developer fee.

## Not doing

Scope discipline is the main project risk — Mike's documents already reach for AI
voice-to-part-number matching, thermal label printing, auto-emailing usage reports
to vendors, ERP/SAP integration, and PLC hooks. The plan's "Out of scope" section
is binding until the prototype is validated. Do not build ahead of it.

## Known gaps

- **No backup substrate.** Server-wide backups are v8 T4.8, not started. This app
  claims permanent auditable ticket numbers; today a mosiah disk failure loses
  them. Prototype mitigation is a nightly `pg_dump` to the workspace — on the same
  disk, so a hedge and not a backup. Resolve before any real plant depends on it.
- **No live customer confirmed.** Some of Mike's Britco material dates to 2023.
  Whether that plant is a live pilot is unresolved and unresolved *deliberately* —
  it does not block building, and the prototype is a better way to ask than email.