# mrebola/akbal-pi architecture

> Architecture diagram of the GitHub repository mrebola/akbal-pi, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mrebola/akbal-pi
- Repository: https://github.com/mrebola/akbal-pi

## Overview

Akbal es un asistente local para Raspberry Pi con interacción por voz y una interfaz web de administración. El flujo principal es pulsar el botón, hablar, transcribir el audio, generar una respuesta y reproducirla por voz mientras se actualiza la pantalla. La aplicación también ofrece selección de modos, chat web, gestión WiFi y funciones de radar, wardriving, GPS y música. El README documenta estas capacidades; como los extractos de código son parciales, las conexiones no verificables se omiten.

Main entry points: [`app/src/device/web-admin-server.ts`](https://github.com/mrebola/akbal-pi/blob/main/app/src/device/web-admin-server.ts) (Servidor web), [`app/src/core/ChatFlow.ts`](https://github.com/mrebola/akbal-pi/blob/main/app/src/core/ChatFlow.ts) (Flujo conversacional), [`app/src/cloud-api/llm.ts`](https://github.com/mrebola/akbal-pi/blob/main/app/src/cloud-api/llm.ts) (LLM y herramientas), [`app/web/admin/app.js`](https://github.com/mrebola/akbal-pi/blob/main/app/web/admin/app.js) (Interfaz web)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Interacción y dispositivo"]
  node_button["Botón y audio<br/>[audio.ts]"]
  node_flow["Flujo conversacional<br/>[ChatFlow.ts]"]
  node_modes["Modos y comandos<br/>[stateMachine.ts]"]
  node_speaker["Salida de audio<br/>[audio.ts]"]
  node_display["Pantalla Whisplay<br/>[display.ts]"]
  node_displayui["Vista de pantalla<br/>[app.js]"]
end

subgraph group_ai["IA y conocimiento"]
  node_speech["Reconocimiento de voz<br/>[server.ts]"]
  node_llm["LLM y herramientas<br/>[llm.ts]"]
  node_plugins["Proveedores IA<br/>[registry.ts]"]
  node_knowledge[("Conocimiento y vectores<br/>[knowledge.ts]")]
  node_tts["Síntesis de voz<br/>[server.ts]"]
end

subgraph group_web["Administración web"]
  node_admin["Interfaz web<br/>[app.js]"]
  node_webserver["Servidor web"]
  node_wifi["WiFi y redes<br/>[wifi.ts]"]
  node_storage["Archivos y USB<br/>[storage.ts]"]
end

subgraph group_radio["Radio y ubicación"]
  node_radar["Radar WiFi<br/>[service.ts]"]
  node_wardrive["Wardriving<br/>[service.ts]"]
  node_audit["Auditoría WiFi<br/>[service.ts]"]
  node_aircraft["Radar ADS-B<br/>[service.ts]"]
end

subgraph group_services["Servicios del dispositivo"]
  node_gps["Posición GPS<br/>[gps.ts]"]
  node_music["Reproductor musical<br/>[music-player.ts]"]
end

node_person(("Usuario"))
node_externalai{{"Servicios de IA externos"}}
node_radiohardware{{"Adaptadores y HackRF"}}

node_person -->|"pulsa y habla"| node_button
node_button -->|"entrega audio"| node_flow
node_flow -->|"solicita transcripción"| node_speech
node_speech -->|"devuelve texto"| node_flow
node_flow -->|"consulta modo"| node_modes
node_flow -->|"solicita respuesta"| node_llm
node_llm -->|"activa proveedor"| node_plugins
node_llm -->|"consulta conocimiento"| node_knowledge
node_llm -.->|"invoca proveedor"| node_externalai
node_flow -->|"solicita voz"| node_tts
node_tts -->|"entrega audio"| node_speaker
node_flow -->|"actualiza estado"| node_display
node_display -->|"sirve vista"| node_displayui
node_person -->|"usa interfaz"| node_admin
node_admin -->|"solicita API"| node_webserver
node_webserver -->|"gestiona redes"| node_wifi
node_webserver -->|"gestiona archivos"| node_storage
node_webserver -->|"consulta radar"| node_radar
node_webserver -->|"gestiona sesiones"| node_wardrive
node_webserver -->|"ejecuta auditoría"| node_audit
node_webserver -->|"consulta tráfico"| node_aircraft
node_radar -->|"captura señales"| node_radiohardware
node_wardrive -->|"captura redes"| node_radiohardware
node_aircraft -->|"recibe ADS-B"| node_radiohardware
node_aircraft -->|"usa posición"| node_gps
node_admin -->|"controla música"| node_music

click node_button "https://github.com/mrebola/akbal-pi/blob/main/app/src/device/audio.ts"
click node_flow "https://github.com/mrebola/akbal-pi/blob/main/app/src/core/ChatFlow.ts"
click node_modes "https://github.com/mrebola/akbal-pi/blob/main/app/src/core/chat-flow/stateMachine.ts"
click node_speech "https://github.com/mrebola/akbal-pi/blob/main/app/src/cloud-api/server.ts"
click node_llm "https://github.com/mrebola/akbal-pi/blob/main/app/src/cloud-api/llm.ts"
click node_plugins "https://github.com/mrebola/akbal-pi/blob/main/app/src/plugin/registry.ts"
click node_knowledge "https://github.com/mrebola/akbal-pi/blob/main/app/src/cloud-api/knowledge.ts"
click node_tts "https://github.com/mrebola/akbal-pi/blob/main/app/src/cloud-api/server.ts"
click node_speaker "https://github.com/mrebola/akbal-pi/blob/main/app/src/device/audio.ts"
click node_display "https://github.com/mrebola/akbal-pi/blob/main/app/src/device/display.ts"
click node_displayui "https://github.com/mrebola/akbal-pi/blob/main/app/web/whisplay-display/app.js"
click node_admin "https://github.com/mrebola/akbal-pi/blob/main/app/web/admin/app.js"
click node_webserver "https://github.com/mrebola/akbal-pi/blob/main/app/src/device/web-admin-server.ts"
click node_wifi "https://github.com/mrebola/akbal-pi/blob/main/app/src/utils/wifi.ts"
click node_storage "https://github.com/mrebola/akbal-pi/blob/main/app/src/utils/storage.ts"
click node_radar "https://github.com/mrebola/akbal-pi/blob/main/app/src/wifiradar/service.ts"
click node_wardrive "https://github.com/mrebola/akbal-pi/blob/main/app/src/wardrive/service.ts"
click node_audit "https://github.com/mrebola/akbal-pi/blob/main/app/src/wifi-audit/service.ts"
click node_aircraft "https://github.com/mrebola/akbal-pi/blob/main/app/src/services/adsb/service.ts"
click node_gps "https://github.com/mrebola/akbal-pi/blob/main/app/src/utils/gps.ts"
click node_music "https://github.com/mrebola/akbal-pi/blob/main/app/src/device/music-player.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_button,node_flow,node_modes,node_speaker,node_display,node_displayui toneBlue
class node_speech,node_llm,node_plugins,node_knowledge,node_tts toneAmber
class node_admin,node_webserver,node_wifi,node_storage toneMint
class node_radar,node_wardrive,node_audit,node_aircraft toneRose
class node_gps,node_music,node_person,node_externalai,node_radiohardware toneIndigo
```

## Components

### Interacción y dispositivo

- [Botón y audio](https://github.com/mrebola/akbal-pi/blob/main/app/src/device/audio.ts): `app/src/device/audio.ts`
- [Flujo conversacional](https://github.com/mrebola/akbal-pi/blob/main/app/src/core/ChatFlow.ts): `app/src/core/ChatFlow.ts`
- [Modos y comandos](https://github.com/mrebola/akbal-pi/blob/main/app/src/core/chat-flow/stateMachine.ts): `app/src/core/chat-flow/stateMachine.ts`
- [Salida de audio](https://github.com/mrebola/akbal-pi/blob/main/app/src/device/audio.ts): `app/src/device/audio.ts`
- [Pantalla Whisplay](https://github.com/mrebola/akbal-pi/blob/main/app/src/device/display.ts): `app/src/device/display.ts`
- [Vista de pantalla](https://github.com/mrebola/akbal-pi/blob/main/app/web/whisplay-display/app.js): `app/web/whisplay-display/app.js`

### IA y conocimiento

- [Reconocimiento de voz](https://github.com/mrebola/akbal-pi/blob/main/app/src/cloud-api/server.ts): `app/src/cloud-api/server.ts`
- [LLM y herramientas](https://github.com/mrebola/akbal-pi/blob/main/app/src/cloud-api/llm.ts): `app/src/cloud-api/llm.ts`
- [Proveedores IA](https://github.com/mrebola/akbal-pi/blob/main/app/src/plugin/registry.ts): `app/src/plugin/registry.ts`
- [Conocimiento y vectores](https://github.com/mrebola/akbal-pi/blob/main/app/src/cloud-api/knowledge.ts): `app/src/cloud-api/knowledge.ts`
- [Síntesis de voz](https://github.com/mrebola/akbal-pi/blob/main/app/src/cloud-api/server.ts): `app/src/cloud-api/server.ts`

### Administración web

- [Interfaz web](https://github.com/mrebola/akbal-pi/blob/main/app/web/admin/app.js): `app/web/admin/app.js`
- [Servidor web](https://github.com/mrebola/akbal-pi/blob/main/app/src/device/web-admin-server.ts): `app/src/device/web-admin-server.ts`
- [WiFi y redes](https://github.com/mrebola/akbal-pi/blob/main/app/src/utils/wifi.ts): `app/src/utils/wifi.ts`
- [Archivos y USB](https://github.com/mrebola/akbal-pi/blob/main/app/src/utils/storage.ts): `app/src/utils/storage.ts`

### Radio y ubicación

- [Radar WiFi](https://github.com/mrebola/akbal-pi/blob/main/app/src/wifiradar/service.ts): `app/src/wifiradar/service.ts`
- [Wardriving](https://github.com/mrebola/akbal-pi/blob/main/app/src/wardrive/service.ts): `app/src/wardrive/service.ts`
- [Auditoría WiFi](https://github.com/mrebola/akbal-pi/blob/main/app/src/wifi-audit/service.ts): `app/src/wifi-audit/service.ts`
- [Radar ADS-B](https://github.com/mrebola/akbal-pi/blob/main/app/src/services/adsb/service.ts): `app/src/services/adsb/service.ts`

### Servicios del dispositivo

- [Posición GPS](https://github.com/mrebola/akbal-pi/blob/main/app/src/utils/gps.ts): `app/src/utils/gps.ts`
- [Reproductor musical](https://github.com/mrebola/akbal-pi/blob/main/app/src/device/music-player.ts): `app/src/device/music-player.ts`

### Other components

- **Usuario**
- **Servicios de IA externos**
- **Adaptadores y HackRF**

## Connections

- Usuario → Botón y audio: pulsa y habla
- Botón y audio → Flujo conversacional: entrega audio
- Flujo conversacional → Reconocimiento de voz: solicita transcripción
- Reconocimiento de voz → Flujo conversacional: devuelve texto
- Flujo conversacional → Modos y comandos: consulta modo
- Flujo conversacional → LLM y herramientas: solicita respuesta
- LLM y herramientas → Proveedores IA: activa proveedor
- LLM y herramientas → Conocimiento y vectores: consulta conocimiento
- LLM y herramientas → Servicios de IA externos: invoca proveedor
- Flujo conversacional → Síntesis de voz: solicita voz
- Síntesis de voz → Salida de audio: entrega audio
- Flujo conversacional → Pantalla Whisplay: actualiza estado
- Pantalla Whisplay → Vista de pantalla: sirve vista
- Usuario → Interfaz web: usa interfaz
- Interfaz web → Servidor web: solicita API
- Servidor web → WiFi y redes: gestiona redes
- Servidor web → Archivos y USB: gestiona archivos
- Servidor web → Radar WiFi: consulta radar
- Servidor web → Wardriving: gestiona sesiones
- Servidor web → Auditoría WiFi: ejecuta auditoría
- Servidor web → Radar ADS-B: consulta tráfico
- Radar WiFi → Adaptadores y HackRF: captura señales
- Wardriving → Adaptadores y HackRF: captura redes
- Radar ADS-B → Adaptadores y HackRF: recibe ADS-B
- Radar ADS-B → Posición GPS: usa posición
- Interfaz web → Reproductor musical: controla música