IT
Il personaggio del globo di Eco², rifinito per questo portfolio a partire dall’ultimo personaggio principale ufficiale: un globo azzurro con terre verdi, un germoglio in cima e un volto marrone sorridente
Torna alla sala

Eco²

Backend · Cloud infrastructure

Indicazioni per la raccolta differenziata da una foto e una conversazione.

Un assistente IA tutto in uno che conosce il funzionamento della raccolta differenziata in Corea.

2025.10.31 — 2026.02.10

Progetto di squadra · base di infrastruttura e deployment → backend di dominio → elaborazione asincrona, agente conversazionale, verifica

2025 새싹 해커톤 (Saessak Hackathon)Premio eccellenza · 2025.12.02

  • App webServizio chiuso

Come si collegano davvero i 24 nodi, un flusso alla volta.

Kubernetes autogestito, costruito con kubeadm. La mappa colloca i 24 nodi fisici e i workload che ospitano nei cinque livelli del README e li unisce con le connessioni reali. Scegliendo un flusso se ne evidenzia solo il percorso, con passi numerati.

Riconosce i rifiuti da una foto e spiega come smaltirli, e in conversazione chiama strumenti per luoghi, meteo, prezzi del riciclo e ricerca web, e genera immagini. In questo progetto di squadra ho iniziato dalla base di cluster e deployment e ho esteso il mio ambito al backend di dominio, all’elaborazione asincrona, all’agente conversazionale e alla verifica.

Dallo sviluppo per la competizione al consolidamento di backend e operazioni

Il servizio ha concluso la sua attività; una demo registrata e il rapporto tecnico lo mostrano in funzione.

Mappa delle connessioni del cluster · ridisegnata dai manifest e dal codice al commit a072127
Mappa delle connessioni del cluster Eco² · 24 nodiUna mappa dei 24 nodi fisici dentro le cinque fasce di livello del README. Il browser cerca solo il nome in Route 53; dopo che il TLS termina all’ALB sulla 443, l’Envoy di ingress di Istio su un NodePort invia la richiesta a un’API di dominio. L’API Scan mette il lavoro in coda su RabbitMQ e restituisce subito un job_id; scan-worker nel pool AI scrive con XADD gli eventi di avanzamento in Redis Streams. L’Event Router li legge, aggiorna State KV e pubblica su Pub/Sub, e l’SSE Gateway li invia al browser. checkpoint-syncer salva i checkpoint di Chat e il persistence consumer sul nodo Chat salva i messaggi in PostgreSQL. Il Platform Layer non è un percorso delle richieste; configura, scala e osserva.BrowserHTTPS · SSEAWS ALB443 · qui termina il TLSRoute 53DNSGitHub Actions · Docker Hubimmagine · revisione del manifestLLM APIOpenAI · GoogleLangSmithtracciamento delle esecuzioni LLMFluent BitDaemonSet · ogni nodok8s-masterALB Controller · ExternalDNSArgo CD image updaterIstiodcontrol planek8s-ingress-gatewayIstio ingress Envoyk8s-api-scanScan APIk8s-api-chatChat APImessage consumerpersistence consumerk8s-api-authauth APIext-authzk8s-api-infoInfo APIinfo-workerk8s-api-charactercharacter APIk8s-api-imageimages APIk8s-api-usersusers APIk8s-api-locationlocation APIk8s-sse-gatewaySSE Gatewayk8s-event-routerEvent Routerk8s-rabbitmqRabbitMQk8s-worker-aik8s-worker-ai-2k8s-worker-storagek8s-worker-storage-2k8s-redis-pubsubPub/Subk8s-redis-streamsStreamsState KVk8s-redis-cacheCachek8s-postgresqlPostgreSQLk8s-redis-authblacklistk8s-monitoringKEDAPrometheusGrafanaAlertmanagerk8s-loggingElasticsearchKibanascan-workerchat-workercheckpoint-syncerauth-relayauth-workerusers-workercharacter-workercharacter-match-workerKialiJaeger · dev in-memoryCluster Kubernetes24 nodi · kubeadmEdge Layer1 nodoService Layer8 nodi · sidecar EnvoyIntegration Layer7 nodiPersistence Layer5 nodiPlatform Layer3 nodi · configurare · scalare · osservareGestito da AWSPool AIdomain: worker-aipool storagedomain: worker-storageNessun nodo fissato1risoluzione DNS2 HTTPS 443 · Browser → AWS ALB23HTTP · NodePort4VirtualService5task Celery6 consume · RabbitMQ → scan-worker67 HTTPS · Pool AI → LLM API78XADD scan:events9XREADGROUP10SETEX state11PUBLISH12SUBSCRIBE13stream SSE14Recupero alla riconnessione1 HTTPS 443 · Browser → AWS ALB12HTTP · NodePort3VirtualService4task Taskiq5 consume · RabbitMQ → chat-worker56 HTTPS · Pool AI → LLM API67XADD chat:events8XREADGROUP9PUBLISH10SUBSCRIBE11stream SSE12checkpoint13lettura del checkpoint14sincronizzazione su PostgreSQL15chat-persistence group16salvataggio dei messaggi1risoluzione DNS2 HTTPS 443 · Browser → AWS ALB23HTTP · NodePort4ext-authz · gRPC 500515consultazione della blacklist6VirtualService7gRPC8gRPC1outbox:blacklist2blacklist.events3 blacklist.events · RabbitMQ → auth-worker34salvataggio della blacklist5 Celery batch · RabbitMQ → users-worker56UPSERT1immagine · revisione del manifest2Ingress → ALB · record DNS3configurazione xDS4numero di Pod5 numero di Pod · KEDA → pool storage56log7 tracciamento delle esecuzioni LLM · Pool AI → LangSmith7

