# ASF — Guida Primi Passi (Solo Frontend 🎨)

> **ASF = Azurian Software Factory** · *SaaS Platform multi-tenant AI-native*
>
> **Motto**: *"From Requirement to Production — everything is contextualized, traceable and AI-accessible."*
>
> **Principio centrale**: ***Everything is an Artifact*** — requisiti, task, PR, commit, build, test, deploy, incidenti, analisi AI, segnalazioni di sicurezza: tutto è un Artifact ASF collegato da Relazioni semantiche.

Questa guida usa **solo il browser** (frontend Next.js su `http://localhost:3000`) — zero curl, zero chiamate API a mano.
L'obiettivo è insegnarti a **usare ASF dal punto di vista dell'utente finale**: navigare le pagine, filtrare i dati, ispezionare gli artifact nel loro contesto, marcare i code smell come risolti, sottomettere job asincroni da UI, interrogare l'AI sul grafo.

---

## 0. Prerequisito (1 comando solo per popolare dati)

ASF MVP non ha ancora (in questa release) le pagine "Create Organization / Create Project / Create Artifact / Create Relationship via form frontend.
Per avere dati reali con cui giocare nel browser, lancia **UNA SOLA VOLTA** questo comando dal terminale (seed demo):
```bash
cd /root/ASF && make seed-clean
```

Questo comando (wrapper `scripts/seed-demo.sh --clean --jobs`) fa per te:
1. Crea Organization demo + Project demo
2. Popola 21 artifact (Requirements / Task / PR / Build / Deploy / Test / Docs / Commits / Security findings / Incidents / Source files / Code smells)
3. Crea 9 relazioni semantiche
4. In coda 5 job echo (devops / testing / code analysis) per provare la pagina Jobs
5. Mostra un report finale: `Artifacts totali / Jobs counts / Graph nodes·edges`

Poi avvia il frontend (se non già attivo):
```bash
make start
```

Controlla che tutto sia vivo:
```bash
make status
```

Quando vedi `asf-core :8000 UP · asf-web :3000 UP · asf-worker ALIVE` puoi iniziare.

**Apri il browser**: `http://localhost:3000`

---

## 🧭 Concetti Chiave da Sapere (prima di cliccare)

```
Organization (il tuo Team) → Project → Artifact ← Relationship → Artifact
```

- **Artifact (17 tipi)**: requirement, epic, story, task, architecture_decision, document, source_file, commit, pull_request, build, test, security_finding, deployment, release, runtime_event, incident, ai_analysis.
- **Relationship (12 predicati semantici)**: implements / verifies / generated_from / documented_by / deployed_as / caused_by / related_to …
- **Tutto è cliccabile**: un nodo nel grafo → apre il dettaglio Context. Una riga in tabella → apre il dettaglio. Un badge ID → apre il dettaglio.
- **Isolamento per Tenant**: il frontend MVP usa dev-trust headers (t-demo-003 / u-mario) già iniettati per te, quindi tutte le pagine mostrano solo i dati del tuo progetto demo.

---

## 🏠 Pagina 1: Overview Dashboard (`/`)

### Cosa vedi
9 cards in alto (da Bootstrap Prompt §9) + numeri veri:

| Card | Come interpretarla |
|---|---|
| Project Health % | Media pesata: req coverage + deploy success + security backlog. Oggi: **94.5%** ✅ |
| Requirements count · per status | Quanti requisiti ci sono? Aperti / In progress / Chiusi |
| Implementation Coverage | Requisiti con ≥1 task collegati |
| Test Coverage | % PR / Deploy con ≥1 test che li "verifica" |
| Traceability Completeness | Quanti artifact hanno catene complete Req→Task→PR→Test→Deploy |
| Deployments last 7d | Quanti deploy · rate di successo |
| Active AI Jobs | Coda attiva: queued / running · usage ultima ora |
| Failed Builds last 7d | Build fallite |
| Security Findings OPEN | Conteggio per severità: CRITICAL/red · HIGH/amber · MEDIUM/brand · LOW/neutral |

### Cosa fare
- **Click sul numero Projects**: ti salta alla pagina **Requirements** (prossima).
- **Click su Security Findings**: ti salta a **Code Analysis** per vedere gli smell aperti.
- **Click su Jobs**: vai a **Jobs (Activity)**.

---

## 📋 Pagina 2: Requirements (`/requirements`)

