Development

[mtsthibau]

📋 PR Description — development → main

## What

Complete architectural plan, documentation, engineering standards, CI/CD pipeline,
and development infrastructure for the HERMES frontend — preparing the monorepo for
Phase 1 development (Login + Shell foundation).

**20 new documents. 46 planned tasks. 3 independent reviews. 8 blockers resolved.**

---

## Architecture Decisions (9 ADRs)

| ADR | Decision |
|---|---|
| ADR-001 | Dual-mode API client: `@hermes/api/server` (SSR) + `@hermes/api/client` (browser) — explicit imports, no runtime detection |
| ADR-002 | Shared `WebSocketProvider` connecting to `hermes-radio-daemon` on `localhost:8081` with event-based subscriptions |
| ADR-003 | HttpOnly cookie auth (production) + localStorage (development) with single-flight token refresh mutex |
| ADR-004 | IndexedDB offline message queue with UUID idempotency (500 messages per conversation, 90-day eviction) |
| ADR-005 | Offline maps via PMTiles + MapLibre GL JS (zero external tile servers, 200MB local file on microSD) |
| ADR-006 | React Context + custom hooks for state management (no Redux, no Zustand) with `ServerState<T>` pattern |
| ADR-007 | nginx reverse proxy: `/` → shell, `/gps` → GPS, `/chat` → chat. Each app independently deployable. |
| ADR-008 | **sBitx canonical target**: Raspberry Pi 4 ARM64, 7-inch 800×480 touchscreen, Chromium kiosk, fully air-gapped, all services on `localhost` |
| ADR-009 | PWA for companion devices (Service Worker + Web App Manifest). Replaces Capacitor entirely. |

## Development Roadmap (3 Phases, 46 Tasks)

| Phase | Duration | Deliverable |
|---|---|---|
| **Phase 1** | Weeks 1–2 | Login, auth, app scaffolding, design system, CI/CD pipeline (17 tasks) |
| **Phase 2** | Weeks 3–5 | GPS viewer with offline map, real-time tracking, breadcrumbs (12 tasks) |
| **Phase 3** | Weeks 6–9 | Chat with offline queue, file uploads, encryption, radio info (17 tasks) |

## Independent Reviews Completed

| Review | Scope | Critical Findings |
|---|---|---|
| **HF Digital Specialist** | 10 architectural concerns validated against HF radio reality (Mercury 750bps throughput, store-and-forward model, propagation windows) | Rejected: typing indicators, presence indicators, 30MB file limits → 500KB. All addressed. |
| **Senior Project Reviewer** | 18 findings across architecture, security, testing, DevOps | 5 critical (no CD pipeline, no ARM64 cross-compile, no test coverage targets, API transport ambiguity, token refresh race). All addressed. |

## Engineering Infrastructure

- ✅ **`.github/workflows/ci.yml`** — PR CI: lint, typecheck, unit tests, build, E2E, bundle size
- ✅ **`.github/workflows/release.yml`** — ARM64 build → deploy to staging (main merge) → deploy to production (git tag)
- ✅ **`.github/pull_request_template.md`** — 12-item checklist (TypeScript, i18n, a11y, viewport testing, theme testing)
- ✅ **`.commitlintrc.json`** — Conventional Commits (10 types, 13 scopes)
- ✅ **`.prettierrc`** — With Tailwind CSS plugin
- ✅ **`packages/config/eslint/next.mjs`** — Strict rules: no-any, no-console, jsx-a11y, React performance, no-restricted-imports
- ✅ **`.env.example`** — All required variables for sBitx deployment

## 8 Blockers Resolved

1. `turbo.json` merge conflicts resolved
2. `package.json` missing scripts added (`dev:shell`, `dev:gps`, `dev:chat`, `typecheck`, `test`)
3. PoC apps excluded from npm workspaces (only final apps listed)
4. `pnpm-workspace.yaml` removed (npm workspaces only)
5. `commitlint` config created
6. `.prettierrc` created
7. ESLint config created with strict rules
8. Root `.env.example` created

## Files Changed

docs/
├── project-brief.md ← Executive summary
├── development-plan.md ← Full roadmap + workflow
├── adr/ ADR-001 through ADR-009 ← 9 architecture decisions
├── tasks/ phase-1/2/3.md ← 46 tasks with acceptance criteria
├── architecture/ frontend-overview.md ← System context, component tree, data flow
│ auth-flow.md ← Login, token refresh, cross-app auth
│ performance-expectations.md ← Memory/CPU/bundle budgets for sBitx
├── audit/ 2026-08-06-hf-digital-specialist-review.md
│ 2026-08-06-senior-reviewer-assessment.md
└── governance/ engineering-standards.md ← Code patterns, commits, PRs, testing

.github/
├── workflows/ ci.yml + release.yml
└── pull_request_template.md

.claude/agents/ 5 agent definitions

turbo.json ← Merge conflicts resolved
package.json ← Scripts fixed, PoC excluded
.env.example ← Created
.commitlintrc.json ← Created
.prettierrc ← Created

## How to Test

```bash
# Verify the plan is complete
ls docs/adr/ docs/tasks/ docs/architecture/ docs/audit/ docs/governance/

# Verify CI config
cat .github/workflows/ci.yml

# Read the development plan
cat docs/development-plan.md
cat docs/project-brief.md

Post-Merge

Phase 1 development begins. First task: docs/tasks/phase-1-shell-foundation-login.md → Task 1.1.0 — Configure sBitx viewport and design token constraints.

---

This is the PR description ready to paste into the GitHub PR. It covers all 9 commits, 20 new documents, 3 review reports, CI/CD setup, 8 resolved blockers, and the path forward for Phase 1 development.