dev_arc_aws/.kiro/steering/project-guide.md

# ArchNest — Project Guide for Kiro

> Steering file for AI sessions working on this repo. Covers architecture
> decisions, workflow rules, and patterns to follow. Read alongside
> `design-rules.md` (visual conventions) which is injected separately.

---

## Quick Context

ArchNest is a **self-hosted ops dashboard** — live infrastructure monitoring,
SSH terminal/tunnels/files, Docker container management, remote desktop, and
bookmarks. Deployed at `archnest.snsnetlabs.com` via Docker Compose on
`racknerd1`. Private Forgejo repo (never public).

## Tech Stack (exact versions matter)

| Layer | Tech |
|-------|------|
| Frontend | React 19, Vite 8, TypeScript 6, Tailwind CSS v4, React Router 7 |
| Charts | Recharts 3 |
| Icons | Lucide React (verify exports exist at runtime, not just TS types) |
| Terminal | xterm.js 6 (`@xterm/xterm` + `@xterm/addon-fit`) |
| Backend | Fastify 5, TypeScript 5.7, ESM (`tsx` dev, `tsc -b` build) |
| DB | better-sqlite3 (SQLite) |
| Auth | `@fastify/jwt` + bcryptjs + server-tracked sessions |
| Validation | zod |
| SSH | ssh2 library |
| AWS | `@aws-sdk/client-ec2`, `@aws-sdk/client-sts` |
| Deploy | Docker Compose (Alpine images), GitHub Actions → racknerd1 |

## Git Workflow

- **Remote**: `origin` → private Forgejo instance (SSH via ProxyJump)
- **Never commit on `main`**. Always create `kiro/<feature>` branches.
- **Commit style**: imperative title + body explaining why, with trailers:
  ```
  Co-authored-by: Samuel James <ssamjame@amazon.com>
  Co-authored-by: Kiro <noreply@kiro.dev>
  ```
- **Before committing**: `npm run build` (frontend) + `cd backend && npx tsc --noEmit` (backend)
- **Stage specific files** — never `git add -A` blindly
- **PR flow**: `git push -u origin <branch>` → `gh pr create` → squash-merge

## Code Patterns to Follow

### Frontend
- One page component per route in `src/pages/`
- All backend calls go through `src/lib/api.ts` (typed `apiFetch` wrapper)
- No global state library — plain React state + localStorage for prefs
- Auth via `src/lib/AuthContext.tsx` (JWT in localStorage)
- New pages need: route in `App.tsx`, entry in `api.ts`, sidebar link

### Backend
- One route file per feature in `backend/src/routes/`
- Integration adapters in `backend/src/integrations/` (must implement `testConnection()`)
- SSH-based features use `backend/src/ssh/connect.ts` shared transport
- Request validation with zod schemas
- Audit logging via `logEvent()` from `db/index.ts`
- Secrets encrypted at rest (AES-256-GCM via `db/crypto.ts`)
- Never expose secret values to frontend — only `secretKeys: string[]`

### Adding a New Integration
1. Create adapter in `backend/src/integrations/<name>.ts`
2. Register in `backend/src/integrations/registry.ts`
3. Add type to `IntegrationType` union
4. Add route if needed in `backend/src/routes/`
5. Add `api.ts` functions + TS interfaces on frontend
6. Add card in Settings integrations section

## Policies

- **Versioning**: development happens on **even** major versions; **odd** majors
  are released/stable lines. We are currently developing **v2** (the prior
  released line is v1, see the `v1.0` git tag). Image/version tags should
  reflect this — dev builds carry the even (v2) version.
- **Zero mock data** — every number comes from a live API/SSH/DB call
- **Design-first for big features** — write a `docs/<feature>.md` before coding
- **No footer** on any page
- **Primary target**: 1920px+ viewport, should feel spacious
- **Mesh gate** defaults OFF — never lock the live instance
- **OpenSSL legacy provider** in backend Dockerfile — don't remove (needed for old PEM keys)

## Environment

- Required env vars: `ARCHNEST_SECRET_KEY`, `ARCHNEST_JWT_SECRET`
- Optional: `ARCHNEST_DB_PATH`, `PORT`, `ARCHNEST_GUAC_CRYPT_KEY`,
  `ARCHNEST_CORS_ORIGIN`, `ARCHNEST_AGENT_TOKEN`, `ARCHNEST_AGENT_STALE_MS`
- Frontend dev proxies `/api` → `http://localhost:4000`

## Key Files to Read First

1. `README.md` — architecture overview
2. `HANDOFF.md` — current state + standing rules
3. `design-decisions.md` — visual conventions + per-page implementation notes
4. `ROADMAP.md` — deferred/tiered work
5. `docs/` — subsystem design documents

## SSH Config (for reference)

- `ssh forgejo` → Git operations (User: forgejo, via ProxyJump linode)
- `ssh forgejo-admin` → root shell on Forgejo host (for admin tasks)
- `ssh linode` → jump host at 172.238.163.85