Setup Local

Esta guía levanta el ecosistema completo (Mother, Orchestrator, Sevastopol, Nostromo y Jean d’Arc) en un entorno de desarrollo local. Cada componente puede correrse de forma independiente; el orden recomendado es: base de datos → backend → frontend → ETL → documentación.

Requisitos Previos

Software	Versión Mínima	Propósito
Node.js	20.x LTS	Runtime para Orchestrator, Sevastopol y Jean d’Arc
PostgreSQL	16.x	Base de datos Mother (multi-tenant)
Python	3.11+	ETL Nostromo (accounting_system/)
Git	2.x	Control de versiones
pnpm	10.x (corepack)	Gestor de paquetes obligatorio (Orchestrator, Sevastopol y Jean d’Arc)

Tip

pnpm se activa con corepack enable && corepack prepare pnpm@latest --activate. El monorepo Accounting/ (Orchestrator + Sevastopol) y Jean d’Arc usan exclusivamente pnpm — la versión está pinneada en package.json → packageManager.

---

Clonar el Monorepo

git clone https://github.com/ChrisTkm/Nostromo.git
cd Nostromo

Estructura del Monorepo

Nostromo/
├── orchestrator/       # Backend Node.js · Express · TypeScript
├── sevastopol/         # Frontend Astro · SolidJS
├── accounting_system/  # ETL Python (loaders BC, Previred, SII)
├── jean_d_arc/         # Documentación (este sitio)
└── .github/            # Workflows y skills compartidos

---

Mother: Base de Datos PostgreSQL

Mother es PostgreSQL 16 con arquitectura multi-tenant: dos bases del sistema y una base por empresa.

Crear bases del sistema

psql

CREATE DATABASE nostromo_common;
CREATE DATABASE nostromo_command;

createdb (CLI)

createdb -U postgres nostromo_common
createdb -U postgres nostromo_command

• nostromo_common aloja parámetros compartidos: monedas, indicadores, AFP, ISAPRE, tablas IUSC.
• nostromo_command aloja autenticación, sesiones y registro de tenants.

Plantilla y primer tenant

Cada empresa vive en su propia base, creada como copia de accunting_template:

CREATE DATABASE accunting_template;
-- Aplicar schemas accounting (remuneraciones, operaciones_sii, administracion...)
\c accunting_template
\i orchestrator/sql/template/init.sql

-- Crear un tenant a partir de la plantilla
CREATE DATABASE nostromo_60004317 WITH TEMPLATE accunting_template;

La convención es nostromo_<rut_empresa_sin_dv>. El RUT se persiste en nostromo_command.tenants.tenant_db y lo resuelve el middleware del Orchestrator en cada petición.

Caution

La plantilla accunting_template mantiene la falta de ortografía intencional por compatibilidad con el código existente del Orchestrator (getDatabaseNameForUser).

---

Variables de Entorno

Cada componente lee su propio .env. Los archivos .env.example viven en cada subcarpeta.

orchestrator/.env

PGHOST=localhost
PGPORT=5432
PGUSER=postgres
PGPASSWORD=$DB_PASSWORD
COMMAND_DB=nostromo_command
COMMON_DB=nostromo_common
JWT_SECRET=$JWT_SECRET
JWT_EXPIRES_IN=8h
CORS_ORIGINS=http://localhost:4321,http://localhost:4322
PORT=8000

sevastopol/.env

PUBLIC_API_URL=http://localhost:8000

accounting_system/.env

PGHOST=localhost
PGPORT=5432
PGUSER=postgres
PGPASSWORD=$DB_PASSWORD
PGDATABASE=nostromo_common

Caution

Nunca commitear .env. Los secretos reales viven en el gestor de credenciales del equipo; los .env.example se actualizan con cada nueva variable.

---

Setup por Componente

Orchestrator (Backend)

1. Instalar dependencias del workspace

   cd Accounting
   pnpm install

   El pnpm-workspace.yaml raíz instala Orchestrator y Sevastopol en una sola pasada.

2. Configurar variables de entorno

   cp orchestrator/.env.example orchestrator/.env
   # editar credenciales de PostgreSQL y JWT_SECRET

3. Iniciar en desarrollo

   pnpm --dir orchestrator dev
   # o desde la raíz del workspace:
   pnpm dev:orchestrator

   El backend queda escuchando en http://localhost:8000.

