Arquitectura¶

Como encajan las piezas del ecosistema.

Vista general¶

graph TD
    AHK[AutoHotkey<br/>capa de atajos] --> APPS

    subgraph APPS[Aplicaciones Python]
        TB[t-books]
        EI[editor-inteligente]
        AI[automatizacion-inea]
        DB[gestores *_db]
    end

    APPS --> SM[secrets_manager<br/>credenciales cifradas]
    SM --> HUB[(scripts/agentes.env<br/>hub central)]

    APPS --> CAP[src/capabilities<br/>inventario cloud]

    CAP --> AZ[Azure<br/>Foundry / VMs]
    CAP --> AWS[AWS<br/>Bedrock / S3]

    ENC[Enciclopedia<br/>este sitio] --> CAP
    ENC --> APPS

Hub de credenciales¶

Todas las aplicaciones comparten un unico origen de verdad para los secretos.

graph LR
    ENV[(scripts/agentes.env)] -->|expand_core| DERIV[Claves derivadas]
    DERIV -->|propagate| A1[editor-inteligente.env]
    DERIV -->|propagate| A2[git-llm.env]
    DERIV -->|propagate| A3[responder-cuestionario.env]
    DERIV -->|propagate| A4[aprendeinea.env]
    DERIV -->|propagate| A5[t-books.env]

Principios:

Una sola AZURE_AI_API_KEY; el resto de claves se derivan de ella.
Los valores sensibles se guardan cifrados con prefijo enc: (Fernet).
El descifrado requiere el PIN maestro (AHK_MASTER_PIN).
Los .env estan en .gitignore; solo se versionan los .example.

Regla de oro

Nunca escribir una clave en claro en el repositorio. Si se agrega un servicio nuevo, se registra en src/secrets_manager/schema.py como SecretField(secret=True) para que el cifrado lo reconozca.

Inventario de capacidades¶

El modulo src/capabilities centraliza el descubrimiento de recursos cloud.

Componente	Responsabilidad
`credentials.py`	Descifra credenciales y prepara el entorno
`collectors_azure.py`	Recolecta modelos y deployments de Foundry
`collectors_aws.py`	Recolecta modelos de Bedrock y cuotas EC2
`inventory.py`	Fusiona y normaliza el inventario cross-cloud
`operativos.py`	Fuente de verdad de modelos realmente invocables
`actions.py`	Acciones: activar modelo, probar invocacion
`history.py`	Bitacora append-only de cambios

Convenciones del repositorio¶

Estructura de una aplicacion¶

mi-app/
├── mi-app.ps1          # launcher PowerShell
├── mi-app.env          # configuracion (NO versionado)
├── .env.example        # plantilla versionada
├── requirements.txt
├── src/                # codigo
├── tests/              # pruebas
└── README.md

Entorno de ejecucion¶

Interprete unico: .venv\Scripts\python.exe en la raiz del workspace.
Codificacion: siempre -X utf8 y PYTHONIOENCODING=utf-8.
Los reportes markdown se escriben en UTF-8 sin BOM.

Nomenclatura¶

Elemento	Convencion
Carpetas de app	minusculas con guion (`editor-inteligente`)
Gestores de datos	sufijo `_db` (`personas_db`)
Launchers	`<nombre>.ps1`
Variables de entorno	MAYUSCULAS con guion bajo

Este sitio¶

La enciclopedia vive en enciclopedia/ dentro del monorepo, siguiendo el mismo patron que el resto de aplicaciones.

enciclopedia/
├── mkdocs.yml          # configuracion del sitio
├── docs/               # contenido markdown
├── api/                # FastAPI (monitor en vivo)
├── scripts/            # generadores de fichas
├── overrides/          # personalizacion del tema
└── enciclopedia.ps1    # launcher

Despliegue previsto:

Documentacion estatica en GitHub Pages (independiente de las suscripciones).
API del monitor en Azure App Service (ahk-webapp-prod).