# boysabio/muttmetrics architecture

> Architecture diagram of the GitHub repository boysabio/muttmetrics, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/boysabio/muttmetrics
- Repository: https://github.com/boysabio/muttmetrics

## Overview

MuttMetrics is a grooming-duration intelligence product whose current runtime centers on capturing groomer visits, elapsed time, and optional photos; its structured visit and dog history supports duration ranges. The graph follows the documented React-to-FastAPI capture flow and separates visit/client handling, photo processing and storage, and persistence/reference data. The README documents P50/P90 duration ranges, but the sampled source does not show a scoring or reporting implementation, so that capability is represented as a documented, unverified branch rather than an asserted runtime call.

Main entry points: [`frontend/src/App.tsx`](https://github.com/boysabio/muttmetrics/blob/main/frontend/src/App.tsx) (Capture SPA), [`src/muttmetrics/api/routes/photos.py`](https://github.com/boysabio/muttmetrics/blob/main/src/muttmetrics/api/routes/photos.py) (Photo routes), [`src/muttmetrics/api/routes/dogs.py`](https://github.com/boysabio/muttmetrics/blob/main/src/muttmetrics/api/routes/dogs.py) (Dog routes), [`src/muttmetrics/api/deps.py`](https://github.com/boysabio/muttmetrics/blob/main/src/muttmetrics/api/deps.py) (Auth and DB dependency)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Visit capture"]
  node_spa["Capture SPA<br/>[App.tsx]"]
  node_picker["Photo picker<br/>[PhotoPicker.tsx]"]
end

subgraph group_api["API handling"]
  node_apiapp["FastAPI app<br/>[app.py]"]
  node_dogsroute["Dog routes<br/>[dogs.py]"]
  node_ownersroute["Owner routes<br/>[owners.py]"]
  node_visitsroute["Visit routes<br/>[visits.py]"]
  node_dogservice["Dog services<br/>[dogs.py]"]
  node_ownerservice["Owner services<br/>[owners.py]"]
  node_authdb["Auth and DB dependency<br/>[deps.py]"]
end

subgraph group_photos["Photo handling"]
  node_photosroute["Photo routes<br/>[photos.py]"]
  node_imageproc["Image processing<br/>[images.py]"]
  node_photostore["Photo file storage<br/>[storage.py]"]
end

subgraph group_data["Persistence and domain"]
  node_owner["Owner records<br/>[owner.py]"]
  node_dog["Dog records<br/>[dog.py]"]
  node_visit["Visit records<br/>[visit.py]"]
  node_photo["Photo metadata<br/>[photo.py]"]
  node_session["SQLAlchemy sessions<br/>[session.py]"]
  node_settings["Runtime settings<br/>[config.py]"]
end

subgraph group_reference["Reference data"]
  node_breed["Breed reference<br/>[breed.py]"]
  node_service["Service reference<br/>[service.py]"]
  node_seed["Reference seeding<br/>[data.py]"]
end

node_groomer(("Groomer"))
node_postgres[("PostgreSQL")]
node_duration["P50/P90 ranges"]

node_groomer -->|"captures visits"| node_spa
node_spa -->|"renders"| node_picker
node_spa -->|"searches dogs"| node_dogsroute
node_spa -->|"creates owners"| node_ownersroute
node_spa -->|"creates dogs"| node_dogsroute
node_spa -->|"saves visits"| node_visitsroute
node_spa -->|"uploads photos"| node_photosroute
node_apiapp -->|"registers"| node_dogsroute
node_apiapp -->|"registers"| node_ownersroute
node_apiapp -->|"registers"| node_visitsroute
node_apiapp -->|"registers"| node_photosroute
node_dogsroute -->|"uses dependencies"| node_authdb
node_dogsroute -->|"delegates"| node_dogservice
node_ownersroute -->|"uses dependencies"| node_authdb
node_ownersroute -->|"delegates"| node_ownerservice
node_visitsroute -->|"uses dependencies"| node_authdb
node_visitsroute -->|"reads and writes"| node_visit
node_photosroute -->|"uses dependencies"| node_authdb
node_photosroute -->|"processes uploads"| node_imageproc
node_photosroute -->|"reads and writes bytes"| node_photostore
node_photosroute -->|"reads and writes metadata"| node_photo
node_dogservice -->|"uses records"| node_dog
node_ownerservice -->|"uses records"| node_owner
node_authdb -->|"creates sessions"| node_session
node_session -->|"gets database URL"| node_settings
node_session -.->|"connects"| node_postgres
node_seed -.->|"seeds reference"| node_breed
node_seed -.->|"seeds reference"| node_service
node_visit -.->|"provides duration facts"| node_duration
node_duration -.->|"informs day planning"| node_groomer

click node_spa "https://github.com/boysabio/muttmetrics/blob/main/frontend/src/App.tsx"
click node_picker "https://github.com/boysabio/muttmetrics/blob/main/frontend/src/PhotoPicker.tsx"
click node_apiapp "https://github.com/boysabio/muttmetrics/blob/main/src/muttmetrics/api/app.py"
click node_dogsroute "https://github.com/boysabio/muttmetrics/blob/main/src/muttmetrics/api/routes/dogs.py"
click node_ownersroute "https://github.com/boysabio/muttmetrics/blob/main/src/muttmetrics/api/routes/owners.py"
click node_visitsroute "https://github.com/boysabio/muttmetrics/blob/main/src/muttmetrics/api/routes/visits.py"
click node_dogservice "https://github.com/boysabio/muttmetrics/blob/main/src/muttmetrics/api/services/dogs.py"
click node_ownerservice "https://github.com/boysabio/muttmetrics/blob/main/src/muttmetrics/api/services/owners.py"
click node_authdb "https://github.com/boysabio/muttmetrics/blob/main/src/muttmetrics/api/deps.py"
click node_photosroute "https://github.com/boysabio/muttmetrics/blob/main/src/muttmetrics/api/routes/photos.py"
click node_imageproc "https://github.com/boysabio/muttmetrics/blob/main/src/muttmetrics/images.py"
click node_photostore "https://github.com/boysabio/muttmetrics/blob/main/src/muttmetrics/storage.py"
click node_owner "https://github.com/boysabio/muttmetrics/blob/main/src/muttmetrics/models/owner.py"
click node_dog "https://github.com/boysabio/muttmetrics/blob/main/src/muttmetrics/models/dog.py"
click node_visit "https://github.com/boysabio/muttmetrics/blob/main/src/muttmetrics/models/visit.py"
click node_photo "https://github.com/boysabio/muttmetrics/blob/main/src/muttmetrics/models/photo.py"
click node_breed "https://github.com/boysabio/muttmetrics/blob/main/src/muttmetrics/models/breed.py"
click node_service "https://github.com/boysabio/muttmetrics/blob/main/src/muttmetrics/models/service.py"
click node_seed "https://github.com/boysabio/muttmetrics/blob/main/src/muttmetrics/seed/data.py"
click node_session "https://github.com/boysabio/muttmetrics/blob/main/src/muttmetrics/db/session.py"
click node_settings "https://github.com/boysabio/muttmetrics/blob/main/src/muttmetrics/config.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_spa,node_picker toneBlue
class node_apiapp,node_dogsroute,node_ownersroute,node_visitsroute,node_dogservice,node_ownerservice,node_authdb,node_postgres toneAmber
class node_photosroute,node_imageproc,node_photostore toneMint
class node_owner,node_dog,node_visit,node_photo,node_session,node_settings toneRose
class node_breed,node_service,node_seed,node_groomer,node_duration toneIndigo
```

## Components

### Visit capture

- [Capture SPA](https://github.com/boysabio/muttmetrics/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Photo picker](https://github.com/boysabio/muttmetrics/blob/main/frontend/src/PhotoPicker.tsx): `frontend/src/PhotoPicker.tsx`

### API handling

- [FastAPI app](https://github.com/boysabio/muttmetrics/blob/main/src/muttmetrics/api/app.py): `src/muttmetrics/api/app.py`
- [Dog routes](https://github.com/boysabio/muttmetrics/blob/main/src/muttmetrics/api/routes/dogs.py): `src/muttmetrics/api/routes/dogs.py`
- [Owner routes](https://github.com/boysabio/muttmetrics/blob/main/src/muttmetrics/api/routes/owners.py): `src/muttmetrics/api/routes/owners.py`
- [Visit routes](https://github.com/boysabio/muttmetrics/blob/main/src/muttmetrics/api/routes/visits.py): `src/muttmetrics/api/routes/visits.py`
- [Dog services](https://github.com/boysabio/muttmetrics/blob/main/src/muttmetrics/api/services/dogs.py): `src/muttmetrics/api/services/dogs.py`
- [Owner services](https://github.com/boysabio/muttmetrics/blob/main/src/muttmetrics/api/services/owners.py): `src/muttmetrics/api/services/owners.py`
- [Auth and DB dependency](https://github.com/boysabio/muttmetrics/blob/main/src/muttmetrics/api/deps.py): `src/muttmetrics/api/deps.py`

### Photo handling

- [Photo routes](https://github.com/boysabio/muttmetrics/blob/main/src/muttmetrics/api/routes/photos.py): `src/muttmetrics/api/routes/photos.py`
- [Image processing](https://github.com/boysabio/muttmetrics/blob/main/src/muttmetrics/images.py): `src/muttmetrics/images.py`
- [Photo file storage](https://github.com/boysabio/muttmetrics/blob/main/src/muttmetrics/storage.py): `src/muttmetrics/storage.py`

### Persistence and domain

- [Owner records](https://github.com/boysabio/muttmetrics/blob/main/src/muttmetrics/models/owner.py): `src/muttmetrics/models/owner.py`
- [Dog records](https://github.com/boysabio/muttmetrics/blob/main/src/muttmetrics/models/dog.py): `src/muttmetrics/models/dog.py`
- [Visit records](https://github.com/boysabio/muttmetrics/blob/main/src/muttmetrics/models/visit.py): `src/muttmetrics/models/visit.py`
- [Photo metadata](https://github.com/boysabio/muttmetrics/blob/main/src/muttmetrics/models/photo.py): `src/muttmetrics/models/photo.py`
- [SQLAlchemy sessions](https://github.com/boysabio/muttmetrics/blob/main/src/muttmetrics/db/session.py): `src/muttmetrics/db/session.py`
- [Runtime settings](https://github.com/boysabio/muttmetrics/blob/main/src/muttmetrics/config.py): `src/muttmetrics/config.py`

### Reference data

- [Breed reference](https://github.com/boysabio/muttmetrics/blob/main/src/muttmetrics/models/breed.py): `src/muttmetrics/models/breed.py`
- [Service reference](https://github.com/boysabio/muttmetrics/blob/main/src/muttmetrics/models/service.py): `src/muttmetrics/models/service.py`
- [Reference seeding](https://github.com/boysabio/muttmetrics/blob/main/src/muttmetrics/seed/data.py): `src/muttmetrics/seed/data.py`

### Other components

- **Groomer**
- **PostgreSQL**
- **P50/P90 ranges**

## Connections

- Groomer → Capture SPA: captures visits
- Capture SPA → Photo picker: renders (evidence: `frontend/src/App.tsx`)
- Capture SPA → Dog routes: searches dogs (evidence: `frontend/src/App.tsx`)
- Capture SPA → Owner routes: creates owners (evidence: `frontend/src/App.tsx`)
- Capture SPA → Dog routes: creates dogs (evidence: `frontend/src/App.tsx`)
- Capture SPA → Visit routes: saves visits (evidence: `frontend/src/App.tsx`)
- Capture SPA → Photo routes: uploads photos (evidence: `frontend/src/App.tsx`)
- FastAPI app → Dog routes: registers (evidence: `src/muttmetrics/api/app.py`)
- FastAPI app → Owner routes: registers (evidence: `src/muttmetrics/api/app.py`)
- FastAPI app → Visit routes: registers (evidence: `src/muttmetrics/api/app.py`)
- FastAPI app → Photo routes: registers (evidence: `src/muttmetrics/api/app.py`)
- Dog routes → Auth and DB dependency: uses dependencies (evidence: `src/muttmetrics/api/routes/dogs.py`)
- Dog routes → Dog services: delegates (evidence: `src/muttmetrics/api/routes/dogs.py`)
- Owner routes → Auth and DB dependency: uses dependencies (evidence: `src/muttmetrics/api/routes/owners.py`)
- Owner routes → Owner services: delegates (evidence: `src/muttmetrics/api/routes/owners.py`)
- Visit routes → Auth and DB dependency: uses dependencies (evidence: `src/muttmetrics/api/routes/visits.py`)
- Visit routes → Visit records: reads and writes (evidence: `src/muttmetrics/api/routes/visits.py`)
- Photo routes → Auth and DB dependency: uses dependencies (evidence: `src/muttmetrics/api/routes/photos.py`)
- Photo routes → Image processing: processes uploads (evidence: `src/muttmetrics/api/routes/photos.py`)
- Photo routes → Photo file storage: reads and writes bytes (evidence: `src/muttmetrics/api/routes/photos.py`)
- Photo routes → Photo metadata: reads and writes metadata (evidence: `src/muttmetrics/api/routes/photos.py`)
- Dog services → Dog records: uses records (evidence: `src/muttmetrics/api/services/dogs.py`)
- Owner services → Owner records: uses records (evidence: `src/muttmetrics/api/services/owners.py`)
- Auth and DB dependency → SQLAlchemy sessions: creates sessions (evidence: `src/muttmetrics/api/deps.py`)
- SQLAlchemy sessions → Runtime settings: gets database URL (evidence: `src/muttmetrics/db/session.py`)
- SQLAlchemy sessions → PostgreSQL: connects
- Reference seeding → Breed reference: seeds reference
- Reference seeding → Service reference: seeds reference
- Visit records → P50/P90 ranges: provides duration facts
- P50/P90 ranges → Groomer: informs day planning
