# DESIGN.md — J621 Frontend Design System & Architecture Specification

> **Version:** the git commit hash of the build (e.g. `3f35330`)  
> **Theme Foundation:** Catppuccin Mocha + e621 Authentic Taxonomy Architecture  
> **Target Platform:** Desktop-first, fully responsive self-hosted home-server media web application (the library is a watched folder on disk, not a NAS appliance)  
> **Reference Design System:** `DESIGN.md` (this folder)

---

## 1. Visual Language & Foundation

The visual identity of J621 blends a high-density, pro-tier terminal aesthetics (inspired by modern system monitors and desktop DAM software) with the **Catppuccin Mocha** palette and authentic **e621.net** color-coded taxonomy standards.

### 1.1 Color Palette Tokens

```css
:root {
  /* Surface Layers (Catppuccin Mocha) */
  --bg-crust:    #11111b; /* Outer frame, status strips, sticky bottom bars */
  --bg-mantle:   #181825; /* Panels, sidebars, modal surfaces, table headers */
  --bg-base:     #1e1e2e; /* Primary canvas & workspace background */
  --surface-0:   #313244; /* Cards, inputs, table rows, neutral borders */
  --surface-1:   #45475a; /* Hover states, active borders, elevated chips */
  --surface-2:   #585b70; /* Active button states, selected boundaries */

  /* Text & Typography */
  --text-primary:   #cdd6f4; /* High-contrast body, primary titles */
  --text-subtext1:  #bac2de; /* Secondary labels, active badges */
  --text-subtext0:  #a6adc8; /* Metadata captions, counters */
  --text-overlay0:  #6c7086; /* Disabled states, placeholders, icons */
  --text-overlay1:  #7f849c; /* Subtle metadata */

  /* Brand & Core Accents */
  --accent-mauve:     #cba6f7; /* Primary brand accent, active tabs, buttons */
  --accent-mauve-dim: rgba(203, 166, 247, 0.15); /* Tinted selection pill */
  --accent-lavender:  #b4befe; /* Secondary links & focus rings */
  --accent-teal:      #94e2d5; /* System online indicators, verified states */
  --accent-blue:      #89b4fa; /* Primary links, remote indicators */

  /* Status & Severity */
  --status-success:   #a6e3a1; /* Safe rating, verified checksums, healthy */
  --status-warning:   #fab387; /* Questionable rating, pending warnings */
  --status-danger:    #f38ba8; /* Explicit rating, blacklisted items, errors */
  --status-highlight: #f9e2af; /* Followed stars, active favorites */
}
```

---

## 2. e621 Authentic Taxonomy Color Specification

All tag chips, counters, and sidebar taxonomy badges strictly adhere to e621's established namespace semantics mapped to Mocha tokens:

| Namespace | Mocha Token | Hex Code | UI Semantic Usage |
|---|---|---|---|
| **Artist** | Yellow / Gold | `#f9e2af` | Creators, animators, illustrators |
| **Copyright** | Mauve / Purple | `#cba6f7` | Franchises, studios, properties (e.g. *Pokemon*, *Nintendo*) |
| **Character** | Green | `#a6e3a1` | Named characters (*Krystal*, *Fox McCloud*) |
| **Species** | Peach / Orange | `#fab387` | Biological species, body forms (*Jolteon*, *Canine*, *Dragon*) |
| **General** | Sky Blue | `#89b4fa` | Action, posture, apparel, thematic tags (*solo*, *clothed*, *bag*) |
| **Meta** | Subtext / Slate | `#9399b2` | Resolution, digital specs, years (*hi_res*, *2026*, *webm*) |
| **Lore** | Teal | `#94e2d5` | Fictional universe lore and faction metadata |
| **Invalid / Blacklist** | Red | `#f38ba8` | Filtered content, blacklisted rules, dangerous operations |

---

## 3. Rating & Moderation Semantics

- **Safe (S):** Tagged with `#a6e3a1` (Green). 1px border on gallery cards, badge background `rgba(166, 227, 161, 0.15)`.
- **Questionable (Q):** Tagged with `#fab387` (Peach/Amber). 1px border, badge background `rgba(250, 179, 135, 0.15)`.
- **Explicit (E):** Tagged with `#f38ba8` (Red). 1px border, badge background `rgba(243, 139, 168, 0.15)`.
- **Blacklisted Overlay:** Filtered pools/tags replace the preview with a dark container (`#11111b`), a red ban shield icon (`#f38ba8`), and explicit `Bypass & Reveal` or `Manage Filter` options.

---

## 4. Layout & Information Architecture

### 4.1 Global Frame (Shell)
- **Top App Bar (`#11111b`, height: 56px):**
  - Left: Brand mark `J621` badge (`#cba6f7`) only. The watched folder path lives in the footer status strip, not in the header.
  - Center: Nav pills: `Library`, `Online`, `Pools`, `Followed`, `Upload`, `Duplicates`, and `Stats [STAFF]`.
  - Right: System status pill with real backend values, never hardcoded: environment (`DEV`/`PROD`), git commit hash, the actual host OS, page generation time, and the total e621 API request time for that page load — e.g. `ENV: PROD · a1b2c3d · LINUX · 18ms (e621: 4ms)`. Followed by the user avatar.
