114 lines
7.1 KiB
Markdown
114 lines
7.1 KiB
Markdown
# 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 |
|