asf/docs/architecture/overview.md

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