asf/TUTORIAL-PRIMO-PROGETTO.md

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):

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):

make start

Controlla che tutto sia vivo:

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)
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