Plataforma técnica

Lado Desarrollador

Desarrollo

Esta landing es el recorrido recomendado para desarrolladores que entran al ecosistema Nostromo. Prioriza arquitectura, contratos técnicos, servicios, endpoints y componentes. La lectura contable queda enlazada cuando aporta contexto de dominio.

El objetivo es que un desarrollador pueda ubicar rápidamente la capa donde vive una funcionalidad, el contrato que la expone y el dominio contable que la motiva. La organización del sidebar agrupa la documentación en cuatro bloques: Arquitectura (visión transversal y modelo de Mother), Sistema (Orchestrator y Sevastopol), Datos y ETL (Nostromo) y Seguridad. Las páginas de introducción técnica —convenciones, setup local y glosario— viven en la raíz del lado dev.

Propósito

El Lado Desarrollador organiza la documentación que permite construir, mantener y depurar el sistema desde una perspectiva técnica. Cada bloque del sidebar describe una vista del stack: la arquitectura que lo sostiene, los dos componentes operacionales que ejecutan el dominio, las cargas masivas que lo alimentan y la capa de seguridad que lo protege.

Esta entrada no reemplaza las páginas específicas. Funciona como un mapa para decidir dónde buscar según la pregunta: arquitectura general, patrón de diseño, contrato HTTP, lógica de dominio, modelo de datos, carga ETL, componente de UI, política de seguridad o convención de código.

Cómo Leer esta Documentación

Partir por el bloque que origina la pregunta: arquitectura transversal, sistema (backend o frontend), datos/ETL o seguridad.
Revisar la arquitectura del componente involucrado: capas, dependencias y patrones (DDD, Hybrid Core, Islands, multi-tenant). Los patrones recurrentes viven en /dev/arquitectura/patrones-de-diseno/.
Identificar el contrato relevante: endpoint REST, función de servicio, vista SQL, componente Solid o script ETL.
Contrastar con el dominio contable cuando el contrato refleje una regla de negocio (remuneraciones, activo fijo, operaciones SII, declaraciones).
Validar convenciones transversales: nomenclatura, manejo de errores, autenticación, multi-tenant, testing.
Saltar a la documentación contable solo cuando se necesite criterio de reconocimiento, norma IFRS o tratamiento tributario.

Mapa del Stack Técnico

flowchart LR
  subgraph FUENTES["Fuentes externas"]
    SII[SII]
    BC[Banco Central]
    PRE[Previred]
  end
  subgraph NOS["Nostromo (Python · ETL)"]
    LOAD[Loaders + cargas masivas]
  end
  subgraph MOM["Mother (PostgreSQL 16)"]
    COM[(nostromo_common)]
    CMD[(nostromo_command)]
    TEN[(tenants por empresa)]
  end
  subgraph ORC["Orchestrator (Node · Express · TS)"]
    DOM[Domain · Services · Engines]
    REP[Repositories]
    API[Routes /api/*]
  end
  subgraph SEV["Sevastopol (Astro · SolidJS)"]
    MID[Middleware SSR]
    ISL[Islands reactivas]
    UI[UI components]
  end
  BR[Navegador del usuario]

  SII --> LOAD
  BC --> LOAD
  PRE --> LOAD
  LOAD --> COM
  LOAD --> TEN
  COM --> REP
  CMD --> REP
  TEN --> REP
  REP --> DOM
  DOM --> API
  API --> MID
  MID --> ISL
  ISL --> UI
  UI --> BR

Capas del Stack

Capa	Tecnología	Responsabilidad	Documentación
Arquitectura	Transversal	Visión integral, hexagonal, patrones de diseño y modelo Mother.	Arquitectura
ETL	Python	Carga masiva de parámetros, indicadores y datos del SII.	Nostromo
Persistencia	PostgreSQL 16	Multi-tenant: `nostromo_common`, `nostromo_command` y bases por empresa.	Mother
Backend	Node.js · Express · TypeScript	Dominio, servicios, engines, repositorios y API REST.	Orchestrator
Frontend	Astro · SolidJS · Tailwind	SSR shell, islands reactivas, hooks, middleware y UI.	Sevastopol
Seguridad	JWT · RBAC · helmet · CORS	Autenticación, autorización, aislamiento de tenant y headers.	Seguridad

Convenciones Transversales

Para cualquier cambio técnico, la implementación debe poder responder:

qué componente del stack es responsable del cambio;
qué contrato externo (HTTP, SQL, módulo) se modifica;
cómo se autentica y a qué tenant pertenece la operación;
qué capa de testing cubre el cambio (unit, integration, e2e);
qué convención de nomenclatura aplica en cada borde (TypeScript camelCase, PostgreSQL snake_case, API snake_case);
qué documento contable o tributario sustenta la regla cuando aplica;
qué evidencia queda en logs, registros o vistas para reconstruir el flujo.