Passa al contenuto principale

High Level Design

Il High Level Design di Emblema presenta un'architettura distribuita moderna, progettata per gestire in modo efficiente l'elaborazione di contenuti multimediali, la ricerca semantica e l'interazione conversazionale con sistemi AI. Questa sezione descrive la visione architetturale complessiva e le decisioni di design fondamentali.

Architettura Generale del Sistema​

Panoramica Architetturale​

Emblema è strutturata secondo il pattern Layered Architecture combinato con Microservices, offrendo una separazione chiara delle responsabilità e una scalabilità indipendente dei componenti.

Loading diagram...

Principi di Design​

1. Separation of Concerns

  • Ogni layer ha responsabilità specifiche e ben definite
  • Business logic separata da presentazione e persistenza
  • AI processing isolato in servizi dedicati

2. Loose Coupling

  • Comunicazione attraverso API REST standardizzate
  • Message queues per operazioni asincrone
  • Event-driven interactions per decoupling

3. High Cohesion

  • Funzionalità correlate raggruppate nello stesso servizio
  • Single Responsibility Principle applicato rigorosamente
  • Clear interfaces tra i componenti

Componenti Principali​

🖥️ Frontend & Presentation Layer​

www-emblema (Next.js Application)

  • Responsabilità: Interfaccia utente principale, routing, state management
  • Tecnologie: React 18, Next.js 14, TypeScript, Tailwind CSS
  • Caratteristiche:
    • Server-Side Rendering (SSR) per performance
    • Progressive Web App (PWA) capabilities
    • Real-time updates via WebSockets
    • Responsive design per multi-device
// Esempio architettura frontend
interface ApplicationCore {
    router: NextRouter;
    stateManager: Zustand | Redux;
    authProvider: NextAuthProvider;
    i18nProvider: InternationalizationProvider;
    apiClient: GraphQLClient;
}

// Layout component structure
const Layout: FC = ({ children }) => (
    <AuthProvider>
        <I18nProvider>
            <MainLayout>
                <Sidebar />
                <MainContent>{children}</MainContent>
                <NotificationCenter />
            </MainLayout>
        </I18nProvider>
    </AuthProvider>
);

🔧 Business Logic Services​

www-emblema Backend

  • Responsabilità: Orchestrazione richieste, business logic, API Gateway interno
  • Architettura: Monolitico modulare con chiara separazione interna
  • Funzionalità:
    • User management e authorization
    • Document lifecycle management
    • Chat conversation handling
    • File upload coordination
    • Real-time notifications

background-task (Python/FastAPI)

  • Responsabilità: Elaborazione asincrona AI-intensive
  • Pattern: Worker pool con Celery
  • Specializzazioni:
    • Document processing (MinerU per PDF)
    • Audio/video transcription (WhisperX)
    • Semantic chunking e embedding generation
    • AI-powered content analysis
# Architettura reale background-task di Emblema
from celery import shared_task
from app.handlers import document as document_handler
from app.chunkers.auto import AutoChunker
from app.handlers.vector_db import store_embeddings
from app.handlers.notification import send_notification

@celery_app.task(bind=True)
def process_document_task(self, document_id: str):
    try:
        # 1. Ottieni documento da GraphQL
        document = document_handler.get(document_id)
        if not document:
            raise ValueError(f"Document {document_id} not found")

        # 2. Inizializza chunker automatico
        chunker = AutoChunker()

        # 3. Processa documento (ottimizzazione + chunking)
        chunks = await chunker.process_document(
            document_id=document_id,
            chunking_config=document.chunkerConfig or {}
        )

        # 4. Genera e salva embeddings in Milvus
        for chunk in chunks:
            await store_embeddings(
                chunk_id=chunk.id,
                content=chunk.content,
                document_id=document_id,
                metadata=chunk.metadata
            )

        # 5. Aggiorna status e invia notifica
        document_handler.update_status(document_id, "completed")
        await send_notification(
            user_id=document.createdBy,
            event="document.processing.completed",
            data={"document_id": document_id, "chunk_count": len(chunks)}
        )

    except Exception as e:
        # Retry con backoff esponenziale
        raise self.retry(countdown=60 * (2 ** self.request.retries), max_retries=3)