4. Verificar

   curl http://localhost:8000/health
   # → {"status":"OK","service":"orchestrator"}

---

Sevastopol (Frontend)

1. Dependencias ya instaladas con pnpm install en el workspace

   Si lo levantás aislado:

   pnpm --dir sevastopol install

2. Configurar el endpoint del Orchestrator

   cp sevastopol/.env.example sevastopol/.env
   # PUBLIC_API_URL=http://localhost:8000

3. Iniciar en desarrollo

   pnpm --dir sevastopol dev
   # o desde la raíz del workspace:
   pnpm dev:sevastopol

   La SPA queda disponible en http://localhost:4321.

---

Nostromo (ETL Python)

Los loaders viven en accounting_system/. Cargan parámetros (UF, USD, EUR, AFP, IUSC) y datos del SII hacia Mother. No corren como daemon: se ejecutan bajo demanda.

1. Crear entorno virtual e instalar dependencias

   Linux / macOS

   cd accounting_system
   python -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt

   Windows (PowerShell)

   cd accounting_system
   python -m venv .venv
   .venv\Scripts\Activate.ps1
   pip install -r requirements.txt

2. Configurar credenciales hacia Mother

   cp .env.example .env
   # PGHOST, PGPORT, PGUSER, PGPASSWORD, PGDATABASE=nostromo_common

3. Ejecutar una carga de prueba (dry-run)

   python bc_loader.py -fi 2026-01-01 -fn 2026-01-31 -m UF -dryrun

El catálogo completo de loaders, flags y ejemplos vive en ETL Scripts.

---

Jean d’Arc (Documentación)

1. Activar corepack y pnpm

   corepack enable
   corepack prepare pnpm@latest --activate

2. Instalar dependencias

   cd jean_d_arc
   pnpm install

3. Iniciar el servidor de desarrollo

   pnpm run dev

   La documentación queda disponible en http://localhost:4322.

4. Build para producción

   pnpm run build
   pnpm run preview

Caution

No usar npm en jean_d_arc/. El package-lock.json no se mantiene y las restricciones de pnpm-workspace.yaml solo se aplican con pnpm.

---

Tabla de Puertos

Componente	URL	Verificación
Orchestrator	http://localhost:8000/health	Retorna {"status":"ok"}
Sevastopol	http://localhost:4321	Muestra la página de login
Jean d’Arc	http://localhost:4322	Muestra la home de la documentación
PostgreSQL	localhost:5432	pg_isready -h localhost -p 5432

---

Flujo de Trabajo Diario

Una sesión típica de desarrollo requiere tener corriendo:

1. PostgreSQL como servicio de sistema o contenedor.
2. Orchestrator con pnpm --dir orchestrator dev (puerto 8000).
3. Sevastopol con pnpm --dir sevastopol dev (puerto 4321).
4. Jean d’Arc con pnpm run dev (puerto 4322) solo si se está editando documentación.

El ETL accounting_system/ se ejecuta bajo demanda cuando hace falta refrescar parámetros del Banco Central, Previred o SII; no es parte del loop de desarrollo continuo.

---

Troubleshooting

Puerto ocupado

Windows

netstat -ano | findstr :8000
# Identificar PID y cerrar el proceso si corresponde
taskkill /F /PID <pid>

Linux / macOS

lsof -i :8000
kill -9 <pid>

Error de conexión a PostgreSQL

pg_isready -h localhost -p 5432
# Si falla: revisar el servicio postgres y las credenciales en .env

Tenant no resuelto al loguear

Verificar que el usuario en nostromo_command.users tenga tenant_db apuntando a una base existente (ej. nostromo_60004317). Sin ese vínculo, el resolver de tenant devuelve 403 Forbidden.

CORS bloquea peticiones desde Sevastopol

El Orchestrator solo acepta orígenes listados en CORS_ORIGINS. Para desarrollo local debe incluir http://localhost:4321 (Sevastopol) y http://localhost:4322 (Jean d’Arc si consume la API).

Migraciones / template desactualizado

Si al crear un tenant nuevo faltan tablas, regenerar accunting_template:

DROP DATABASE accunting_template;
CREATE DATABASE accunting_template;
\c accunting_template
\i orchestrator/sql/template/init.sql

Luego recrear los tenants existentes que necesiten la versión actualizada.