Update README and add HANDOFF.md for session handoff

Documents the real backend, all 8 completed integration adapters, known
caveats (Proxmox TLS, fast-jwt vuln, SSH key textarea UX, the
IntegrationType/integrationTypes enum duplication footgun), and what's
explicitly on hold (Terminal/Termix), so another AI session can resume
work with full context.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BbJV5nm8KPVH1oNJYKpnoF

2026-06-18 21:12:50 +00:00

3.5 KiB

Raw Blame History

ArchNest

A self-hosted ops dashboard — infrastructure monitoring, a bookmark hub for your homelab/cloud links, an embedded terminal, and system settings, all in one place. Real backend, real integrations, no mock data.

Frontend: React 19 + TypeScript + Vite, styled with Tailwind CSS v4, charts via Recharts, icons via Lucide React. Backend: Fastify + TypeScript + SQLite (better-sqlite3), JWT auth, AES-256-GCM encrypted integration secrets.

For a full handoff/status writeup (what's done, what's not, how to resume), see HANDOFF.md.

Pages

Page	Route	Status
Glance	`/`	Done — real backend data (system status, resource overview, alerts, network traffic)
Infrastructure	`/infrastructure`	Done — resource distribution, node status grid, cost/trend breakdown, all from real integration data. "Network" sub-tab planned as a future addition.
BookNest	`/booknest`	Done — categorized bookmark hub wired to the real bookmarks API
Terminal	`/terminal`	Pending / on hold — will be based on a fork of the (archived) Termix project; user has the fork and intends to hand this off to another AI session to integrate. Do not start this without explicit instruction.
Settings	`/settings`	Done — Profile (real user identity + avatar, editable via API), Appearance, Integrations (8 real adapters), Notifications, Data & Backup, About

See archnest-blueprint.md for the original per-page design spec and design-decisions.md for the visual/UX conventions and lessons learned while building each page — read that file before making layout changes, it documents why things are built the way they are (hero banner layering, card blend techniques, icon library gotchas, etc.).

Development

Frontend:

npm install
npm run dev

Backend:

cd backend
npm install
ARCHNEST_SECRET_KEY=$(openssl rand -hex 32) ARCHNEST_JWT_SECRET=$(openssl rand -hex 32) npm run dev

Both ARCHNEST_SECRET_KEY (encrypts integration secrets at rest) and ARCHNEST_JWT_SECRET (signs auth tokens) are required env vars with no defaults — the server will refuse to start without them. ARCHNEST_DB_PATH optionally overrides the SQLite file location (defaults to a local path under backend/). PORT overrides the listen port (default 4000-range, check server.ts).

Type-check both before committing:

npx tsc --noEmit          # from repo root, frontend
cd backend && npx tsc --noEmit   # backend

Vite/the browser surface some runtime errors (e.g. missing icon exports) that the type-checker won't catch, so also smoke-test pages in a browser.

Tech Stack

Frontend

React 19 + Vite + TypeScript
React Router for routing
Tailwind CSS v4
Recharts (donuts, line/area charts)
Lucide React (icons)

Backend

Fastify 5 + TypeScript, tsx for dev, tsc -b for build
better-sqlite3 for storage
@fastify/jwt for auth tokens, bcryptjs for password hashing
zod for request validation
AES-256-GCM (Node crypto) for encrypting integration secrets at rest
Integration adapters: Proxmox, Docker, NetBird, Cloudflare, AWS, Uptime Kuma, Weather, SSH (see backend/src/integrations/)

Deploy target: Docker on racknerd1 → NPM (Nginx Proxy Manager) proxy at archnest.snsnetlabs.com.

Deployment

This project is deployed via Docker on racknerd1, proxied through Nginx Proxy Manager at archnest.snsnetlabs.com. Not yet deployed as of this writing — still under active development on the claude/wonderful-faraday-qxym5t branch.