retrieval-service (Semantic Search)

  • Responsabilità: Ricerca semantica ottimizzata tramite Milvus
  • Specializzazione: Vector similarity search con controlli di accesso
  • Performance: Sub-second response times per query complesse

🧠 AI & ML Integration Layer​

LiteLLM Gateway

  • Funzione: Abstraction layer per multiple AI providers
  • Benefici:
    • Unified API per diversi modelli
    • Load balancing e fallback automatico
    • Cost optimization e rate limiting
    • Caching intelligente delle risposte
Loading diagram...

💾 Data Architecture​

Multi-Modal Data Storage

  • PostgreSQL: Metadata, users, configurations, relations
  • Milvus: Vector embeddings, semantic search indices
  • MinIO: Raw files, processed documents, media content
  • Redis: Session cache, task queues, temporary data
  • MongoDB: Notification system data (Novu)
Loading diagram...

Flussi di Dati Principali​

📤 Document Upload & Processing Flow​

Loading diagram...

🔍 Semantic Search Flow​

Loading diagram...

💬 AI Chat Conversation Flow​

Loading diagram...

Integrazione e Comunicazione​

🔌 Inter-Service Communication​

Synchronous Communication

  • REST APIs per operazioni real-time
  • GraphQL per query complesse e flessibili
  • HTTP/2 per performance ottimizzate

Asynchronous Communication

  • Redis pub/sub per eventi real-time
  • Celery task queues per long-running operations
  • WebSockets per notifiche istantanee
// Esempio client API unificato
class EmblemaAPIClient {
  private httpClient: AxiosInstance;
  private wsClient: WebSocket;
  private graphqlClient: GraphQLClient;

  // REST API calls
  async uploadDocument(file: File): Promise<Document> {
    return this.httpClient.post("/api/documents", file);
  }

  // GraphQL queries
  async searchDocuments(query: string): Promise<SearchResult[]> {
    return this.graphqlClient.request(SEARCH_DOCUMENTS, { query });
  }

  // Real-time subscriptions
  subscribeToNotifications(callback: (notification: Notification) => void) {
    this.wsClient.on("notification", callback);
  }
}

🌐 External Integrations​

Model Context Protocol (MCP)

  • Standardized protocol per integrazioni AI
  • Plugin architecture per estensioni custom
  • Support per tools e resources esterni

Authentication Integration

  • OpenID Connect con Keycloak
  • SAML support per enterprise SSO
  • API key authentication per service-to-service

Monitoring & Observability

  • Prometheus metrics collection
  • Distributed tracing con OpenTelemetry
  • Centralized logging con Loki/Grafana

Considerazioni Non-Funzionali​

🔒 Sicurezza​

  • Zero Trust Architecture - nessun componente trusted by default
  • Encryption everywhere - TLS per comunicazioni, AES per storage
  • Fine-grained RBAC - controlli accesso granulari
  • Audit logging completo - tracciabilità di tutte le operazioni

⚡ Performance​

  • Horizontal scaling - tutti i componenti scalabili orizzontalmente
  • Intelligent caching - cache multi-livello per performance
  • Async processing - operazioni pesanti in background
  • Database optimization - indici, connection pooling, query optimization

🚀 Scalabilità​

  • Microservices architecture - scaling indipendente per componente
  • Container orchestration - deployment e scaling automatizzati
  • Auto-scaling policies - scaling basato su metriche
  • Load balancing - distribuzione intelligente del carico

🔧 Maintainability​

  • Clear separation of concerns - responsabilità ben definite
  • Comprehensive testing - unit, integration, e2e testing
  • Documentation as code - documentazione sempre aggiornata
  • CI/CD pipelines - deployment automatizzato e sicuro

Prossimi Passi​

Questo High Level Design fornisce la visione architetturale generale. Per approfondimenti specifici:

  1. Low Level Design - Dettagli implementativi e pattern specifici
  2. Architettura Microservizi - Pattern e best practices per microservices
  3. Diagrammi di Flusso - Workflow dettagliati e sequence diagrams
  4. Requisiti Sistema - Specifiche hardware e software

Il High Level Design è un documento vivente che evolve con la piattaforma, mantenendo sempre l'equilibrio tra visione strategica e realtà implementativa.

Questa pagina ti è stata utile?