photofetch/DESIGN.md

# photofetch — Design (QFD)

How photofetch turns "pick a Project, see its team as faces" into engineering
functions and components. Vocabulary is defined in [CONTEXT.md](./CONTEXT.md);
the Slack-matching decision is recorded in [ADR-0001](./docs/adr/0001-slack-directory-cache.md).
This is the tree-only QFD variant (cascade + budget + tradeoffs) — the goal/function
counts don't justify the upkeep of full QFD matrices.

Strength weights used below: **9** strong, **3** medium, **1** weak, blank none.

---

## 1. Goals — the WHATs

| ID | Goal | Weight | Source |
|----|------|:------:|--------|
| G1 | Pick a Project and immediately see who's on it, as faces | 10 | user request |
| G2 | Each Member shows the correct name + Role | 8 | user request |
| G3 | Find a specific Project fast, even among hundreds | 6 | [Q3] |
| G4 | Stay useful when Slack is down or a Member has no Slack | 6 | [Q6] |
| G5 | Keep the roster private to the team | 7 | [Q7] |
| G6 | Select several Projects, see their teams grouped, and export the photos | 8 | user request |

## 2. Functions — the HOWs

| ID | Function | Dir | Target (now) | Target (future) |
|----|----------|:---:|--------------|-----------------|
| F1 | Resolve a Project's Members from Napta (real + active only) | → | correct set | — |
| F2 | Render a Project's grid end-to-end | ↓ | ≤ 2 s p95 (warm cache) | ≤ 1 s |
| F3 | Match Members → Slack Avatars | ↑ | in-memory vs cached directory | — |
| F4 | Authenticate to Napta (Auth0 M2M) | → | cached JWT, refresh on 401/expiry | — |
| F5 | Keep the Slack directory cache fresh | → | 30-day TTL + manual Refresh | — |
| F6 | Filter/search the Project picker (multi-select) | ↓ | instant on ≤ few hundred (client-side) | server-side if thousands |
| F7 | Gate access to the whole site | → | Basic Auth at nginx | SSO |
| F8 | Build the Export zip (folder per Project Group) | ↓ | ≤ ~15 s for a few hundred photos | stream + progress |

## 3. Cascade — Goals → Functions → How → Components

- **G1** Pick a Project, see its team _(W10)_
  - **F1** Resolve Members from Napta
    - **How**: `GET /user_project?filter[project_id]` (drop `simulated`) → resolve `user_id`s → `GET /user` (drop inactive) → resolve `user_position_id` → Role
      - **Component**: `backend/src/napta.ts` (client + token + queries)
  - **F4** Authenticate to Napta
    - **How**: client-credentials → JWT at `auth.napta.io/oauth/token` (aud `backend`), cache until expiry, refresh on 401
      - **Component**: `backend/src/napta.ts` (token cache)
  - **F2** Render the grid
    - **How**: one backend call `GET /api/projects/:id/members` returns ready-to-render Members; SPA shows loading skeleton → grid
      - **Component**: `src/App.vue`, `src/components/MemberGrid.vue`, `MemberCard.vue`
- **G2** Correct name + Role _(W8)_
  - **F1** (Role = Napta Position) — see above
  - **F3** Match Members → Avatars
    - **How**: `users.list` sweep → `email → {imageUrl, slackId}` directory in SQLite; match each Member's email in memory; unmatched → initials Avatar
      - **Component**: `backend/src/slack.ts`, `backend/src/db.ts` (directory table)
- **G3** Find a Project fast _(W6)_
  - **F6** Client-side searchable picker
    - **How**: fetch all non-archived Projects once; typeahead filters by name + client
      - **Component**: `src/components/ProjectPicker.vue`
- **G4** Useful when Slack is down / no match _(W6)_
  - **F7→degrade**: if the directory sweep fails, return Members anyway with `slackMatched:false` + a `slackError` flag; UI shows initials + dismissible warning
      - **Component**: `backend/src/slack.ts`, `MemberGrid.vue`
- **G5** Private to the team _(W7)_
  - **F7** Basic Auth at the edge
    - **How**: nginx `auth_basic` over the whole site incl. `/api`; htpasswd generated at container start from `BASIC_AUTH_USER`/`BASIC_AUTH_PASSWORD`; no-op when unset (local dev)
      - **Component**: `nginx.conf`, web image entrypoint
