diff --git a/.planning/phases/18-web-dashboard/18-CONTEXT.md b/.planning/phases/18-web-dashboard/18-CONTEXT.md new file mode 100644 index 0000000..2a412d9 --- /dev/null +++ b/.planning/phases/18-web-dashboard/18-CONTEXT.md @@ -0,0 +1,121 @@ +# Phase 18: Web Dashboard - Context + +**Gathered:** 2026-04-06 +**Status:** Ready for planning +**Mode:** Auto-generated + + +## Phase Boundary + +Embedded web dashboard: htmx + Tailwind CSS + chi router + go:embed. All HTML/CSS/JS embedded in the binary. Pages: overview, keys, providers, recon, dorks, settings. REST API at /api/v1/*. SSE for live scan progress. Auth: optional basic/token auth. + + + + +## Implementation Decisions + +### Stack (per CLAUDE.md) +- chi v5 HTTP router — 100% net/http compatible +- templ v0.3.1001 — type-safe HTML templates (compile to Go) +- htmx v2.x — server-rendered interactivity, vendored via go:embed +- Tailwind CSS v4.x standalone — compiled to single CSS file, go:embed +- SSE for live updates — native browser EventSource API + +### Package Layout +``` +pkg/web/ + server.go — chi router setup, middleware, go:embed assets + handlers.go — page handlers (overview, keys, providers, recon, dorks, settings) + api.go — REST API handlers (/api/v1/*) + sse.go — SSE endpoint for live scan/recon progress + auth.go — optional basic/token auth middleware + static/ + htmx.min.js — vendored htmx + style.css — compiled Tailwind CSS + templates/ + layout.templ — base layout with nav + overview.templ — dashboard overview + keys.templ — keys list + detail modal + providers.templ — provider list + stats + recon.templ — recon launcher + live results + dorks.templ — dork management + settings.templ — config editor +``` + +### Pragmatic Scope (v1) +Given this is the final phase, focus on: +1. Working chi server with go:embed static assets +2. REST API endpoints (JSON) for all operations +3. Simple HTML pages with htmx for interactivity +4. SSE for live scan progress +5. Optional auth middleware + +NOT in scope for v1: +- Full templ compilation pipeline (use html/template for now, templ can be added later) +- Tailwind compilation step (use CDN link or pre-compiled CSS) +- Full-featured SPA experience + +### REST API Endpoints +``` +GET /api/v1/stats — overview statistics +GET /api/v1/keys — list findings +GET /api/v1/keys/:id — get finding detail +DELETE /api/v1/keys/:id — delete finding +GET /api/v1/providers — list providers +GET /api/v1/providers/:name — provider detail +POST /api/v1/scan — trigger scan +GET /api/v1/scan/progress — SSE stream +POST /api/v1/recon — trigger recon +GET /api/v1/recon/progress — SSE stream +GET /api/v1/dorks — list dorks +POST /api/v1/dorks — add custom dork +GET /api/v1/config — current config +PUT /api/v1/config — update config +``` + +### Integration +- Wire into cmd/serve.go — serve starts HTTP server alongside optional Telegram bot +- All handlers call the same packages as CLI commands (pkg/storage, pkg/engine, pkg/recon, pkg/providers, pkg/dorks) + + + + +## Existing Code Insights + +### Reusable Assets +- cmd/serve.go — wire HTTP server +- pkg/storage/ — all DB operations +- pkg/engine/ — scan engine +- pkg/recon/ — recon engine +- pkg/providers/ — provider registry +- pkg/dorks/ — dork registry +- pkg/output/ — formatters (JSON reusable for API) + +### Dependencies +- chi v5 — already in go.mod +- go:embed — stdlib +- htmx — vendor the minified JS file +- Tailwind — use CDN for v1 (standalone CLI can be added later) + + + + +## Specific Ideas + +- Dashboard should be functional but not pretty — basic Tailwind utility classes +- Keys page: table with masked keys, click to reveal, click to copy +- Recon page: select sources from checkboxes, click "Sweep", see live results via SSE +- Overview: simple stat cards (total keys, providers, last scan, scheduled jobs) + + + + +## Deferred Ideas + +- templ compilation pipeline — use html/template for v1 +- Tailwind standalone build — use CDN for v1 +- WebSocket instead of SSE — SSE is simpler and sufficient +- Full auth system (OAuth, sessions) — basic auth is enough for v1 +- Dark mode toggle — out of scope + +