system-docs/MANUAL_USUARIO_ARCHITECT.md

MANUAL DE USUARIO - ARCHITECT (Servidor Central TZZR)

Introducción

ARCHITECT es el coordinador central del sistema TZZR alojado en el servidor 69.62.126.110. Este manual describe los servicios, herramientas y procedimientos para trabajar en el servidor central.

Información del Servidor

Aspecto	Detalles
IP	69.62.126.110
Usuario	architect
Ubicación	Servidor Central TZZR
Rol	Coordinador multiagente, gestión de servicios

Servicios Disponibles

1. Gitea (Control de Versiones)

Puerto: 3000 URL: http://69.62.126.110:3000 Uso: Repositorio central de código para todos los proyectos

Características:

• Hospedaje de repositorios Git
• Interfaz web para gestión de código
• Integración con pipelines de CI/CD
• Backup automático en R2

Acceso:

# Clonar repositorio
git clone http://69.62.126.110:3000/architect/[repo-name].git

# Ver estado de repositorio
cd /home/architect/[repo-name]
git status
git log --oneline

2. PostgreSQL (Base de Datos)

Puerto: 5432 Usuario: architect Base de datos: TTZR (por defecto) Uso: Almacenamiento central de datos persistentes

Características:

• Base de datos relacional centralizada
• Backups automáticos en R2
• Esquemas versionados
• Logs de auditoría

Conexión:

# Conectar a PostgreSQL
psql -h localhost -U architect -d TTZR

# Comandos básicos en psql:
\dt              # Listar tablas
\d [tabla]       # Ver estructura de tabla
SELECT * FROM [tabla] LIMIT 10;  # Consultar datos

Acceso a Servidores Remotos

Tienes acceso SSH a tres servidores remotos via la clave ~/.ssh/tzzr:

Servidores Disponibles

Servidor	IP	Acceso	Rol
deck	72.62.1.113	root@72.62.1.113	GPU/Computación
corp	92.112.181.188	root@92.112.181.188	Servicios corporativos
hst	72.62.2.84	root@72.62.2.84	HST-API + Directus

Conectar a servidor remoto:

# Conexión general
ssh root@[IP] -i ~/.ssh/tzzr

# Ejemplos:
ssh root@72.62.1.113 -i ~/.ssh/tzzr    # Conectar a deck
ssh root@92.112.181.188 -i ~/.ssh/tzzr # Conectar a corp
ssh root@72.62.2.84 -i ~/.ssh/tzzr     # Conectar a hst

Almacenamiento R2 (Cloudflare)

Configuración

Endpoint: https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com Bucket: architect Acceso: via AWS CLI

Estructura de Carpetas R2

s3://architect/
├── documentos adjuntos/          # Documentos para compartir con usuario
├── documentos adjuntos/architect/ # Reportes y documentación generada
├── system/                        # Configs, backups internos, manuales
├── gpu-services/                  # Servicios GRACE/PENNY/FACTORY
├── backups/                       # Backups automáticos de Gitea/PostgreSQL
└── auditorias/                    # Logs de auditoría y eventos

Comandos R2 Básicos

Listar contenido:

# Listar raíz de bucket
aws s3 ls s3://architect/ --endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com

# Listar carpeta específica
aws s3 ls s3://architect/system/ --endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com

# Listar recursivamente
aws s3 ls s3://architect/system/ --recursive --endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com

Subir archivos:

# Subir documento para usuario
aws s3 cp archivo.md "s3://architect/documentos adjuntos/archivo.md" \
  --endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com

# Subir a system (configs, manuales, backups internos)
aws s3 cp archivo "s3://architect/system/archivo" \
  --endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com

# Subir carpeta completa
aws s3 cp carpeta/ "s3://architect/system/carpeta/" --recursive \
  --endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com

Descargar archivos:

# Descargar archivo individual
aws s3 cp "s3://architect/system/archivo" ./archivo \
  --endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com

# Descargar carpeta recursivamente
aws s3 cp "s3://architect/system/carpeta/" ./ --recursive \
  --endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com

Gestión de Backups

Backups Automáticos

El sistema realiza backups automáticos de:

• Gitea: Repositorios y base de datos Gitea
• PostgreSQL: Base de datos TTZR
• Almacenados en: s3://architect/backups/

Restaurar desde Backup

# Listar backups disponibles
aws s3 ls s3://architect/backups/ --recursive \
  --endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com

# Descargar backup
aws s3 cp "s3://architect/backups/[backup-name]" ./ \
  --endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com

# Restaurar PostgreSQL desde dump
psql -h localhost -U architect -d TTZR < backup.sql

Uso de context-manager Local

context-manager es una herramienta local para gestionar contexto de aplicaciones y bases de datos.

Ubicación

/home/architect/captain-claude/context-manager/

Estructura

