# blakiatech/blakia-agent-launchpad architecture

> Architecture diagram of the GitHub repository blakiatech/blakia-agent-launchpad, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/blakiatech/blakia-agent-launchpad
- Repository: https://github.com/blakiatech/blakia-agent-launchpad

## Overview

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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    Client["Client"]:::external

    %% EntryPoint / API Layer
    subgraph "EntryPoint / API Layer"
        FastAPI["FastAPI App"]:::infra
    end

    %% Dependency Injection
    DI["Dependency Injection"]:::core

    %% Ports
    subgraph "Ports"
        InboundPorts["Inbound Ports"]:::ports
        OutboundPorts["Outbound Ports"]:::ports
    end

    %% Core
    subgraph "Core (Hexagon)"
        Agents["Core Agents"]:::core
        Graph["Core Graph"]:::core
        subgraph "Memory"
            Codec["Memory Codec"]:::core
            InMem["In-Memory Store"]:::core
            Manager["Memory Manager"]:::core
            Processors["Memory Processors"]:::core
            RedisHistory["Redis History Store"]:::core
            RedisStore["Redis Store"]:::core
        end
        Tools["Tooling Helpers"]:::core
    end

    %% Adapters
    subgraph "Adapters"
        Webhook["Generic Webhook Adapter"]:::adapters
        Telegram["Telegram Adapter"]:::adapters
        subgraph "WhatsApp Business Adapter"
            WA_Cards["Cards & Templates"]:::adapters
            WA_Catalog["Catalog"]:::adapters
            WA_Client["Client Wrapper"]:::adapters
            WA_Handler["Handler"]:::adapters
            WA_Models["Message Models"]:::adapters
            WA_Sender["Sender"]:::adapters
        end
    end

    %% Infrastructure
    subgraph "Infrastructure"
        Server["Server Bootstrap"]:::infra
        Settings["Application Settings"]:::infra
    end

    %% Observability
    subgraph "Observability"
        LF_Config["Langfuse Config"]:::observability
        LF_Tracing["Langfuse Tracing Hooks"]:::observability
    end

    %% External Services / Data Stores
    subgraph "External Services / Data Stores"
        RedisDB["Redis"]:::external
        VectorDB["Vector DB"]:::external
        Ext_WH["WhatsApp API"]:::external
        Ext_TG["Telegram API"]:::external
        Ext_Webhook["Webhook Endpoint"]:::external
    end

    %% Connections
    Client --> FastAPI
    FastAPI --> InboundPorts
    FastAPI --> Settings
    Settings --> InboundPorts
    Settings --> OutboundPorts
    InboundPorts --> Graph
    Graph --> Agents
    Graph --> Manager
    Graph --> Tools
    Manager --> Codec
    Manager --> InMem
    Manager --> RedisHistory
    Manager --> RedisStore
    Graph --> OutboundPorts
    OutboundPorts --> Webhook
    OutboundPorts --> Telegram
    OutboundPorts --> WA_Handler
    Webhook --> Ext_Webhook
    Telegram --> Ext_TG
    WA_Handler --> Ext_WH
    Server --> FastAPI
    Server --> Settings
    Server --> LF_Config
    LF_Config --> LF_Tracing
    Graph --> LF_Tracing
    FastAPI --> LF_Tracing
    Agents --> LF_Tracing
    Manager --> LF_Tracing

    %% Click Events
    click FastAPI "https://github.com/blakiatech/blakia-agent-launchpad/tree/main/src/app"
    click DI "https://github.com/blakiatech/blakia-agent-launchpad/blob/main/src/core/deps.py"
    click InboundPorts "https://github.com/blakiatech/blakia-agent-launchpad/blob/main/src/ports/messages.py"
    click OutboundPorts "https://github.com/blakiatech/blakia-agent-launchpad/blob/main/src/ports/outbound.py"
    click Agents "https://github.com/blakiatech/blakia-agent-launchpad/blob/main/src/core/agents.py"
    click Graph "https://github.com/blakiatech/blakia-agent-launchpad/blob/main/src/core/graph.py"
    click Codec "https://github.com/blakiatech/blakia-agent-launchpad/blob/main/src/core/memory/codec.py"
    click InMem "https://github.com/blakiatech/blakia-agent-launchpad/blob/main/src/core/memory/in_memory.py"
    click Manager "https://github.com/blakiatech/blakia-agent-launchpad/blob/main/src/core/memory/manager.py"
    click Processors "https://github.com/blakiatech/blakia-agent-launchpad/blob/main/src/core/memory/processors.py"
    click RedisHistory "https://github.com/blakiatech/blakia-agent-launchpad/blob/main/src/core/memory/redis_history.py"
    click RedisStore "https://github.com/blakiatech/blakia-agent-launchpad/blob/main/src/core/memory/redis_store.py"
    click Tools "https://github.com/blakiatech/blakia-agent-launchpad/blob/main/src/core/tools/dummy.py"
    click Webhook "https://github.com/blakiatech/blakia-agent-launchpad/blob/main/src/adapters/generic_webhook/handler.py"
    click Telegram "https://github.com/blakiatech/blakia-agent-launchpad/blob/main/src/adapters/telegram/handler.py"
    click WA_Cards "https://github.com/blakiatech/blakia-agent-launchpad/blob/main/src/adapters/whatsapp_business/cards.py"
    click WA_Catalog "https://github.com/blakiatech/blakia-agent-launchpad/blob/main/src/adapters/whatsapp_business/catalog.py"
    click WA_Client "https://github.com/blakiatech/blakia-agent-launchpad/blob/main/src/adapters/whatsapp_business/client.py"
    click WA_Handler "https://github.com/blakiatech/blakia-agent-launchpad/blob/main/src/adapters/whatsapp_business/handler.py"
    click WA_Models "https://github.com/blakiatech/blakia-agent-launchpad/blob/main/src/adapters/whatsapp_business/models.py"
    click WA_Sender "https://github.com/blakiatech/blakia-agent-launchpad/blob/main/src/adapters/whatsapp_business/sender.py"
    click Server "https://github.com/blakiatech/blakia-agent-launchpad/blob/main/src/infrastructure/server.py"
    click Settings "https://github.com/blakiatech/blakia-agent-launchpad/blob/main/src/infrastructure/settings.py"
    click LF_Config "https://github.com/blakiatech/blakia-agent-launchpad/blob/main/src/observability/langfuse/configure.py"
    click LF_Tracing "https://github.com/blakiatech/blakia-agent-launchpad/blob/main/src/observability/langfuse/tracing.py"

    %% Styles
    classDef core fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef adapters fill:#d4edda,stroke:#333,stroke-width:1px
    classDef ports fill:#fff3cd,stroke:#333,stroke-width:1px
    classDef infra fill:#ffe5b4,stroke:#333,stroke-width:1px
    classDef observability fill:#ffd1a4,stroke:#333,stroke-width:1px
    classDef external fill:#e2e3e5,stroke:#333,stroke-width:1px
```
