# Redirect Intelligence — v2 Update (Chakra UI, Admin + Users, Postgres)

## 0) Goals & Strategy

- **Keep Node/Express** to minimize rewrite risk and preserve existing routes/limits/options (GET/POST `/api/v1/track`, legacy `/api/track`, 100 req/hr IP rate-limit, UA presets, SSL extraction, response-body truncation) [Comprehensive App Doc].
- **Add Postgres** via Prisma for users/orgs/projects/history/reports/jobs.
- **Upgrade UI to Chakra UI** with a modular app shell, light/dark, accessible components.
- **Expand analysis** to include robots/meta/canonical/mixed content and optional JS redirects; add export (MD/PDF), bulk jobs, API keys, monitoring—carried over from the earlier plan.

---

## 1) Tech Stack (final)

- **Backend:** Node.js 20, Express (TS), **Prisma + PostgreSQL**, Zod (validation), **BullMQ + Redis** (bulk & monitoring), **Axios/undici** (HTTP), **Playwright** (optional JS redirects), **Puppeteer** (PDF export), `rate-limiter-flexible` (limits), `jsonwebtoken`/`jose` (auth).
- **Frontend:** React + TypeScript, **Chakra UI**, TanStack Query, React Router, Mermaid (client render) + server render for PDFs.
- **Auth:** Email/password (argon2), organization membership, roles (owner/admin/member), HttpOnly cookie sessions.
- **Billing (Phase later):** Stripe.
- **Packaging:** Docker Compose (api, web, db, redis, worker).

---

## 2) Data Model (PostgreSQL via Prisma)

**Core tables**

- `users(id, email unique, name, password_hash, created_at, last_login_at)`
- `organizations(id, name, plan, created_at)`
- `org_memberships(id, org_id fk, user_id fk, role enum(owner|admin|member))`
- `projects(id, org_id fk, name, settings_json, created_at)`
- `checks(id, project_id fk, input_url, method, headers_json, user_agent, started_at, finished_at, status enum(ok|error|timeout|loop), final_url, total_time_ms, report_id nullable)`
- `hops(id, check_id fk, hop_index, url, scheme, status_code, redirect_type enum(http_301|302|307|308|meta_refresh|js|final|other), latency_ms, content_type, reason, response_headers_json)`
- `ssl_inspections(id, check_id fk, host, valid_from, valid_to, days_to_expiry, issuer, protocol, warnings_json)`
- `seo_flags(id, check_id fk, robots_txt_status, robots_txt_rules_json, meta_robots, canonical_url, sitemap_present, noindex bool, nofollow bool)`
- `security_flags(id, check_id fk, safe_browsing_status, mixed_content enum(none|present|final_to_http), https_to_http bool)`
- `reports(id, check_id fk, markdown_path, pdf_path, created_at)`
- `bulk_jobs(id, project_id fk, upload_path, status enum(queued|running|done|error), progress_json, created_at, completed_at)`
- `api_keys(id, org_id fk, name, token_hash, perms_json, rate_limit_quota, created_at)`
- `audit_logs(id, org_id fk, actor_user_id fk, action, entity, entity_id, meta_json, created_at)`

**Indexes**
- `checks(project_id, started_at desc)`, `hops(check_id, hop_index)`, `api_keys(token_hash)`

---

## 3) API (preserve current + extend)

**Keep existing behavior**
- `POST /api/v1/track`, `GET /api/v1/track` (query param mode), legacy `/api/track`, rate-limit (100/hr/IP), UA options, timing, SSL extraction, response truncation & metadata.

**New (MVP+)**
- `POST /api/v1/checks` (alias of `track` that persists history & returns `check_id`)
- `GET /api/v1/checks/:id` (check + hops + ssl + seo + security + diagram)
- `POST /api/v1/reports/:check_id/export` (`{format: md|pdf}`)
- `GET /api/v1/projects/:id/checks` (paginated history, filters)
- `POST /api/v1/bulk-jobs` (CSV upload), `GET /api/v1/bulk-jobs/:id` (progress, download bundle)
- `POST /api/v1/auth/login`, `POST /api/v1/auth/logout`, `GET /api/v1/auth/me`
- `POST /api/v1/users` (admin), `GET/PUT /api/v1/users/:id`
- `POST/GET/DELETE /api/v1/api-keys` (org-scoped), public namespace: `POST /public/checks`, `GET /public/checks/:id` with `x-api-key`