### Header in alto
Titolo + 4 strumenti di filtraggio + 1 pulsante:
1. **Search field** (ricerca libera per external_id, title, content)
2. **Project filter** (tutti o 1 progetto specifico)
3. **Status filter** (open / in_progress / done / fixed / resolved)
4. **Type filter** (requirement / epic / story / task / document)
5. **🆕 New Requirement** — ⚠️ *placeholder UI*: in questa MVP non si può creare requirement da form. Usare il make seed per aggiungere nuovi record.

### Tabella Sticky Header
| Colonna | Cosa mostra |
|---|---|
| ID | external_id monospace (REQ-103) | badge + badge tipo (REQ / colorato |
| Title | titolo lungo artifact |
| Status | Badge tone (amber=open · brand=in_progress · green=fixed · blue=active) |
| Project | nome progetto NON-UUID (es. "ASF SaaS MVP" invece di UUID) |
| Source | product-board / jira / github / pytest / argo / etc. |
| Updated | data relativa "2h fa / 3d fa |

### Cosa fare (esercizio 2 clic)
1. Scrivi nella Search: `SSO` → filtra subito i requirements che matchano title/content.
2. Status filter = `Open`.
3. **Click sulla riga REQ-103**. → **ti porta automaticamente a Context Explorer con REQ-103 selezionato**.
   Questo è il pattern ASF: **ogni riga è un link diretto al contesto.

---

## 🔍 Pagina 3: Context Explorer (`/context`) — IL CUORE DI ASF

Questa è la pagina più potente. **5 tab** per 5 modi diversi di vedere lo STESSO artifact selezionato.

### Layout
```
┌─────────────────────────────────────────────────────────────────────┐
│ Artifact Picker (SX)          │  Contenuto Destra (Tabs 1 di 5)      │
│ Search x project                  │                                   │
│ ┌────────────────────────────┐│                                   │
│ │ - REQ-103  ← selezionato ││  [Metadata] [Relationships]       │
│ │ - TASK-101                 ││  [Related 2-hop] [Graph ⭐]        │
│ │ - PR#88                    ││  [History timeline]                │
│ │ - BUILD-910 / DEP-44 ...  ││                                   │
│ └────────────────────────────┘│                                   │
└─────────────────────────────────────────────────────────────────────┘
```

### Tab 1 — Metadata (Informazioni statiche
- **Title · external_id · type · status · version · source · created_at · updated_at
- Griglia 2x2: Version / Source / Created / Updated
- Source preview `<pre>` bg-slate-900 mono (se è un source_file o un content lungo)
- Side card destra: **Remediation** (per i code smell) + **Traceability** (collegamenti rapidi)

### Tab 2 — Relationships (Liste dirette)
- **Outgoing** (edge uscenti: cosa è questo artifact → altri)
- **Incoming** (edge entranti: altri artifact → questo)
- Ogni riga mostra badge `relationship_type` + target title + external_id clickable

### Tab 3 — Related (2-hop)
Tutti i vicini a **2 salti** (artifact direttamente collegati + i loro collegati). Utile per:
"Se modifico REQ-103, cosa viene influenzato indirettamente?"
- 2 gruppi Hop1 e Hop2 con badge di profondità, colore distinto

### Tab 4 — GRAPH (3 anelli concentrici) ⭐ IL PIÙ BELLO
Vedi il tuo artifact **al centro**, poi hop1 → hop2.
- **Layout radiale**:
  - 🟦 Centro → artifact selezionato · bordo indigo + badge SELECTED
  - 🟣 Anello interno (R1 = 220px di raggio · bordo violetto · pillola **HOP1**
  - ⬜ Anello esterno (R2 = R1+220+ ~ raggio · bordo slate · pillola **HOP2**)
- **Edges a 2 livelli visivi:
  - Tier 1 (Sel↔Hop1): **SOLIDO 2.1px** colore REL_COLORS
  - Tier 2 (Hop1↔Hop2): **TRATTEGGIATO strokeDasharray + opacity 0.78
- **11 colori per tipo relazione** (legenda in alto a destra: implements/verifies/generated_from/deployed_as/documented_by/related_to/caused_by …)
- Controlli: drag per spostare, scroll zoom, pulsanti Controls in basso a SX, **MiniMap** colori per layer (indigo / violet / slate)

**Clicca QUALSIASI nodo** nel grafo**:
→ Context si sposta il centro e ricentra sul nuovo artifact!**

### Tab 5 — History Timeline
Eventi ordinati per data:
- 🟣 created_at CREATED viola
- 🔵 updated_at UPDATED blu
- 🟢 version_bump VERSION verde
- 🟠 rel_added / relationship creazione edge arancione

---

## 🧠 Esercizio Pratico Context (3 click!)
1. Nel Picker SX clicca **SEC-025 (security finding SQL injection severity=high
2. Vai in Tab **Related → vedi il nodo SEC-025 e "related_to PR#88
3. Vai in Tab **Graph** → vedi SEC al centro · RELATED_TO PR (edge slate · Hop1
4. Click PR → **Clicca il nodo PR#88 nel graph** → Ora PR#88 è il nuovo centro
5. Tab RELATED del PR → vedi tutti i 2-hop: TASK · BUILD · TEST · DEP · COMMIT · DOC...

Questo è il "perché del progetto: capire l'impatto a cascata.

---

## 💻 Pagina 4: Code Analysis (`/code`)

Analisi di codice + code smells. **2 useQuery separate TanStack (source_file e ai_analysis.kind=code_smell).

### 6 Filtri (Client Side)
1. **Search** libera (title · external_id · remediation · source_path)
2. **Scope**: `All / Source / Smells`
3. **Language**: `All / python / ts / java`
4. **Severity** (solo smells): `Critical / High / Medium / Low`
5. **Status**: `All / open / in_progress / fixed / resolved
6. **Project**: `All / ASF SaaS MVP`

### 5 StatCards in alto
1. Source files caricati
2. Smells trovati
3. Criticali (Badge rosso AlertOctagon)
4. Alti (Badge amber AlertTriangle)
5. Medi+Bassi

### Tabella Righe
Riga = 1 artifact (può essere source_file O smell.

### DetailView (click sulla riga)
Apre pannello info 2 colonne:
```
┌──────────────────────────────────────┬──────────────────────────────┐
│ <Source preview pre>                 │ Info 2x2                     │
│ linguaggio color syntax                  │ version / source / created /     │
│ linee evidenziate in ROSE se linesToHighlight │ Remediation suggerita  │
│ (righe colpevoli di codice)              │ Traceability              │
│                                    │ Status badge severity:                  │
│                                    │  │
│                                    │ ⭐ BUTTON "Mark as fixed"     │
└──────────────────────────────────────┴──────────────────────────────┘
```

### ⭐ AZIONE PRINCIPALE: **Mark as Fixed (PATCH status=fixed)
Prima devi selezionare un **smell** (source files non hanno il tasto).

**Procedura (5 step click!):
1. Filtra Severity = **High**
2. Click la riga **CS-003 pytype ASF-SEC-203 (source consumer.py lines 8-16
3. Dettaglio sulla DX → in alto header un bottone verde **Mark as fixed
4. Click → Attendi ~300ms
5. Sparisce il pulsante → appare un Badge **🟢 Resolved**

**Cosa succede dietro le quinte? useMutation `markFixedM`:
1. `PATCH /artifacts/:id { status: "fixed" }`
2. `onSuccess`: **invalidateQueries(["code-source", "code-smells"]
3. TanStack ricarica le 2 query (tabella si aggiorna automaticamente

Verifica visiva: torna nel filtro Status = fixed → il tuo smell è in fixed!

---

## 🧬 Pagina 5: Traceability Graph (/)
**Grafo GLOBALE del progetto intero** (Context Graph solo di 1 artifact.

### Cosa vedilaid out
- Layout layered DAG React Flow
- **21 nodes · 9 edges demo seed)
- Nodi colorati per tipo artifact type (color map 11 colori)
- refetchInterval 5s auto-aggiorna)
- Pannello Inspector a DX:
  - **selezionato: seleziona
  - **Title · ID · Project
  - **Relationships dirette

### Esercizio Trace (2 click!)
1. Click il nodo arancione **INC-77 (incidente login failure)
2. Guarda Inspector **caused_by DEP-44
3. Click DEP-44 → Inspector deployed_as → BUILD → generated_from PR → implements → task → REQ-103 → Questo è il ciclo completo.

---

## 🚀 Pagina 6: Jobs (Activity) (/)
TUTTI i job. Auto-refresh ogni **3s** (non devi ricarica la pagina manualmente).

### 6 StatCards in alto
Queued / Running / Completed / Failed / Cancelled / Total

### Tabella
| Colonna | Cosa |
|---|---|
| Job ID | ID corto UUID+ clickable |
| Title | titolo descrittivo |
| Queue | code DIRECT pill devops/testing/code_analysis/... |
| Status | Badge tone |
| Worker | asf-worker-1 o quale macchina |
| Priority | 0-100 |
| Usage ms | tempo CPU time 42ms |
| Cost | USD estimate (demo |
| Updated | relativo "4s fa · 1m fa |
| Actions | |

### ⭐ Creare un Job da UI (Form completo) (useMutation submitM + Modal
1. In alto a DX click **Enqueue job** → Apre **MODALE DIALOG 720w
2. Compila il form (7 campi):
   a. **Queue* (select): ai.interactive / ai.background / indexing / code_analysis / testing / devops / notifications
   b. **Job Type** (stesso nome queue)
   c. **Title** (campo libero)
   d. Priority** (0-100)
   e. Correlation ID (opzionale)
   f. Payload** (editor JSON validato - se JSON invalido → disable button, 422 fallback
   g. Notes (opzionale)
3. Click **Enqueue** (in basso a DX pulsante primario Submit 2 pulsanti Cancel · Submit!)
→ Dopo 2 modal si chiude · useMutation:
   - `onSuccess: 1. POST /jobs/submit
   - 2. invalidateQueries(["jobs"])
   - 3. setFilters resetta filtri → Tabella si aggiorna **new job diventa Queued Poi in ~3 secondi lo vede il worker → Running → **Completed** (echo handler demo)

### Detail Modal (Click sulla riga Job)
- **JSON completo del job`:
```
{ id, title, status, queue, payload, priority, created_at, started_at, completed_at, result, usage, error, worker_id, correlation_id, metadata }
```
- Progress 0-100:
  - queued/cancelled: 0%
  - running = progressivo
  - completed = 100%, failed 100% rosso
- Meta pills Queue / Status
- Actions: View similar (precompila la modale Enqueue)

---

## 🤖 Pagina 7: Ask ASF (AI Chat) (`/ask-asf`)

Chat UI stile ChatGPT.

### Layout
```
┌──────────────────────────────┬─────────────────────────────────────┐
│ Sidebar DX:               │ Bolle chat SX                       │
│ · 🔍 Context Scope          │ 👤 Utente                       │
│ · (source_context=true            │ 🤖 AI Risposta                  │
│ · include_relationships=true  │ [box digitando…                 │
│ · max_depth 2                │                                    │
│ · max_nodes 50               │                                    │
│ · send_trace                   │ Prompt input + enter send + shift enter newline │
│ · clear chat              │                                    │
└──────────────────────────────┴─────────────────────────────────────┘
```

### Flusso completo (passo per passo utente)
1. Scrivi nel prompt:
   > *"Cosa causa l'incidente INC-77? Traccia la catena fino al requirement originario, e suggerisci 2 azioni di rimozione"*
2. **Invia con Enter (Shift+Enter = newline nel testo
3. 👤 La tua bolla appare subito (azzurra)
4. 202 accepted → gear rotante "In attesa di risposta dall'AI..." (polling every 2s · max 120 itera 2 minuti
5. Appena il job status=COMPLETED 🟢
6. 🤖 AI Answer: pickAnswer legge `job.result.message/answer/summary/response/text`
7. **JobMeta pills**: queue=ai.interactive status=completed timestamp
8. **Copy**: icona Copy → clipboard
9. **Clear**: icona Clear
10. Prompt ancora una domanda diversa

### MVP attuale
Senza provider LLM attivo → **fallback del AI Gatewa.
**Tutto il resto è FUNZIONANTE
- 202 accettato 2
- 02:
- : 00 iterato
- Risposta renderizzata in bolla
- Context sidebar & Scope pills + History multiple domande

---

## 🧾 Cheat Sheet: Pagine & Azioni Frontend (Riepilogo)

| Pagina Route | Come ci arrivi dalla Sidebar | Cosa ci fai |
|---|---|---|
| `/` | 🏠 Overview | 9 cards KPIs · dashboard generale |
| `/settings` | ⚙️ Settings | **Crea Org (slug regex 3-60)** · **Crea Proj (key A-Z 2-20)** · tabelle lista |
| `/requirements` | 📋 Requirements | Cerca · filtra · **pulsante "New Requirement" modale form completo** · click riga → Context |
| `/context` | 🔍 Context | **pulsante "New Artifact" (17 tipi!)** · **pulsante "Link" (12 rel. types!)** · Ispeziona 5 Tabs · Graph 3 anelli · click nodi ricentra |
| `/code` | 💻 Code Analysis | Filtra smells · **Click riga smell → "Mark as fixed" |
| `/traceability` | 🧬 Trace | Grafo globale · Click nodo → Inspector |
| `/jobs` | 🚀 Jobs (Activity) | **Modale "Enqueue job" form completo** · Detail JSON modal |
| `/ask-asf` | 🤖 Ask ASF (AI) | Fai domande sul grafo · 202 + poll · Chat |

---

## ✅ Stato Copertura Frontend vs API

Tutte le operazioni CRUD principali **ora hanno UI** (0 comandi curl necessari):

| Operazione | UI nel frontend? | Dove la trovi |
|---|---|---|
| Creare Organization | ✅ | **/settings → "New organization" |
| Creare Project | ✅ | **/settings → "New project" |
| Creare Requirement | ✅ | **/requirements → pulsante "New Requirement" |
| Creare Artifact GENERICO (17 tipi: task, epic, story, commit, source_file, ai_analysis, deployment, incident, security_finding, …) | ✅ | **/context → pulsante **"New Artifact" |
| Creare Relazioni tra artifact (12 tipi: implements, verifies, generated_from, documented_by, depends_on, deployed_as, caused_by, related_to, …) | ✅ | **/context → pulsante **"Link"** |
| Upload source code smell | ✅ | Context → New Artifact → `type=ai_analysis` + metadata `{"kind":"code_smell","severity":"high"}` |
| Mark smell come fisso | ✅ | /code → DetailView → **Mark as fixed** |
| Sottomettere Job | ✅ | /jobs → Modale **Enqueue job** completo |
| Interrogare AI grafo | ✅ | /ask-asf → Chat UI 202 + poll |

---

## ✅ Checklist Primo Progetto Frontend (solo click, ZERO curl)

- [ ] Stack attivo: `make seed-clean` + `make start` + `make status` → **UP (tutti verdi)
- [ ] /settings → **New organization**: fill name=NuovaOrg, slug=nuova-org-001 (3-60 lowercase+dash), plan=Free → **Submit → riga apparsa in tabella Organizations ✅
- [ ] /settings → **New project**: fill name="Demo Proj 1", key="DEMO1" (A-Z 2-20), branch=main → Submit → riga apparsa Projects tabella ✅
- [ ] /requirements → **pulsante "New Requirement" → fill Title="SSO Login OK", Project=DEMO1, Content="Login with Okta/OAuth2", Status=backlog → Create → apparsa in lista ✅
- [ ] /requirements → Cerca "SSO" + click riga → Context
- [ ] /context → **New Artifact**: Type=task · Title="Implementa Okta middleware" · External_id="TASK-900" · Project=DEMO1 · Status=todo → Create → selezionata in picker ✅ (17 tipi artifact!)
- [ ] /context → **Link** pulsante: Source=REQ (il SSO appena creato) · Type=implements · Target=Task900 (search "Okta" filter) → Create Relationship → Tab "Relationships" mostra implements→ task 🔗
- [ ] /context → Graph 3 anelli: hop0 (centro) · hop1 (solid task) · hop2 (dashed se esistevano) → Click nodo task (si ricentra) ✅
- [ ] /code → Filtro Severity High → riga CS-003 → click → **Mark as fixed" → Badge 🟢 Resolved ✅
- [ ] /traceability → Click nodo INC-77 → Inspector caused_by DEP-44 → Click DEP → chain completa
- [ ] /jobs → pulsante **Enqueue job → compila form titolo="Smoke test job", queue=testing, priority=normal → Invia → Attesa 3s → Status queued → Running → **Completed 100% ✅
- [ ] Jobs riga completata → Click → JSON modale Detail 100% completati → Usage result
- [ ] /ask-asf → Invia domanda: "Quale task implementa il requirement SSO?" → Attendi 202+poll → bolle user e AI → Copy clipboard ✅
- [ ] `make tsc` → 0 errors
- [ ] `make test` → 12+6+8+7+4 = 37/37 ✅ GREEN