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