---

## 4) Analysis Pipeline (Node)

**HTTP chain (non-JS) now**
- Manual redirect following with Axios/undici (turn off auto-follow to record hops), keep per-hop timeouts, normalize URLs, loop set, capture headers. Preserves existing behavior.

**Additions**
- **Meta refresh** parse when 200 HTML with `<meta http-equiv="refresh">`.
- **SEO/Security**: fetch/parse robots.txt; parse `<meta name="robots">`, canonical; detect HTTP→HTTPS / HTTPS→HTTP; scan final HTML for `http://` subresources = mixed content.
- **Optional JS redirects** (phase later): Playwright worker with hard caps; record `window.location` changes as `js` hops.

---

## 5) Exports

- **Markdown** via Nunjucks/Jinja-like templates in Node.
- **PDF** via Puppeteer (server-side render of a report page); embed Mermaid SVG graph; org branding for paid tiers.

---

## 6) Frontend — Chakra UI

**App Shell (Chakra)**
- Header (org/project switcher, theme toggle), left Nav (Dashboard, Checks, Bulk, Projects, API, Monitoring, **Admin**), content area with responsive grid.

**Key Screens**
1) **Home / New Check**
2) **Check Detail**: Chain Table + Mermaid Diagram, flags, export.
3) **History (Project)**
4) **Bulk Jobs**
5) **Monitoring**
6) **API**
7) **Admin Panel**

**Chakra Components**
- `Container`, `Grid`, `Card`, `Table`, `Badge`, `Tabs`, `Accordion`, `Alert`, `Stat`, `FormControl`, `Select`, `Drawer`, `Modal`, `Menu`, `Progress`, `Skeleton`, `Toast`.

---

## 7) Security & Limits

- Preserve **100/hr/IP** default limit on public endpoints; add per-org/user buckets for authenticated usage.
- HttpOnly cookie sessions; CSRF on mutations; password hashing (argon2).
- Redact sensitive headers from persistence/logs.

---

## 8) Phased Build Plan (Cursor-Ready)

### Phase 0 — Repo & Env (Dockerized)
### Phase 1 — Postgres + Prisma + Auth
### Phase 2 — Persisted Checks (Non-JS Chain)
### Phase 3 — SSL/SEO/Security Flags
### Phase 4 — Chakra UI Upgrade Complete
### Phase 5 — Exports (MD & PDF)
### Phase 6 — Bulk CSV + Worker
### Phase 7 — Request Options UI
### Phase 8 — API Keys + Public API + Quotas
### Phase 9 — Optional JS Redirects
### Phase 10 — Monitoring & Alerts
### Phase 11 — Admin Panel
### Phase 12 — Billing (Stripe)
### Phase 13 — Hardening & Perf

---

## 9) UI Map (Chakra)

- **Layout:** AppShell (Sidebar, Header, Main).
- **Home/New Check:** Input, Select, Drawer for headers.
- **Detail:** Tabs, Accordion for hops, Badges for flags, Stats, Buttons.
- **History:** Table with filters.
- **Bulk:** Dropzone, Progress, job list.
- **Admin:** Table for users, Modal invite, Select roles, Form for org & settings.

---

## 10) Back-Compat & Migration

- Keep existing **endpoint semantics** and response shape for `/api/v1/track` and legacy `/api/track`.

---

## 11) Acceptance & KPIs

- Single URL (non-JS) median end-to-end < 1.2s; p95 < 3s.
- Meta refresh detection ≥ 99% test corpus.
- PDF export success ≥ 99%/1k reports.
- Bulk throughput ≥ 50 URLs/s with 5 workers.

---