Richiesta Scan → consegna in tempo reale

Una richiesta di analisi di una foto diventa lavoro in coda, e i suoi eventi di avanzamento tornano allo stesso browser.

  1. Browserrisoluzione DNSRoute 53

    Dai record di Route 53 si risolve solo il nome. Le richieste non passano per il DNS.

  2. BrowserHTTPS 443AWS ALB

    Il TLS termina all’ALB.

  3. AWS ALBHTTP · NodePortIstio ingress Envoyk8s-ingress-gateway

    Passata all’Envoy di ingress di Istio tramite il NodePort del target di istanza EC2.

  4. Istio ingress Envoyk8s-ingress-gatewayVirtualServiceScan APIk8s-api-scan

    Instradata all’API Scan, che mette il lavoro in coda e restituisce subito un job_id; un’interrogazione del risultato risponde 202 finché il job non è terminato.

  5. Scan APIk8s-api-scantask CeleryRabbitMQk8s-rabbitmq

    Il task Scan va su RabbitMQ.

  6. RabbitMQk8s-rabbitmqconsumescan-workerk8s-worker-ai · k8s-worker-ai-2

    scan-worker (Celery · gevent) nel pool AI lo prende ed esegue Vision → Rule → Answer → Reward. Le quattro fasi sono task Celery concatenati, non nodi.

  7. Pool AIk8s-worker-ai · k8s-worker-ai-2HTTPSLLM API

    I worker di scan e chat chiamano le API di OpenAI e Google.

  8. scan-workerk8s-worker-ai · k8s-worker-ai-2XADD scan:eventsStreamsk8s-redis-streams

    Gli eventi di avanzamento vengono scritti in uno dei quattro shard di Streams.

  9. Streamsk8s-redis-streamsXREADGROUPEvent Routerk8s-event-router

    L’Event Router li legge come consumer group ed esegue XACK dopo l’elaborazione; pending e reclaim mantengono la consegna at-least-once.

  10. Event Routerk8s-event-routerSETEX stateState KVk8s-redis-streams

    Scrive lo stato più recente e un marcatore contro la doppia elaborazione in State KV sullo stesso nodo Redis.

  11. Event Routerk8s-event-routerPUBLISHPub/Subk8s-redis-pubsub

    Consegnato in tempo reale sul canale del job nel Pub/Sub a shard.

  12. Pub/Subk8s-redis-pubsubSUBSCRIBESSE Gatewayk8s-sse-gateway

    L’SSE Gateway si iscrive tramite un unico listener condiviso per processo e distribuisce a ogni browser connesso.

  13. SSE Gatewayk8s-sse-gatewaystream SSEBrowser

    Una connessione aperta sullo stesso percorso di ALB e ingress. La consegna è at-least-once; i duplicati sono gestiti in modo idempotente.

  14. State KVk8s-redis-streamsRecupero alla riconnessioneSSE Gatewayk8s-sse-gateway

    Alla riconnessione con Last-Event-ID, State KV e gli Streams conservati recuperano gli eventi persi.

