How blakiatech/blakia-agent-launchpad works
Para diseñar un diagrama de arquitectura preciso y completo de Blakia Agent Launchpad, seguimos estos pasos adaptados al propósito y estructura del proyecto:
Identificación del tipo de proyecto y propósito
• Proyecto: Boilerplate para construir agentes de IA modernos.
• Propósito: Proveer una arquitectura hexagonal con lógica de negocio desacoplada, múltiples adaptadores (WhatsApp, Telegram, Webhooks), memoria (Redis + RAG), observabilidad (Langfuse/OTEL), y calidad industrial (lint, typing, testing).
Análisis de la estructura de archivos
• Top-level:
• src/app → punto de entrada (FastAPI / worker).
• src/core → lógica de negocio (graph, agentes, memoria, herramientas).
• src/adapters → conectores a canales externos (WhatsApp, Telegram, Webhooks).
• src/ports → interfaces inbound/outbound (mensajes, envío).
• src/infrastructure → servidor, configuración.
• src/observability → trazas y métricas (Langfuse + OpenTelemetry).
• Configuración y CI/CD: Dockerfile, GitHub Actions, mkdocs, mypy, pytest, etc.
Información clave del README
• Arquitectura hexagonal: separación clara entre core, adapters y ports.
• Memoria: implementaciones en memoria y Redis + preparado para vector DB (RAG).
• Observabilidad: Langfuse integrable en el flujo de ejecución.
• CI/CD y calidad: tests (unitarios, E2E), lint, type-check, coverage.
Creación del diagrama de sistema
a. Componentes principales
1) EntryPoint/API Layer
– FastAPI (src/app)
– Worker / CLI (si aplica)
2) Ports
– Inbound Ports (src/ports/messages.py): define modelos de entrada.
– Outbound Ports (src/ports/outbound.py): interfaz de envío.
3) Core (Hexágono Interior)
– Agents & Graph (src/core/agents.py, src/core/graph.py)
– Memory Manager / Processors (src/core/memory/*)
– Tools Helpers (src/core/tools)
4) Adapters (Conectores)
– Generic Webhook
– Telegram
– WhatsApp Business
5) Infrastructure & Configuration
– Server bootstrap (src/infrastructure/server.py)
– Settings (src/infrastructure/settings.py)
6) Observability
– Langfuse tracer (src/observability/langfuse)
– OpenTelemetry hooks
7) External Services / Data Stores
– Redis (history store, pub/sub)
– Vector DB (Qdrant/pgvector)
– Canales externos (APIs de WhatsApp, Telegram, Webhooks)
b. Relaciones e interacciones
1) Cliente → FastAPI → Inbound Port
2) Inbound Port → Core Graph/Agent
3) Core → Memory Manager ↔ Redis / In-Memory
4) Core → Outbound Port → Adapter correspondiente → Servicio externo
5) Cada llamada lleva instrumentación de trazas hacia Langfuse/OTEL
6) Configuración centralizada inyectada en cada capa
c. Patrones y principios arquitectónicos
• Hexagonal Architecture (Ports & Adapters)
• Dependency Injection vía core/deps.py
• Separación de responsabilidades:
• Core: lógica pura
• Adapters: I/O y protocolos externos
• Ports: contratos de comunicación
• Observabilidad transversal (Cross-cutting)
d. Tecnologías y librerías clave
• FastAPI (entrada HTTP)
• Pydantic-AI, LangGraph (modelado y orquestación de agentes)
• Redis + opcional Qdrant/pgvector (memoria y RAG)
• Langfuse + OpenTelemetry (trazas y métricas)
• Docker, GitHub Actions (CI/CD)
• Ruff, Mypy, Pytest
Guías según el tipo de proyecto
• Full-stack “agent API”:
• Mostrar claramente capa HTTP externa y el core desacoplado.
• Resaltar capa de persistencia (Redis/vector DB) y adaptadores de salida.
• Open-source boilerplate:
• Enfatizar puntos de extensión: puertos para nuevos adapters, memory stores.
• Indicar lugares para “plug-and-play” nuevos servicios (Qdrant, Slack, Email).
• Enfoque hexagonal:
• Distinguir entre núcleo puro y adaptadores en el diagrama.
Elementos imprescindibles para el diagrama
• Etiquetas claras en cada módulo/componente
• Flechas direccionales que muestren el flujo de datos (entrada → procesamiento → salida)
• Colores o formas:
• Núcleo/Core (azul)
• Adaptadores (verde)
• Puertos (amarillo)
• Infraestructura/Observabilidad (naranja)
• Servicios externos/Data Stores (gris)
Recomendaciones finales
• Sé detallado: incluye cada sub-componente (ej. Memory Manager vs. Memory Store).
• No añadas componentes irrelevantes (tests, CI/CD internos pueden quedar en “infraestructura” genérica).
• Revisa el diagrama con el equipo para asegurar que cada puerto, adapter y proceso de memoria esté representado.
Con este enfoque, el diagrama capturará fielmente la arquitectura hexagonal de Blakia Agent Launchpad, sus canales de entrada/salida, el núcleo de agentes IA, la capa de memoria y la observabilidad integradas.