From 1b8ac53dd8e6f7e928e158404928703b6be32339 Mon Sep 17 00:00:00 2001
From: Johannes <johannes@bcos.cloud>
Date: Wed, 1 Jul 2026 21:31:29 -0400
Subject: [PATCH] docs(claude): slim CLAUDE.md to thin standard, defer
 architecture to the Guide

Keeps operating essentials (template gate, ports, build/deploy, env, What's New,\nrepo-specific quirks); moves architecture/endpoints/tables/topics to the HiveIQ\nGuide (guide.bcos.dev) which is kept in sync with code. Part of the guide-KB rollout.\n\nCo-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 frontend/CLAUDE.md | 91 ++++++++++++++++++++++++++++++----------------
 1 file changed, 60 insertions(+), 31 deletions(-)

diff --git a/frontend/CLAUDE.md b/frontend/CLAUDE.md
index 35b75da..e8bd98d 100644
--- a/frontend/CLAUDE.md
+++ b/frontend/CLAUDE.md
@@ -7,45 +7,74 @@
 > 4. Copy the filter-sidebar + table CSS **verbatim** — never simplify.
 > 5. Scoped `<style>` only — never `import './x.css'`. *(hook-enforced)*
 
+ARIA — ATM threat intelligence & precursor-sequence detection (IOC catalog, threat events,
+attack sequences, device posture). Svelte frontend + Spring Boot 3.4 backend.
+Package `com.hiveops.aria`, DB `hiveiq_aria`.
+
+| Sub-module | Port | Dev | Prod |
+|---|---|---|---|
+| `backend/` (repo root) | 8095 | `api.bcos.dev/aria/` | `api.bcos.cloud/aria/` |
+| `frontend/` | 5187 | `aria.bcos.dev` | `aria.bcos.cloud` |
+
+## 📖 Architecture, endpoints, tables, Kafka, gotchas, testing → the Guide
+
+The deep, **code-grounded** knowledge for this service lives in the HiveIQ **Guide** — kept in
+sync with code (unlike hand-written docs, which rot). Query it instead of duplicating here:
+
+```bash
+TOKEN=$(curl -s https://api.bcos.dev/auth/api/login -H 'Content-Type: application/json' \
+  -d '{"email":"<you>","password":"<pw>"}' | python3 -c 'import sys,json;print(json.load(sys.stdin)["token"])')
+
+# service overview:
+curl -s https://api.bcos.dev/guide/api/v1/guide/modules/technical.aria     -H "Authorization: Bearer $TOKEN"
+# per-module (Customer / Internal / Architect / Testing / Claude tabs) — read the "Claude" tab to act:
+curl -s https://api.bcos.dev/guide/api/v1/guide/modules/aria.threat-events -H "Authorization: Bearer $TOKEN"
+```
+
+Modules: `aria.dashboard`, `aria.threat-events`, `aria.ioc-management`, `aria.ioc-feeds`,
+`aria.precursor-alerts`, `aria.device-posture`. Browse: **https://guide.bcos.dev** (admin login
+shows the internal tabs). The Guide is the source of truth for endpoints, DB tables, Kafka topics,
+roles, gotchas, and how to test — **this file stays thin on purpose.** When you change ARIA
+behaviour, update the Guide content, not this file.
 
 ## Before writing ANY new component
 
-Read an existing sibling component first. Mandatory. Use `IocManagement.svelte` or `DevicePosture.svelte` as the reference.
+Read an existing sibling component first. Mandatory. Use `IocManagement.svelte` or
+`DevicePosture.svelte` as the reference. Poll the STATUS endpoint only (never trigger a refresh
+from `setInterval`), and always `onDestroy(() => clearInterval(interval))`.
 
-## Canonical patterns (copy exactly, no variations)
+## Dev / build
 
-**Header** — text only, no buttons:
-```svelte
-<div class="header">
-  <div class="header-text">
-    <h1>Page Title</h1>
-    <p>Subtitle</p>
-  </div>
-</div>
+```bash
+# backend (repo root)
+./mvnw clean package -DskipTests
+# frontend
+cd frontend && npm install && npm run dev   # http://localhost:5187
 ```
 
-**Toolbar** — all buttons go here, never in the header:
-```svelte
-<div class="form-card">
-  <div class="toolbar">
-    <div class="toolbar-left"><span class="count">N items</span></div>
-    <div class="toolbar-right">
-      <button class="btn btn-secondary btn-sm">Refresh</button>
-      <button class="btn btn-primary btn-sm">+ Add</button>
-    </div>
-  </div>
+## Build & deploy
+
+```bash
+# backend image (hiveiq-aria) — root build.sh; frontend image (hiveiq-aria-frontend) built from frontend/Dockerfile
+./build.sh --registry registry.bcos.dev  --push      # dev  (:dev tag, bcos.dev / .251)
+./build.sh --registry registry.bcos.cloud --push     # prod (:latest; CI/CD on merge to main, manual only if CI broken)
+
+# deploy dev: ssh .251 → ~/hiveiq/hiveops-openmetal/hiveops/instances/dev
+docker compose pull hiveiq-aria hiveiq-aria-frontend && docker compose up -d hiveiq-aria hiveiq-aria-frontend
+# prod: same on 173.231.195.250 with registry.bcos.cloud
 ```
+CI: `.gitea/workflows/cd-develop.yml` (push → develop, deploys to bcos.dev), `cd-main.yml`.
 
-**Buttons** — always global classes, never custom button CSS:
-- `btn btn-primary` / `btn btn-primary btn-sm`
-- `btn btn-secondary` / `btn btn-secondary btn-sm`
+## Env vars
 
-**Table** — inside `.table-wrapper > .table-container`:
-- `thead` background: `#f9fafb`, sticky
-- `th` color: `#374151`, uppercase, `font-size: 0.78rem`
-- `td` color: `#1f2937`
-- `tbody tr:hover` background: `#eff6ff`
+```
+# backend — hiveiq_aria on hiveiq-postgres
+DB_URL  DB_USERNAME  DB_PASSWORD        # ddl-auto=validate; Flyway owns schema (db/migration)
+JWT_SECRET (shared w/ auth)  KAFKA_BOOTSTRAP_SERVERS  CORS_ALLOWED_ORIGINS
+```
+Frontend: `VITE_API_URL` = `https://api.bcos.dev/aria` (dev) / `https://api.bcos.cloud/aria` (prod).
+Injected at container runtime into `dist/config.js` (`window.__APP_CONFIG__.apiUrl`) via `entrypoint.sh`.
 
-## Auto-poll
-- Poll the STATUS endpoint only — never trigger a refresh from setInterval
-- Use `onDestroy(() => clearInterval(interval))` always
+## What's New
+
+Edit `hiveops-release/releases.json` → `./deploy.sh` in that repo.