Plataforma Enterprise de Preservación Cultural Digital para el Pueblo Indígena Misak (Guambiano) de Colombia.
Sistema de diccionario bilingüe Namtrik-Español diseñado con Clean Architecture, React 19, Fastify 5, PostgreSQL 18 y un sistema de validación comunitaria.
Note
Este repositorio público contiene la documentación técnica oficial, especificaciones de arquitectura, ADRs (Architecture Decision Records), guías de desarrollo y contratos de API del proyecto Diccionario Cultural Misak. El código fuente de la aplicación se mantiene en un repositorio privado por razones de protección de propiedad intelectual y salvaguarda del patrimonio cultural digital.
🖥️ Interfaz Principal y Plataforma Educativa Namtrik
- 📖 Descripción General y Misión
- 🛡️ Pilares del Sistema
- 🛠️ Stack Tecnológico
- 🏗️ Arquitectura del Monorepo
- 📊 Cobertura y Métricas de Calidad
- 🌐 Resumen de la API RESTful
- 🚦 Fases del proyecto y Roadmap
- 📚 Índice Completo de Documentación
- 📄 Licencia
El Pueblo Misak (Guambiano) habita principalmente en el departamento del Cauca, Colombia. Su lengua materna, el Namtrik (Namuiwam), representa la piedra angular de su cosmovisión, memoria ancestral y organización territorial.
El Diccionario Cultural Misak es una plataforma pionera diseñada para la salvaguarda digital de la lengua y cultura Misak mediante tecnología web enterprise:
- Diccionario Bilingüe Interactivo: Consulta léxica Namtrik - Español con pronunciación en audio, ejemplos de uso y taxonomía lingüística.
- Jerarquía Semántica Territorial: Clasificación de conceptos ligada al territorio (Campos Semánticos, Subcampos y Microcampos).
- Storytelling Inmersivo: Narrativas interactivas con animaciones sincronizadas al scroll (scrollytelling) que integran contexto histórico y cultural.
- PWA Offline-First: Acceso asegurado en zonas rurales de baja conectividad mediante Service Workers y Workbox.
- Validación Comunitaria: Contenidos supervisados y avalados por las autoridades del Cabildo Indígena del Resguardo de Guambía.
- Framework: React 19.2 + Vite 7.2 + TypeScript 5.9 + TailwindCSS 4.1
- PWA: Soporte offline completo con
vite-plugin-pwa(66 KB gzipped total bundle size). - Animaciones: Framer Motion 12 para transiciones culturales fluidas.
- Calidad: 175 tests automatizados con Vitest (98.78% coverage).
- Framework: Fastify 5.6 + Prisma 7.0 + PostgreSQL 18.1
- Patrón: Clean Architecture (Domain, Application, Infrastructure, Presentation) + DDD.
- Seguridad: Autenticación JWT (access 15m + refresh 7d) con Bcrypt y RBAC de 5 roles.
- Calidad: 246 tests automatizados con Vitest (threshold de cobertura 80%).
- Proceso formal de revisión de término por el comité lingüístico (
cultural_reviewer). - Trazabilidad y auditoría completa de modificaciones de términos (Event Sourcing audit patterns).
| Dominio | Tecnología | Versión | Propósito |
|---|---|---|---|
| Runtime | Node.js | 24.15.0 LTS |
Entorno de ejecución servidor y tooling |
| Package Manager | pnpm | 10.20.0 |
Gestión monorepo y workspaces ultrarrápidos |
| Linter / Formatter | Biome | v2.4+ |
Toolchain unificada de análisis de código |
| Frontend Framework | React | 19.2 |
Interfaz declarativa de usuario |
| Build Tool | Vite | 7.2 |
Bundle y dev server ultrarrápido |
| Styles | TailwindCSS | 4.1 |
Motor de utilidades CSS |
| Backend Framework | Fastify | 5.6 |
HTTP server de alto rendimiento y bajo overhead |
| ORM | Prisma | 7.0 |
Mapeo objeto-relacional y migraciones tipadas |
| Database | PostgreSQL | 18.1 |
Base de datos relacional con extensiones citext, pg_trgm, pgvector |
| Testing | Vitest | 4.0 |
Suite de pruebas unitarias e integración |
| CI/CD | GitHub Actions | Standard | Pipelines automáticos de Test, Lint y Build |
misak-dictionary/
├── apps/
│ ├── web-client/ # Client PWA React 19 + Vite 7 (175 tests)
│ │ ├── src/ # UI components, layout, sections, hooks
│ │ └── docs/ # Documentación del cliente
│ ├── backend-service/ # REST API Fastify 5 + Prisma 7 (246 tests)
│ │ ├── src/ # Clean Arch: domain, application, infrastructure, presentation
│ │ └── prisma/ # Migraciones y esquema PostgreSQL
│ └── prototypes/ # Prototipos interactivos de laboratorio
├── packages/
│ └── shared-types/ # Contratos de TypeScript compartidos entre Frontend y Backend
├── docs/ # Especificaciones maestras y guías
├── scripts/ # Scripts de automatización y verificación pnpm
└── biome.json # Configuración global de formateo y linting
| Proyecto / App | Tests Pasar | Test Files | Cobertura | Build Size / Metrics |
|---|---|---|---|---|
Frontend (web-client) |
175 / 175 (100%) | 16 archivos | 98.78% | 66.37 KB (gzipped bundle) |
Backend (backend-service) |
246 / 246 (100%) | 24 archivos | > 80.0% | 27 endpoints (12 públicos, 12 CRUD admin, 3 auth) |
| Total Ecosistema | 421 tests | 40 archivos | High Baseline | Zero-leak linting con Biome v2 |
El backend expone 27 endpoints estructurados en dos bloques:
-
API Pública Diccionario (12 endpoints):
GET /api/v1/dictionary/words— Búsqueda paginada y filtrado por idioma (Namtrik / Español).GET /api/v1/dictionary/words/:id— Detalle completo de palabra con multimedia y fonética.GET /api/v1/dictionary/categories— Jerarquía semántica de campos culturales.GET /api/v1/dictionary/search— Búsqueda full-text trigram.
-
API Administrativa & Auth (15 endpoints):
POST /api/v1/auth/login— Autenticación JWT de administradores.POST /api/v1/auth/refresh— Renovación de access token.POST /api/v1/auth/logout— Revocación de sesión.POST/PUT/DELETE /api/v1/admin/words— Gestión CRUD protegida por roles (super_admin,content_admin,cultural_reviewer).
- Fase 1: Fundación Enterprise (v0.1.0 - v0.4.0) ✅
- Setup de Monorepo modular pnpm workspaces.
- Implementación del Web Client React 19 con PWA y 175 tests (98.78% coverage).
- Implementación del Backend Service Fastify 5 con Prisma 7 y 246 tests.
- Migración exitosa de linters a Biome v2.4.
- Fase 2: Motor Semántico & Multimedia (Q3 2026) 🔄
- Motor de búsqueda con Vector Embeddings / ElasticSearch para búsqueda conceptual.
- Integración de CDN multimedia Cloudinary para clips fonéticos de audio.
- Panel Admin avanzado con workflow de aprobación de 3 pasos.
- Fase 3: Innovación Territorial & Móvil (Q4 2026) 📅
- Mapas interactivos 3D del territorio Guambía vinculados al léxico.
- Lanzamiento de App Móvil nativa con React Native / Expo.
Para explorar en detalle la arquitectura y guías del proyecto, ingresa a la carpeta docs/:
- 📖 Visión General del Proyecto — Objetivos culturales y alcance.
- 🛠️ Stack Tecnológico — Especificación de librerías y componentes.
- 🚀 Roadmap de Desarrollo — Hitos y entregables por fases.
- 📐 Monorepo & Workspaces — Configuración y comandos pnpm.
- ⚙️ Backend Clean Architecture — Capas DDD y patrones.
- 🎨 Frontend Architecture — Diseño atómico y estado.
- 🗄️ Esquema de Base de Datos — Diagrama relacional y migraciones Prisma.
- 📖 Índice de API — Overview de comunicación HTTP.
- 🔓 Endpoints Públicos — Diccionario y búsquedas.
- 🔐 Endpoints Autenticados & RBAC — Autenticación y administración.
- 📝 ADR-001: Adopción de Monorepo con pnpm Workspaces
- 📝 ADR-002: Implementación de Clean Architecture en Backend
- 📝 ADR-003: Selección de PostgreSQL 18 + Prisma 7
- 📝 ADR-004: Migración de Tooling a Biome v2
- 📝 ADR-005: Modelo de Gobernanza y Validación Cultural
- 🟢 Setup de Desarrollo Local
- 🧪 Estrategia de Testing & Calidad
- 🏛️ Proceso de Validación con Cabildo Misak
- 🔄 Pipelines CI/CD GitHub Actions
- ☁️ Estrategia de Despliegue
Este proyecto está bajo la Licencia MIT. Consulta el archivo LICENSE para obtener más detalles.
Desarrollado con ❤️ para la preservación del patrimonio lingüístico del Pueblo Indígena Misak.