Chat · token e archiviazione

I token di Chat seguono lo stesso percorso di eventi di Scan; checkpoint e messaggi sono salvati da due workload diversi.

  1. BrowserHTTPS 443AWS ALB

    Il TLS termina all’ALB.

  2. AWS ALBHTTP · NodePortIstio ingress Envoyk8s-ingress-gateway

    Passata all’Envoy di ingress di Istio tramite il NodePort del target di istanza EC2.

  3. Istio ingress Envoyk8s-ingress-gatewayVirtualServiceChat APIk8s-api-chat

    Instradata all’API Chat.

  4. Chat APIk8s-api-chattask TaskiqRabbitMQk8s-rabbitmq

    Il task Chat va su RabbitMQ.

  5. RabbitMQk8s-rabbitmqconsumechat-workerk8s-worker-ai · k8s-worker-ai-2

    chat-worker (Taskiq · asyncio) classifica l’intento con LangGraph, poi esegue se serve vision, gli strumenti selezionati, l’aggregator e se serve un riepilogo, e risponde. Ogni richiesta esegue solo i rami che le servono.

  6. Pool AIk8s-worker-ai · k8s-worker-ai-2HTTPSLLM API

    I worker di scan e chat chiamano le API di OpenAI e Google.

  7. chat-workerk8s-worker-ai · k8s-worker-ai-2XADD chat:eventsStreamsk8s-redis-streams

    Token ed eventi di fase vengono scritti in quattro shard di Streams; da lì il percorso di consegna è lo stesso di Scan.

  8. Streamsk8s-redis-streamsXREADGROUPEvent Routerk8s-event-router

    L’Event Router li legge come consumer group ed esegue XACK dopo l’elaborazione; pending e reclaim mantengono la consegna at-least-once.

  9. Event Routerk8s-event-routerPUBLISHPub/Subk8s-redis-pubsub

    Consegnato in tempo reale sul canale del job nel Pub/Sub a shard.

  10. Pub/Subk8s-redis-pubsubSUBSCRIBESSE Gatewayk8s-sse-gateway

    L’SSE Gateway si iscrive tramite un unico listener condiviso per processo e distribuisce a ogni browser connesso.

  11. SSE Gatewayk8s-sse-gatewaystream SSEBrowser

    Una connessione aperta sullo stesso percorso di ALB e ingress. La consegna è at-least-once; i duplicati sono gestiti in modo idempotente.

  12. chat-workerk8s-worker-ai · k8s-worker-ai-2checkpointCachek8s-redis-cache

    Il checkpoint di LangGraph è conservato in Redis Cache.

  13. Cachek8s-redis-cachelettura del checkpointcheckpoint-syncerk8s-worker-ai · k8s-worker-ai-2

    checkpoint-syncer legge il checkpoint da Redis.

  14. checkpoint-syncerk8s-worker-ai · k8s-worker-ai-2sincronizzazione su PostgreSQLPostgreSQLk8s-postgresql

    AsyncPostgresSaver lo salva in PostgreSQL in modo asincrono.

  15. Streamsk8s-redis-streamschat-persistence grouppersistence consumerk8s-api-chat

    Il persistence consumer sul nodo Chat legge gli eventi done come consumer group.

  16. persistence consumerk8s-api-chatsalvataggio dei messaggiPostgreSQLk8s-postgresql

    I messaggi di chat vengono salvati in PostgreSQL. È un workload diverso da checkpoint-syncer.

Ingresso · autenticazione

Il percorso sincrono dall’ingresso del cluster a un’API di dominio. Solo i percorsi protetti da policy controllano prima l’autenticazione; il traffico dei Pod tra i nodi passa su Calico VXLAN.

  1. Browserrisoluzione DNSRoute 53

    Dai record di Route 53 si risolve solo il nome. Le richieste non passano per il DNS.

  2. BrowserHTTPS 443AWS ALB

    Il TLS termina all’ALB.

  3. AWS ALBHTTP · NodePortIstio ingress Envoyk8s-ingress-gateway

    Passata all’Envoy di ingress di Istio tramite il NodePort del target di istanza EC2.

  4. Istio ingress Envoyk8s-ingress-gatewayext-authz · gRPC 50051ext-authzk8s-api-auth

    Solo i percorsi sotto una policy CUSTOM interrogano prima l’ext-authz in Go (timeout 2 s, failOpen false). Percorsi come login, health e docs sono esclusi.

  5. ext-authzk8s-api-authconsultazione della blacklistblacklistk8s-redis-auth

    Il token viene confrontato con la blacklist di Redis.

  6. Istio ingress Envoyk8s-ingress-gatewayVirtualServiceChat APIk8s-api-chat

    Instradata all’API Chat.

  7. Chat APIk8s-api-chatgRPCimages APIk8s-api-image

    La chiamata sincrona chat → images indicata nel README.

  8. auth APIk8s-api-authgRPCusers APIk8s-api-users

    La chiamata sincrona auth → users indicata nel README.

