cis-docs · Documentación técnica del ecosistema CIS¶

Hub Markdown con runbooks, integraciones y decisiones arquitectónicas (ADRs) del ecosistema Compañía de Innovación de Santiago SpA (CIS).

Estado: 🟡 staging · markdown plano · static site generator pendiente decisión humana. Source code repo: /srv/projects/cis/cis-docs/. Hosting target: docs.innovacionsantiago.cl (pendiente — el subdominio actual está repurposed como redirect a admin.innovacionsantiago.cl/documentos, ver infra/caddy/docs.innovacionsantiago.cl.caddy).

Tabla de contenidos¶

`integrations/` — APIs externas¶

Cómo y dónde se conectan los servicios CIS con APIs y proveedores externos.

Integración	Service	Documento
SII Chile (Servicio de Impuestos Internos)	`cis-sii-gateway`	`integrations/sii.md`
Resend (transactional email)	`cis-mailer`	TBD — ver runbook
Authentik (OIDC)	`cis-auth`	TBD — ver runbook
Cloudflare DNS	infra	TBD
Flow.cl (pagos CLP)	`cis-platform`	TBD — ver ADR-009
Google APIs (Gmail/Calendar/Drive)	`cis-claudia`, `cis-inbox`	TBD — ver ADR-017
WhatsApp Business	`cis-claudia`	TBD

`runbooks/` — Operación diaria¶

Cómo arrancar/parar/restartear, ver logs, healthz, secretos, gotchas — un archivo por servicio CIS. Índice completo en runbooks/INDEX.md.

Servicio	Stack	Runbook
`cis-admin`	Vite+React + FastAPI	`runbooks/cis-admin.md`
`cis-auth`	Authentik (Docker)	`runbooks/cis-auth.md`
`cis-claudia`	FastAPI + Claude Code CLI subprocess	`runbooks/cis-claudia.md`
`cis-core`	FastAPI + vault propio	`runbooks/cis-core.md`
`cis-inbox`	FastAPI + Next.js + IMAP	`runbooks/cis-inbox.md`
`cis-isometrico`	Vite + Three.js + Python	`runbooks/cis-isometrico.md`
`cis-mailer`	FastAPI + Resend	`runbooks/cis-mailer.md`
`cis-mando`	FastAPI dashboard	`runbooks/cis-mando.md`
`cis-monitoreo`	FastAPI + APScheduler	`runbooks/cis-monitoreo.md`
`cis-platform`	FastAPI gateway	`runbooks/cis-platform.md`
`cis-sign`	FastAPI + cryptography	`runbooks/cis-sign.md`
`cis-sii-gateway`	FastAPI + Playwright	`runbooks/cis-sii-gateway.md`
`cis-www`	Vite + React	`runbooks/cis-www.md`

`adrs/` — Decisiones arquitectónicas¶

Mirror read-only del log monolítico /srv/projects/cis/cis-plan/DECISIONS.md splitteado en 33 archivos individuales (ADR-001 → ADR-033). Modificaciones canónicas siempre en cis-plan; estos archivos se re-generan con tools/split_adrs.py.

Índice completo: adrs/INDEX.md.

Highlights:

ADR-008 · Sudo como Firma Electrónica Simple (FES)
ADR-010 · cis-admin rewrite frontend a Vite+React+TS
ADR-011 · Contabilidad in-house
ADR-012 · Service-to-service auth · shared-key
ADR-014 · Consolidación user model · Google-primary + OTP fallback
ADR-022 · Marketplace lifecycle (internal → preview → beta → public)
ADR-026 · Operations permission model (Claude-judged auto vs FES-gated)
ADR-029 · Claudia + Claude Code CLI subprocess (Draft)
ADR-032 · cis-sii-monitor → módulo tributario en cis-admin
ADR-033 · DR backup + offsite (RTO 1h / RPO 24h)

Otros recursos del ecosistema¶

Plan maestro y backlog: /srv/projects/cis/cis-plan/
Contratos vivos (proveedor ↔ consumidor): /srv/projects/cis/CONTRACTS.md
Estructura del repo CIS: /srv/projects/cis/STRUCTURE.md
Manual del servidor: /srv/projects/a
Glosario: /srv/projects/cis/GLOSSARY.md
Status snapshot: /srv/projects/cis/STATUS.md

Pendientes¶

Static site generator: decidir entre mkdocs-material, docusaurus, vitepress, hugo o seguir con Markdown plano + tree. La SPA Vite+React preexistente en frontend/ es para una vista de documentos legales (módulo legacy), no para esta documentación técnica. Ver MKDOCS-FUTURE.md cuando exista.
Hosting: registrar docs.innovacionsantiago.cl apuntando al output del SSG. El subdominio actual hace 301 redirect a admin.innovacionsantiago.cl/documentos por la consolidación de cis-docs (legal docs) en cis-admin (ADR-010 Fase C+E). Si vamos a usar el mismo subdominio para esto, hay que retirar el redirect Caddy y reasignar.
Auto-split de ADRs: el script tools/split_adrs.py (o equivalente bajo cis-docs/) puede correr como pre-commit o GH Action contra cis-plan/DECISIONS.md para mantener adrs/ sincronizado.
Integraciones pendientes: documentar Resend, Authentik, Cloudflare, Flow.cl, Google APIs, WhatsApp Business como hacemos con SII.

Convenciones¶

Markdown puro (CommonMark). NO HTML inline si se puede evitar (compatibilidad SSGs).
Encoding: UTF-8.
Idioma: castellano para narrativa, inglés solo para nombres técnicos / endpoints / código.
Frontmatter: opcional; muchos archivos lo omiten. Si existe, campos sugeridos: title, owner, status, last_review.
Links a archivos de otros repos: usar paths absolutos /srv/projects/... o relativos al docs root cuando estamos dentro de cis-docs.
No commitear secretos, .env, *.pem, *.key. Ver .gitignore.