- **Global Footer Status Strip (`#11111b`, height: 32px):**
  - The strip placement is a proposal; its values are real and drawn from the existing stats data.
  - Left: `🖴 Backend Storage: <bar> 61.3%` — disk usage of the watched folder, colour-coded per the DESIGN.md capacity thresholds, with used/total/free in the tooltip. The folder path is no longer printed in the shell.
  - Center: the backend API origin (empty means same origin). Staff can click it to open `/setup` and point the browser at another backend.
  - Right: `⚡ Active Workers: N running | Queue: M pending` — the count of active optimization/ingest jobs and queued downloads (the original app surfaced this on its stats page; the footer simply keeps it visible).
  - The build version (`<env> @ <git commit hash>`) is shown by the header status pill only — never repeated in the footer.
- **Collapsible Sidebar (Behavior):**
  - **Closed by default** across all gallery and viewer views to prioritize screen real estate.
  - Toggled via `☰` button or quick keyboard shortcut (`Ctrl+B` or `⌘B`).
  - On mobile/tablet viewports (< 1024px), opens as an overlay modal drawer with backdrop blur.

---

## 5. Screen Component Catalog

### 5.1 Library Main Gallery
- **Header Filters:** Search query input with autocomplete (`filename:`, `tag:`, `score:`, `rating:`), items-per-page selector (24, 48, 96), and sorting dropdown (`Date Added`, `Filesize`, `Post ID`).
- **Media Card Grid:** CSS Grid (`grid-template-columns: repeat(auto-fill, minmax(220px, 1fr))`).
- **Card Specs:** 
  - Rating corner indicator ribbon (`S`, `Q`, `E`).
  - Sync verification icon (`✓ Ingested`).
  - Monospace footer: `#<post_id>` · `<filesize>` · `<score> ▲ <faves> ★ <comments> 💬`.

### 5.2 Library & Online Detail View (e621 Aligned)
- **2-Column Layout:**
  - **Left Rail (320px):** Categorized tag hierarchy (`Artist`, `Copyright`, `Species`, `General`, `Meta`) with tag search links `?` and follow `+` toggles. Specs sheet (Post ID, MD5, dimensions, format, source URL).
  - **Right Main Area:**
    - Action Header: `Download` (local files) / `Download to Library` (online posts), `Favorite`, `Add to Pool` — downloading writes into the watched folder; there is no separate "NAS" step. Favorites and pools are e621-side actions.
    - Media Canvas: Centered high-resolution image or loopable WebM/MP4 viewer with pan/zoom.
    - Context Panels: Artist commentary, local storage allocation paths (`/data/media/j621/...`), inode/checksum integrity report, and user comment stream.

### 5.3 Upload & Ingestion Pipeline
- **Dropzone:** Drag-and-drop target with support for PNG, JPG, WEBM, MP4, GIF (up to 512MB).
- **3-Column Board:**
  1. `Pending & Unmatched`: Local uploads awaiting e621 ID link or custom tag specification.
  2. `Visual Similarity Detected`: Perceptual hash clash resolution (side-by-side diff with replacement or duplicate-keep buttons).
  3. `Auto-uploaded & Indexed`: Files verified by MD5 or IQDB and written to the archive.

### 5.4 Duplicates & Similarity Engine
- **MD5 Exact Match Section:** Hash collision certainty (100%), 1-click `Keep File A & Delete File B`.
- **Perceptual Similarity Groups:** Confidence bar (e.g. 96%), side-by-side artwork previews with crop/resolution indicators, and `Commit Deduplication` queue.

### 5.5 Followed Tags & Pools
- **Subscription Cards:** Multi-post collage or tag cover, `Unseen Badge` (`14 Unseen`, `99+ Unseen`), follow/unfollow toggle star, and `Mark Seen` button.

### 5.6 Staff System & Backend Statistics
- **Telemetry Cards:** AMD Ryzen CPU load/temp gauge, ECC RAM allocation bar, ZFS NVMe pool usage, NVIDIA NVENC hardware acceleration status.
- **Worker Pipeline:** 4 active background parsing threads with job IDs and operations (`pHash`, `BLAKE3`, `e621_api`).
- **Live Terminal Log:** Monospace tail container with autoscroll toggle and log level highlighting (`[INFO]`, `[INGEST]`, `[API]`).

---

## 6. Implementation Notes for Frontend Engineers

1. **State Persistence:** Sidebar open/closed state, active rating filter toggles, and items-per-page must persist in `localStorage`.
2. **Smooth Layout Shift Prevention:** Preload image dimension aspect ratios (`aspect-ratio: attr(width) / attr(height)`) to prevent grid jumping during infinite scroll or pagination loads.
3. **Keyboard Accessibility:**
   - `/`: Focus search bar
   - `Ctrl+K` / `⌘K`: Quick command palette & tag finder
   - `[` / `]`: Previous / Next post in detail view
   - `D`: Trigger Download (or "Download to Library" while browsing online posts)
   - `F`: Toggle favorite / follow