Pool storage · scritture asincrone

La blacklist di autenticazione e la proprietà dei personaggi sono salvate dai worker del pool storage, che prendono il lavoro da RabbitMQ.

  1. blacklistk8s-redis-authoutbox:blacklistauth-relayk8s-worker-storage · k8s-worker-storage-2

    auth-relay (l’auth-Bus del README) legge l’outbox di Redis.

  2. auth-relayk8s-worker-storage · k8s-worker-storage-2blacklist.eventsRabbitMQk8s-rabbitmq

    Ripubblica su RabbitMQ, con retry e una DLQ.

  3. RabbitMQk8s-rabbitmqblacklist.eventsauth-workerk8s-worker-storage · k8s-worker-storage-2

    auth-worker riceve gli eventi della blacklist.

  4. auth-workerk8s-worker-storage · k8s-worker-storage-2salvataggio della blacklistblacklistk8s-redis-auth

    Vengono salvati nella blacklist di Redis.

  5. RabbitMQk8s-rabbitmqCelery batchusers-workerk8s-worker-storage · k8s-worker-storage-2

    users-worker riceve in batch il lavoro sulla proprietà dei personaggi.

  6. users-workerk8s-worker-storage · k8s-worker-storage-2UPSERTPostgreSQLk8s-postgresql

    Viene applicato a PostgreSQL.

Configurare · scalare · osservare

Il Platform Layer non è un passo attraversato dalle richieste; distribuisce, configura, scala e osserva gli altri livelli. I nodi sono istanze EC2 create con Terraform, con kubeadm e Calico installati da Ansible; la CI si limita a validare Terraform e non lo applica mai automaticamente.

  1. GitHub Actions · Docker Hubimmagine · revisione del manifestArgo CD image updaterk8s-master

    Argo CD allinea la configurazione del cluster tramite App-of-Apps e Sync Waves. È stata confermata solo la collocazione sul control plane dell’image updater.

  2. ALB Controller · ExternalDNSk8s-masterIngress → ALB · record DNSGestito da AWS

    ALB Controller ed ExternalDNS configurano le risorse lato AWS. Non è un percorso seguito dalle richieste.

  3. Istiodk8s-masterconfigurazione xDSIstio ingress Envoyk8s-ingress-gateway

    Istiod invia via xDS la configurazione di Gateway, VirtualService ed EnvoyFilter all’Envoy di ingress e al sidecar Envoy di ogni API.

  4. KEDAk8s-monitoringnumero di PodPool AIk8s-worker-ai · k8s-worker-ai-2

    KEDA regola il numero di Pod dei worker. Il numero di nodi non cambia.

  5. KEDAk8s-monitoringnumero di Podpool storagek8s-worker-storage · k8s-worker-storage-2

    I Pod dei worker del pool storage sono scalati allo stesso modo.

  6. Fluent BitlogElasticsearchk8s-logging

    Fluent Bit è un DaemonSet su ogni nodo e invia i log a Elasticsearch.

  7. Pool AIk8s-worker-ai · k8s-worker-ai-2tracciamento delle esecuzioni LLMLangSmith

    Le trace delle chiamate LLM vanno a LangSmith, un SaaS esterno.