- **G6** Multi-select + grouped view + photo Export _(W8)_
  - **F6** Multi-select searchable picker; chosen Projects render as Project Groups (a Person on several appears in each)
      - **Component**: `src/components/ProjectPicker.vue`, `src/App.vue`, `ProjectGroup.vue`
  - **F8** Export zip
    - **How**: `POST /api/export {projectIds[]}` → per Project Group fetch Members, fetch each Avatar's bytes (dedup within the export, bounded concurrency), write `<project>/<lastname-firstname>.<ext>`; unmatched Members get a generated **initials SVG**; stream the zip (`fflate`)
      - **Component**: `backend/src/export.ts`, `backend/src/avatar.ts` (initials SVG), `backend/src/index.ts`

## 7. Critical performance budget

| Rank | Function | Target | Watched on | If we miss it |
|------|----------|--------|------------|---------------|
| 1 | F2 grid render | ≤ 2 s p95 (warm) | backend request logs | parallelize Napta calls; cache Positions table; batch `user` fetch by id |
| 2 | F5 directory sweep | ≤ ~10 s for full workspace | sweep duration log | paginate + serve stale snapshot while refreshing in background |
| 3 | F1 Member resolution | correct set, not slow path | spot-check vs Napta UI | add `staffed_days > 0` filter if "assigned but never staffed" noise appears |
| 4 | F8 Export build | ≤ ~15 s, a few hundred photos | export duration log | bounded-concurrency avatar fetch; dedup repeated avatars; cap selection size with a warning |

## 8. Tradeoffs — Got / Paid / ADR

| ID | Tradeoff | Got | Paid | ADR |
|----|----------|-----|------|-----|
| T1 | `users.list` whole-workspace sweep over per-email lookup | few Slack calls, rate-limit-safe, in-memory matching | fetch entire directory; up to 30-day staleness (mitigated by Refresh) | [ADR-0001](./docs/adr/0001-slack-directory-cache.md) |
| T2 | Napta Auth0 M2M cached JWT over a static token | matches Napta's real auth; survives token expiry | token-exchange code + refresh-on-401 | — |
| T3 | HTTP Basic Auth over SSO | strangers kept out with ~zero build | one shared credential; no per-user identity/audit; easily swapped later | — |
| T4 | Email as the only Napta↔Slack join key | one reliable key, no fuzzy matching | Members whose Slack email differs go unmatched (shown with initials) | — |
| T5 | Display-only grid for v1 | ships the core ask fastest | no click-to-Slack / copy-email yet | — |
| T6 | Initials Avatars exported as SVG, not rasterized PNG | zero native deps, clean Alpine image, scalable | mixed extensions in folders; SVG unsuitable where only raster embeds | — |
| T7 | Server-side zip (`fflate`), built in memory | no Slack-CDN CORS, has avatar bytes; simple | whole zip held in memory; large Selections need streaming (F8 future) | — |

### Tensions being watched (unresolved by design)

- **Project count.** Client-side search assumes ≤ a few hundred active Projects. **Trigger to revisit:** the all-Projects fetch gets slow or Napta paginates it past one page → move search server-side (F6 future).

## 9. Inconsistencies spotted and fixed

- **Static token assumption.** Scaffold used `NAPTA_API_TOKEN`; Napta actually uses Auth0 M2M client-credentials. → Config becomes `NAPTA_CLIENT_ID` + `NAPTA_CLIENT_SECRET` with a token-exchange step.
- **Wrong cache shape.** Scaffold `db.ts` modeled a per-email avatar cache (`email → url`, null = no-match), which fits `lookupByEmail`, not the chosen `users.list` sweep. → Reworked to a directory snapshot table + a `refreshed_at` timestamp.
- **Host port publishing.** `docker-compose.yml` published `80`/`8000`, which collided on the Coolify host and failed the first deploy. → Switched to `expose:` (already fixed and deployed).

---

## How to keep this honest

- New ADR lands → reference it from §8 and (if matrices ever added) §6.
- Spike/measurement returns numbers → update §7 `Target` / `Watched on`.
- WHATs (§1) change rarely; HOWs (§2) change per release; revisit §3 cascade when either side moves.
- Delete any section that becomes empty — empty sections lie.