first

2026-09-08 07:21:34 -04:00
commit a4b224da8e
169 changed files with 27483 additions and 0 deletions
@@ -0,0 +1,113 @@
+# ASF Architecture Overview
+
+> Metafora "**Ufficio Postale di ASF**":
+>
+> Ogni informazione che entra o esce da ASF è una **busta (Artifact)**.
+> Le **Relazioni** sono gli indirizzi che legano una busta all'altra.
+> RabbitMQ è il **carteggio** (posta interna), MongoDB l'**archivio**,
+> l'AI Gateway è l'**ufficio analisti** che legge le buste e risponde,
+> il Context Engine è l'**impiegato che raccoglie il fascicolo completo**
+> prima di passarlo a un analista.
+
+## Logical Diagram (ASCII)
+
+```
+                     ┌─────────────────────────────────────────────┐
+                     │              asf-web (Next.js)              │
+                     │  Shell · Overview · Context Explorer ·      │
+                     │  Traceability (React Flow) · Ask ASF chat   │
+                     └────────────────────┬────────────────────────┘
+                                          │ HTTPS /api/v1
+                     ┌────────────────────▼────────────────────────┐
+                     │        asf-core (FastAPI REST API)           │
+                     │  Orgs · Projects · Artifacts · Relations ·   │
+                     │  Jobs CRUD · Audit · Auth boundary           │
+                     └──────┬───────────────┬───────────┬───────────┘
+                            │               │           │
+              (writes/reads)│      (events) │   (queries)│
+                            ▼               ▼           ▼
+                   ┌─────────────┐   ┌────────────┐  ┌───────────────┐
+                   │   MongoDB   │   │  RabbitMQ  │  │  asf-context  │
+                   │  (archivio) │   │ (carteggio)│  │ (fascicolatore)│
+                   └─────────────┘   └──────┬─────┘  └───────┬───────┘
+                                            │                │
+                                     (jobs) │                │ assemble context
+                                            ▼                │
+                                 ┌───────────────────┐       │
+                                 │   asf-worker      │       │
+                                 │ (addetti alle poste)│     │
+                                 │ consumers:        │       │
+                                 │ ai.*, indexing,   │       │
+                                 │ testing, devops   │       │
+                                 └─────────┬─────────┘       │
+                                           │                 │
+                                     (inference reqs)        │
+                                           ▼                 │
+                                 ┌───────────────────┐       │
+                                 │     asf-ai        │◄──────┘
+                                 │ AI Gateway        │
+                                 │ (ufficio analisti)│
+                                 │ ├─ MockProvider   │
+                                 │ ├─ model routing  │
+                                 │ └─ usage/cost     │
+                                 └─────────┬─────────┘
+                                           │
+                                           ▼
+                           ┌───────────────────────────────┐
+                           │ Provider adapters (future):   │
+                           │ · NVIDIA DGX / OpenAI compat │
+                           │ · External providers         │
+                           └───────────────────────────────┘
+
+ ┌────────────────────────────────────────────────────────────────┐
+ │ Shared packages (imported by all services):                    │
+ │ · asf-domain   → Pydantic models (Artifact, Job, Org, ...)     │
+ │ · asf-events   → Event schemas (RabbitMQ payload contracts)    │
+ │ · asf-connectors → Integration interfaces (GitHub, Jira, ...)  │
+ └────────────────────────────────────────────────────────────────┘
+
+ ┌─────────────────────────────┐
+ │   Supporting infrastructure │
+ │  · Redis (cache / locks)    │
+ │  · MinIO (large blobs)      │
+ └─────────────────────────────┘
+```
+
+## Data Flow — end-to-end (Example: "Crea un Requirement")
+
+1. User POST `/api/v1/projects/{p_id}/artifacts` (type=`requirement`)
+   via **asf-web** → **asf-core**.
+2. **asf-core** validates tenant context, writes to MongoDB `artifacts`,
+   emits `artifact.created` event to RabbitMQ, returns `201`.
+3. **asf-worker** picks up `artifact.created` from the events exchange.
+4. Worker optionally submits `ai.inference.requested` for "enrich
+   requirement" to `asf.ai.background` queue.
+5. Another worker calls **asf-ai** gateway → provider → returns
+   enrichment. Updates `artifact.metadata.enriched = true`, writes an
+   `artifact.updated` event, records an `AIExecution` in MongoDB.
+6. UI polls / SSE receives update; Context Explorer now shows both the
+   Artifact AND its enrichment trace.
+
+## Tenancy Boundary
+
+```
+ Organization (tenant_id == organization_id in bootstrap)
+  │
+  ├── Team[]
+  └── Project[]
+       └── Artifact[] + ArtifactRelationship[] + Job[]
+```
+
+**Rule:** Ogni query su dati tenant-owned è filtrata da `tenant_id`.
+Il `tenant_id` non viene mai accettato dal client direttamente ma
+deriva dal contesto di autenticazione validato.
+
+## Extensibility Points
+
+| Concern               | Where                      | Future Hook                    |
+|-----------------------|----------------------------|--------------------------------|
+| Semantic search / RAG | asf-context                | Vector DB (pgvector / Qdrant)  |
+| Graph traversal       | asf-context (Mongo $lookup)| Graph DB projection            |
+| Auth / SSO            | asf-core middleware        | OIDC / SAML adapters           |
+| Billing / metering    | asf-core + asf-ai usage    | Subscription service           |
+| External providers    | asf-connectors + AI Gateway| Per-system adapter             |