# 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:
```bash
# 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:
```bash
# 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:
```bash
# 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:
```bash
# 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:
```bash
# 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:
```bash
# 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

```bash
# 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
```bash
cd /home/architect/captain-claude/context-manager
python -m src.database init

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

#### 2. Guardar contexto
```python
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
```python
# 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)
```python
# Seleccionar contexto óptimo con IA
selected = cm.select_context_ai(
    query="Necesito información sobre arquitectura",
    provider="anthropic"  # o "openai"
)
```

### Variables de Entorno Requeridas

```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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