SDOC Platform

Un nuevo formato de archivo abierto para documentos vivos.

.sdoc es a .pdf lo que .pdf fue a .ps: el siguiente paso.
Colaborativo, offline-first, firmable, cifrable y siempre portable.

Spec del formato · Documentación · Roadmap · Reportar bug

---

🤖 ¿Eres una IA / asistente de código?

Antes de tocar una sola línea, lee en este orden:

1. AGENTS.md — contrato no negociable para IA.
2. SPEC.md — única fuente de verdad (7700+ líneas).
3. docs/PROJECT_OVERVIEW.md — estado actual del código vs. spec.
4. docs/FORMAT_SPEC_INDEX.md — índice rápido del formato .sdoc.
5. docs/AI_TASK_PROTOCOL.md — protocolo de cambios.

No improvises. No asumas. Pregunta cuando dudes. Sin menciones a IA en código ni commits.

---

Qué es SDOC

SDOC NO es un editor. Es un formato de archivo abierto (.sdoc) — un ZIP+JSON con estructura estricta que incluye, dentro del propio archivo:

• Contenido estructurado (texto, imágenes, tablas, código, embeds).
• Historial completo de versiones.
• ACL (permisos) embebida.
• Estado CRDT (Yjs) para sincronización offline-first.
• Firma criptográfica (Ed25519) y metadatos de cifrado (AES-256-GCM).
• Preview universal (thumbnail + HTML auto-contenido).

Este repositorio contiene:

Pieza	Estado
Especificación del formato .sdoc	SPEC.md §6
Plataforma de referencia (8 microservicios Java + render-service Python)	services/
Editor web de referencia (React 18 + TipTap + Yjs)	apps/web/
Librerías TS para leer/escribir .sdoc	packages/sdoc-format/ (en progreso)
Infraestructura (Docker, K8s, Helm, Vault, Keycloak, Kafka)	infrastructure/

---

Por qué .sdoc

Vive en un solo archivo	Cualquier .sdoc lleva dentro su historial, sus assets, sus permisos y su firma. Portable y soberano.
Colaboración nativa	El archivo contiene el estado CRDT (Yjs). Cualquier app que entienda la spec puede seguir editando colaborativamente.
Offline-first real	No depende de un servidor para existir. El servidor es solo un peer más en la red CRDT.
Export fiel	PDF, DOCX, HTML, EPUB. Plantillas para informes ejecutivos, tesis y publicaciones.
Seguridad bancaria	AES-256-GCM + HKDF-SHA256 para cifrado, Ed25519 para firma, OPA para permisos finos.
Abierto	ZIP + JSON. Cualquiera puede inspeccionarlo, validarlo, implementarlo. Licencia MIT.

---

Trabajar con archivos .sdoc en código

import { createSdoc, serializeSdoc, parseSdoc } from "@sdoc/format";

// Crear un .sdoc nuevo
const file = await createSdoc({
  title: "Mi documento",
  owner: { id: "usr_01HXYZ..." },
});

// Serializar a bytes (listo para descargar / guardar)
const bytes = await serializeSdoc(file);

// Leer un .sdoc desde disco
const parsed = await parseSdoc(bytes);
console.log(parsed.manifest.title);

Firma Ed25519, cifrado AES-256-GCM, validación de schemas, CLI: ver packages/sdoc-format/README.md.

Tres archivos .sdoc de ejemplo (simple, firmado, cifrado) listos para probar en packages/sdoc-format/examples/.

Mostrar un .sdoc en cualquier web

import { mountSdocViewer } from "@sdoc/viewer";
import "@sdoc/viewer/style.css";

const bytes = await fetch("/api/v1/documents/abc/download.sdoc")
  .then((r) => r.arrayBuffer());

await mountSdocViewer(document.getElementById("viewer")!, {
  source: new Uint8Array(bytes),
  verifySignature: true,
});

El viewer es vanilla (sin React/Vue), verifica la firma Ed25519, soporta dark mode, escapa contenido por XSS-safety. Ver packages/sdoc-viewer/README.md.

---

Empezar en 30 segundos

