# n8n-io/self-hosted-ai-starter-kit architecture

> Architecture diagram of the GitHub repository n8n-io/self-hosted-ai-starter-kit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/n8n-io/self-hosted-ai-starter-kit
- Repository: https://github.com/n8n-io/self-hosted-ai-starter-kit

## Overview

##### Identifica el tipo de proyecto y su propósito
- Este es un “Self-hosted AI Starter Kit”: una plantilla Docker Compose que monta un entorno local para flujos de trabajo de IA low-code usando n8n, un LLM local (Ollama), un vector store (Qdrant) y PostgreSQL.
- No es una aplicación monolítica, sino un conjunto de microservicios orquestados por Docker Compose para pruebas de concepto y desarrollo local.

##### Analiza la estructura de archivos
- Top-level:
- .env, LICENSE, README.md
- docker-compose.yml → define los servicios, redes y volúmenes
- assets → imágenes y recursos (demo, gifs)
- n8n/demo-data → credenciales y workflows de ejemplo
- No hay código fuente propiamente dicho: la lógica corre dentro de los contenedores (n8n).

##### Extrae detalles del README
- Tecnologías clave:
- n8n (puerto 5678) para diseñar flujos de IA
- Ollama (puerto 11434) como motor LLM local
- Qdrant (puerto por defecto) para almacenamiento vectorial
- PostgreSQL (puerto 5432) como base relacional
- Volumen compartido: se monta /data/shared en n8n para acceso a ficheros locales.

##### Componentes principales y relaciones
a. Componentes:
1. Docker Compose (orquestador)
2. Servicio n8n
3. Servicio Ollama (LLM local)
4. Servicio Qdrant (vector DB)
5. Servicio PostgreSQL (base de datos)
6. Volumen Docker (shared-data) y carpeta local
7. Red Docker interna
b. Interacciones:
- n8n envía peticiones HTTP a Ollama para inferencia LLM
- n8n lee/escribe embeddings en Qdrant vía API HTTP
- n8n almacena estado y credenciales en PostgreSQL
- n8n accede al volumen compartido para lecturas/escrituras de ficheros locales
c. Patrones y principios:
- Microservicios ligeros desacoplados
- Configuración declarativa via Docker Compose
- Separación de capas: orquestación, lógica de flujos (n8n), IA, almacenamiento
d. Tecnologías y librerías:
- Docker Compose v3+
- n8n (Node.js + low-code GUI)
- Ollama (motor LLM local, multiplataforma)
- Qdrant (API RESTful para vectores)
- PostgreSQL (SQL, ACID)

##### Guía para el diagrama de sistema
- Utiliza cajas (rectángulos) para cada servicio:
- Caja azul: n8n (App)
- Caja naranja: Ollama
- Caja verde: Qdrant
- Caja gris: PostgreSQL
- Dibuja una nube o rectángulo envolvente “Docker Compose Network”
- Indica el volumen: un cilindro etiquetado “shared-volume ↔ /data/shared” conectado a n8n
- Mapea puertos sobre la caja de Docker Compose:
- 5678 → 5678 (n8n)
- 11434 → 11434 (Ollama)
- 5432 → 5432 (PostgreSQL)
- Flechas de dirección:
- n8n → Ollama (HTTP Inferencia)
- n8n → Qdrant (HTTP API)
- n8n → PostgreSQL (PG client)
- n8n ↔ Volumen (I/O ficheros)

##### Elementos gráficos recomendados
- Etiquetas claras en cada componente (nombre y puerto)
- Flechas sólidas con sentido de lectura
- Colores o iconos distintos para distinguir:
- Servicios de IA (Ollama, Qdrant)
- Servicio de orquestación (n8n)
- Base de datos relacional (PostgreSQL)
- Volumen de datos
- Leyenda o key para explicar colores y formas

##### Consejos finales
- Sé detallado: incluye configuración de perfiles GPU vs CPU si es relevante
- Muestra los ajustes de entorno (variables de OLLAMA_HOST, perfiles Docker Compose)
- Si planeas extender el kit, deja espacio para nuevos servicios (por ejemplo Redis, message broker)
- Mantén la claridad: el diagrama debe explicar en un vistazo cómo fluyen datos y peticiones entre los servicios

Con esta guía, el ingeniero principal podrá dibujar un diagrama preciso y específico que refleje con exactitud la arquitectura del “Self-hosted AI Starter Kit.”

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Docker Compose Network"
        direction TB
        Compose["Docker Compose"]:::compose
        n8n["n8n (5678)"]:::n8n
        Ollama["Ollama (11434)"]:::ollama
        Qdrant["Qdrant (Vector DB)"]:::qdrant
        Postgres["PostgreSQL (5432)"]:::postgres
        SharedVol["shared-volume ↔ /data/shared"]:::volume

        subgraph "n8n/demo-data"
            direction TB
            DemoCred1["sFfERYppMeBnFNeA.json"] 
            DemoCred2["xHuYe0MDGOs9IpBW.json"]
            DemoWorkflow["srOnR8PAY3u4RSwb.json"]
        end
    end

    n8n -->|"HTTP Inference"| Ollama
    n8n -->|"HTTP API"| Qdrant
    n8n -->|"PG Client"| Postgres
    n8n <--> SharedVol

    classDef n8n fill:#89CFF0,stroke:#000,stroke-width:1px
    classDef ollama fill:#FFA500,stroke:#000,stroke-width:1px
    classDef qdrant fill:#90EE90,stroke:#000,stroke-width:1px
    classDef postgres fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef volume fill:#CCCCFF,stroke:#000,stroke-width:1px
    classDef compose fill:#FFFFFF,stroke:#000,stroke-dasharray:5 5

    click Compose "https://github.com/n8n-io/self-hosted-ai-starter-kit/blob/main/docker-compose.yml"
    click n8n "https://github.com/n8n-io/self-hosted-ai-starter-kit/tree/main/n8n/"
    click DemoCred1 "https://github.com/n8n-io/self-hosted-ai-starter-kit/blob/main/n8n/demo-data/credentials/sFfERYppMeBnFNeA.json"
    click DemoCred2 "https://github.com/n8n-io/self-hosted-ai-starter-kit/blob/main/n8n/demo-data/credentials/xHuYe0MDGOs9IpBW.json"
    click DemoWorkflow "https://github.com/n8n-io/self-hosted-ai-starter-kit/blob/main/n8n/demo-data/workflows/srOnR8PAY3u4RSwb.json"
    click n8n "https://github.com/n8n-io/self-hosted-ai-starter-kit/tree/main/n8n/demo-data/"
    click Assets "https://github.com/n8n-io/self-hosted-ai-starter-kit/tree/main/assets/"
```