context-manager/
├── schemas/           # Esquemas SQL versionados
│   ├── 00_base.sql
│   ├── 01_immutable_log.sql
│   ├── 02_context_manager.sql
│   └── 03_algorithm_engine.sql
├── src/              # Código Python
│   ├── database.py       # Conexión y operaciones BD
│   ├── models.py         # Modelos de datos
│   ├── context_selector.py
│   └── providers/        # Proveedores de IA
│       ├── base.py
│       ├── anthropic.py
│       └── openai.py
└── tests/            # Tests

Uso Básico

1. Inicializar base de datos

cd /home/architect/captain-claude/context-manager
python -m src.database init

# Ver estado de BD
python -m src.database status

2. Guardar contexto

from src.database import ContextManager

cm = ContextManager()

# Guardar contexto
cm.save_context(
    context_id="task-123",
    content="Descripción de la tarea",
    metadata={"project": "skynet", "version": 8}
)

3. Recuperar contexto

# Recuperar contexto
context = cm.get_context("task-123")
print(context.content)
print(context.metadata)

# Listar contextos
contexts = cm.list_contexts(project="skynet")

4. Seleccionar contexto (IA)

# Seleccionar contexto óptimo con IA
selected = cm.select_context_ai(
    query="Necesito información sobre arquitectura",
    provider="anthropic"  # o "openai"
)

Variables de Entorno Requeridas

# En ~/.bashrc o ~/.env
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."
export DATABASE_URL="postgresql://architect@localhost/TTZR"

Flujo de Trabajo Diario

1. Verificar Estado del Sistema

# Ver servicios activos
systemctl status

# Ver logs de Gitea
tail -f /var/log/gitea/gitea.log

# Ver conexión a PostgreSQL
psql -h localhost -U architect -d TTZR -c "SELECT version();"

2. Gestionar Repositorios

# Clonar nuevo repo desde Gitea
git clone http://69.62.126.110:3000/architect/[proyecto].git

# Trabajar localmente
cd [proyecto]
git checkout -b feature/[nombre]
# ... realizar cambios ...
git add .
git commit -m "Descripción de cambios"
git push origin feature/[nombre]

# En Gitea: crear Pull Request y revisar

3. Manejar Datos

# Backup de BD antes de cambios importantes
pg_dump -h localhost -U architect TTZR > backup-$(date +%Y%m%d).sql

# Exportar desde R2
aws s3 cp "s3://architect/backups/" ./backups/ --recursive \
  --endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com

4. Documentar y Archivar

# Generar documentación
# ... crear archivos .md ...

# Subir a R2
aws s3 cp reporte.md "s3://architect/documentos adjuntos/architect/reporte.md" \
  --endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com

# Verificar subida
aws s3 ls "s3://architect/documentos adjuntos/architect/" \
  --endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com

# Limpiar local
rm reporte.md

Seguridad y Mejores Prácticas

SSH

• Usa siempre la clave ~/.ssh/tzzr para conectar a servidores remotos
• Nunca compartas las claves SSH
• Mantén permisos restrictivos: chmod 600 ~/.ssh/tzzr

Credenciales

• Nunca commits credenciales en Gitea
• Usa variables de entorno para API keys
• Rota credenciales regularmente

R2

• Verifica siempre que archivos se suban correctamente
• No guardes documentos en el filesystem local
• Limpia archivos locales después de subirlos a R2

Base de Datos

• Realiza backups antes de cambios estructurales
• Usa transacciones para operaciones críticas
• Revisa logs de auditoría regularmente

Troubleshooting

No puedo conectar a PostgreSQL

# Verificar que PostgreSQL está activo
systemctl status postgresql

# Verificar permisos
sudo -u postgres psql -c "SELECT * FROM pg_user WHERE usename = 'architect';"

# Reiniciar si es necesario
sudo systemctl restart postgresql

Error al subir a R2

# Verificar credenciales AWS configuradas
aws configure

# Verificar conectividad
aws s3 ls s3://architect/ --endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com

# Reintentar con --no-progress para más info
aws s3 cp archivo s3://architect/system/archivo --no-progress \
  --endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com

Gitea no responde

# Ver logs
tail -f /var/log/gitea/gitea.log

# Reiniciar servicio
sudo systemctl restart gitea

# Verificar puerto
netstat -tlnp | grep 3000

Contacto y Soporte

Para problemas con los servicios o el servidor:

1. Revisa los logs relevantes
2. Verifica el estado del servicio
3. Consulta la documentación en s3://architect/system/
4. Contacta al administrador del sistema

Referencias Rápidas

Puertos Importantes

• Gitea: 3000
• PostgreSQL: 5432
• SSH: 22

Directorios Importantes

• Proyectos: /home/architect/captain-claude/
• Backups locales: /home/architect/backups/
• Logs: /var/log/

Comandos Frecuentes

# Actualizar repositorio
cd /home/architect/[proyecto] && git pull

# Ver últimos cambios
git log --oneline -10

# Conectar a BD
psql -h localhost -U architect -d TTZR

# Listar en R2
aws s3 ls s3://architect/system/ --recursive \
  --endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com

---

Última actualización: Diciembre 2025 Versión: 1.0