Opción 1 — Frontend en modo demo (sin backend)

git clone https://github.com/metatech-programmer/sdoc.git
cd sdoc
npm install --workspaces --include-workspace-root
npm run dev -w apps/web

Abre http://localhost:3000. El editor detecta que no hay backend y activa modo demo con documentos seed. Cero configuración.

Opción 2 — Stack mínimo con Docker

docker compose -f docker-compose.demo.yml up -d

Web + Postgres + Redis arriba en ~60 segundos.

Opción 3 — Plataforma completa (microservicios)

Ver GETTING-STARTED.md para el stack completo con 8 microservicios + Kafka + Keycloak + Vault.

---

Desplegar gratis

SDOC se despliega en pocos minutos con planes gratuitos:

• Vercel (frontend) — un comando, HTTPS automático.
• Render (API) — free tier con auto-deploy desde Git.
• Neon (Postgres) — 0.5 GB gratis, sin tarjeta.
• Upstash (Redis) — 10 K comandos/día gratis.

vercel --prod

Guía completa en DEPLOY.md.

---

Stack

Frontend	Backend	Datos	Infraestructura
React 18 · TypeScript Vite 5 · PWA TipTap (ProseMirror) Yjs CRDT colaboración Zustand · TanStack Query IndexedDB offline	Spring Boot 3.3 (Java 21) Spring Cloud Gateway 8 microservicios + Python render FastAPI · Celery WeasyPrint (PDF) Keycloak (SSO)	PostgreSQL 16 Redis 7.2 Kafka 3.7 (Avro) MinIO / S3 Vault (secretos)	Docker · Kubernetes Helm + ArgoCD OpenTelemetry · Jaeger Grafana · Prometheus KEDA (autoscaling)

Arquitectura completa en SPEC.md §3.

---

Capturas

Las capturas viven en docs/screenshots/. Para generarlas localmente:

npm run dev -w apps/web
# Abre http://localhost:3000 y captura las vistas que quieras compartir.

---

Roadmap

Roadmap completo en SPEC.md §21. Estado actual sintetizado en docs/PROJECT_OVERVIEW.md.

• Microservicios core (auth, document, sync, asset, version, notification, render)
• API Gateway con JWT, rate limit, idempotency
• Editor de referencia (React + TipTap + Yjs)
• Exportación PDF / DOCX / HTML
• PWA · Offline-first · Dark mode
• @sdoc/format: librería TS read/write/validate del formato .sdoc real
• JSON Schemas oficiales (manifest, document, acl, signature, encryption-meta)
• Crypto: Ed25519 firma + AES-256-GCM + HKDF-SHA256 + PBKDF2 (Web Crypto nativo)
• CLI sdoc: init, info, validate, extract, pack, sign, verify, keygen
• Import/export .sdoc desde el editor web (botones "Abrir / Descargar .sdoc")
• CRDT round-trip dentro del .sdoc: el estado Yjs viaja con el archivo
• Backend: GET /documents/{id}/download.sdoc (Java + canonical JSON)
• @sdoc/viewer: viewer read-only embebible, sin framework
• Ejemplos .sdoc reales (simple, firmado, cifrado)
• Publicar @sdoc/format y @sdoc/viewer en npm
• Sitio público de la spec (GitHub Pages)
• Firma Ed25519 automática del .sdoc desde backend (Vault)
• App móvil
• Marketplace de plantillas

---

Contribuir

Toda contribución es bienvenida. Lee CONTRIBUTING.md para empezar.

Cosas en las que se puede ayudar:

• Traducir SDOC a otros idiomas
• Implementar piezas del formato (packages/sdoc-format)
• Crear plantillas
• Mejorar la documentación
• Reportar bugs
• Proponer features

---

Licencia

MIT — usa SDOC para lo que quieras, comercial o personal.

---

Autor

Creado y mantenido por Santiago Aguilar — @metatech-programmer.

Hecho con cariño en Medellín, Colombia.

---

Construido sobre los hombros de gigantes: TipTap · Yjs · Spring · React · Vite.

Si SDOC te resulta útil, dale ⭐ al repo.