Tutte le connessioni con lo stesso peso. Scegliendo un flusso se ne evidenzia solo il percorso, con passi numerati.

  • Continua · direzione di richieste, lavoro, eventi e scritture
  • Punteggiata · risoluzione DNS; le richieste non vi passano
  • Tratteggiata · configurare o scalare; non è un percorso dei dati
  • Tratto lungo e punto · log e tracciamento delle esecuzioni
  • Linea nera spessa · il flusso scelto; i numeri danno l’ordine
  • Riquadro · un nodo fisico, nome host nell’intestazione
  • Chip interno · un workload in esecuzione su quel nodo
  • Cornice tratteggiata · un pool di scheduling di due nodi
  • Riquadro tratteggiato · fuori dal cluster, non contato come nodo
  • Contorno arancione · dove decide un modello
  • Control plane1 nodo
  • Domain API8 nodi
  • Pool AI2 nodi
  • pool storage2 nodi
  • Data5 nodi
  • Platform6 nodi

I cinque livelli del README (le fasce) e i gruppi fisici (la tinta dell’intestazione di ogni nodo) raggruppano diversamente gli stessi 24 nodi. State KV condivide il nodo di Streams e non è contato a parte; Route 53, l’ALB e i servizi fuori dal cluster non sono nodi. Un pool è un ambito di scheduling, non l’affermazione che ogni pod giri su entrambi i nodi.

Struttura a 24 nodi · dall’elenco dei nodi della dashboard del January 21, 2026

24nodi

24 = 1 control plane + 8 API + 4 worker + 5 data + 6 platform

  1. 1Control plane

    role: control-plane

    kube-apiserver · scheduler · controller-manager · etcd, più i controller della piattaforma.

    1. k8s-master

  2. 8Domain API

    domain: <servizio>

    Un nodo per dominio. Le chiamate interne usano gRPC.

    1. k8s-api-auth
    2. k8s-api-users
    3. k8s-api-scan
    4. k8s-api-character
    5. k8s-api-location
    6. k8s-api-image
    7. k8s-api-chat
    8. k8s-api-info

  3. 4Execution worker

    Due pool di scheduling di due nodi ciascuno. KEDA cambia il numero di pod; il numero di nodi resta lo stesso.

    pool storagedomain: worker-storage
    1. k8s-worker-storage
    2. k8s-worker-storage-2
    Pool AIdomain: worker-ai
    1. k8s-worker-ai
    2. k8s-worker-ai-2

  4. 5Data

    Redis è diviso per scopo su quattro nodi. Lo storage di PostgreSQL è EBS CSI · gp3.

    1. k8s-postgresql
    2. k8s-redis-auth
    3. k8s-redis-streams
    4. k8s-redis-cache
    5. k8s-redis-pubsub

  5. 6Platform

    Messaggistica, osservabilità, ingress e consegna in tempo reale hanno ciascuno un proprio nodo.

    1. k8s-rabbitmq
    2. k8s-monitoring
    3. k8s-logging
    4. k8s-ingress-gateway
    5. k8s-sse-gateway
    6. k8s-event-router
Ogni nodo
  • Fluent Bit · DaemonSet
  • Calico

Modelli configurati · per provider

Il servizio è stato chiuso, quindi questi sono i modelli configurati nel repository, non scelte disponibili oggi. Ogni ruolo è elencato a parte; non è un elenco di esecuzioni verificate.

  • OpenAI

    Provider predefinito di Chat

    Chat

    • openai/gpt-5.2predefinito

    Il modello predefinito è gpt-5.2; se la richiesta indica un modello, si usa quello.

    Scan

    • gpt-5.2predefinito
    • gpt-5.2-pro
    • gpt-5.1
    • gpt-5
    • gpt-5-pro
    • gpt-5-mini

    I modelli fuori dalla mappatura dei 13 modelli vengono rifiutati.

    Mappatura delle immagini

    • gpt-image-1.5

    Separato da gpt-5.2, il modello di orchestrazione di Responses. La generazione di immagini è disattivata per impostazione predefinita.

    Valutazione

    • gpt-4o-minipredefinito

    Il grader LLM per la valutazione delle conversazioni, separato dal modello Chat.

  • Google

    Quando Chat seleziona Google

    Chat

    • google/gemini-3-pro-preview
    • google/gemini-3-flash-preview

    Con Google selezionato, gemini-3-flash-preview è il predefinito.

    Scan

    • gemini-3-pro-preview
    • gemini-3-flash-preview
    • gemini-2.5-pro
    • gemini-2.5-flash
    • gemini-2.5-flash-lite
    • gemini-2.0-flash
    • gemini-2.0-flash-lite

    Mappatura delle immagini

    • gemini-3-pro-image-preview

Fontebackend main d8840c7Commit pubblico September 29, 2026 · verificato October 8, 2026