Especificación Técnica

OPSV Dashboard v2.0
Plan de Arquitectura

Documento de referencia para el desarrollo con Claude Code. Define stack tecnológico, estructura de base de datos, roles de usuario y fases de desarrollo.

Versión 2.0 Fecha Abril 2026 Stack React + Supabase + Vercel Modalidad Solo developer · Claude Code
1

Decisiones de arquitectura

⚛️

Frontend

React + Vite — mismo entorno que usaste en el dashboard anterior. Claude Code lo maneja perfectamente.

React 18 + Vite 5
🗄️

Backend + Auth

Supabase: base de datos PostgreSQL, autenticación email/password, storage para los CSV. Todo gratuito.

Supabase Free Tier
🚀

Hosting

Vercel: deploy automático desde GitHub, HTTPS incluido, dominio gratuito bajo vercel.app.

Vercel Hobby (gratis)
🎨

UI + Gráficos

Tailwind CSS para estilos. Recharts para visualizaciones (mismo que ya usás). Lucide para iconos.

Tailwind + Recharts
¿Por qué no GitHub Pages? GitHub Pages es estático puro — no puede manejar autenticación ni guardar datos. Vercel sí, y también es 100% gratuito con deploy automático cada vez que hacés push.
2

Stack tecnológico completo

Capa Tecnología Para qué sirve Costo
UI Framework React 18 + Vite Interfaz del dashboard y panel admin
Familiar para Claude Code, ecosistema enorme
 Gratis
Estilos Tailwind CSS v3 Diseño responsivo, paleta institucional OPSV
Claude Code genera Tailwind excelente
 Gratis
Gráficos Recharts Todos los gráficos del dashboard actual
Mismo que el dashboard anterior → migración directa
 Gratis
Base de datos Supabase PostgreSQL Config del dashboard, textos editables, roles, metadatos de CSV
500MB gratis, más que suficiente para configuración
 Gratis
Autenticación Supabase Auth Login email/contraseña con roles (superadmin, admin, editor)
Email confirmado + recupero de contraseña incluidos
 Gratis
Storage CSV Supabase Storage Almacenamiento de los 3 archivos CSV mensuales
1GB gratis, historial de versiones posible
 Gratis
Hosting Vercel Publicación del sitio, deploy automático desde GitHub
Cada push = nueva versión publicada en segundos
 Gratis
Repositorio GitHub Control de versiones, integración con Vercel
Todo el código centralizado, historial completo
 Gratis
3

Diagrama de arquitectura

USUARIOS FRONTEND · VERCEL BACKEND · SUPABASE 👤 Usuario Público Sin login requerido Acceso al dashboard 🔐 Administrador Login email/password superadmin | admin editor Dashboard Público / · sin autenticación React + Recharts Panel Admin /admin · ruta protegida Upload CSV · Editar textos React Router + Auth guard Login / Auth /login · email + password GitHub Repository Push → Vercel auto-deploy Variables de entorno Supabase en Vercel (VITE_SUPABASE_URL) Supabase Auth JWT · Roles · Email confirm user_roles table PostgreSQL DB dashboard_config user_roles · datasets Textos · Chart config Row Level Security Supabase Storage siniestros.csv personas.csv · involucrados.csv REST API SDK Client Free tier · 500MB DB + 1GB Storage Respaldo automático · SSL incluido
4

Roles de usuario y permisos

Rol Ver dashboard Subir CSV Editar textos/resumen Config gráficos Gestionar usuarios Acceso
Superadmin ✓ ✓ ✓ ✓ ✓ Crear/borrar admins Login requerido
Admin ✓ ✓ ✓ ✓ ✗ Login requerido
Editor ✓ ✗ ✓ Solo textos ✗ ✗ Login requerido
Público ✓ Solo lectura ✗ ✗ ✗ ✗ Sin login · acceso libre
5

Esquema de base de datos (Supabase)

user_roles
  • iduuid PK
  • user_iduuid FK auth
  • roleenum
  • created_attimestamp
datasets
  • iduuid PK
  • typetext
  • yearinteger
  • monthinteger
  • storage_pathtext
  • uploaded_byuuid FK
  • created_attimestamp
dashboard_config
  • iduuid PK
  • keytext unique
  • valuejsonb
  • updated_byuuid FK
  • updated_attimestamp
resumen_content
  • iduuid PK
  • yearinteger
  • monthinteger
  • titletext
  • bodytext (md)
  • publishedboolean
  • created_byuuid FK
chart_config
  • iduuid PK
  • chart_keytext unique
  • titletext
  • chart_typeenum
  • color_palettejsonb
  • visibleboolean
  • updated_attimestamp
Row Level Security (RLS) — Supabase protege cada tabla con políticas: el público solo puede leer, los admins pueden escribir. Esto se configura una vez con SQL y funciona automáticamente.
6

Estructura del proyecto

opsv-dashboard/ ├── src/ │ ├── components/ # Componentes reutilizables │ │ ├── charts/ # BarChart, LineChart, etc. │ │ ├── ui/ # Button, Card, Modal, Input │ │ └── layout/ # Navbar, Sidebar, Footer │ │ │ ├── pages/ # Páginas / rutas │ │ ├── Dashboard.jsx # / → público │ │ ├── Login.jsx # /login │ │ └── admin/ │ │ ├── AdminPanel.jsx # /admin → panel principal │ │ ├── UploadCSV.jsx # /admin/upload │ │ ├── EditResumen.jsx # /admin/resumen │ │ ├── EditCharts.jsx # /admin/charts │ │ └── ManageUsers.jsx # /admin/users (superadmin) │ │ │ ├── hooks/ # Custom hooks │ │ ├── useAuth.js # Estado de sesión Supabase │ │ ├── useCSVData.js # Carga y parseo de CSV │ │ └── useDashConfig.js # Config editable desde DB │ │ │ ├── lib/ │ │ └── supabase.js # Cliente Supabase (1 línea) │ │ │ ├── utils/ │ │ └── parseCSV.js # Lógica de procesamiento CSV │ │ │ └── App.jsx # Rutas + Auth provider │ ├── .env.local # VITE_SUPABASE_URL + ANON_KEY (no subir a GitHub) ├── .env.example # Template sin valores reales (sí subir) ├── vercel.json # Configuración de Vercel (SPA redirect) ├── tailwind.config.js # Paleta institucional OPSV #252C61 └── vite.config.js
7

Fases de desarrollo

Fase 1 2–3 sem

Fundación del proyecto

  • Crear proyecto en Supabase (auth + storage + DB)
  • Scaffold React + Vite con Tailwind y paleta OPSV
  • Sistema de autenticación: login, logout, sesión persistente
  • Ruta protegida /admin con auth guard
  • Conectar Vercel ↔ GitHub (deploy automático)
Sitio online vacío con login funcional y deploy automático
Fase
2
3–4 sem

Dashboard público

  • Upload manual de los 3 CSV desde panel admin
  • Parser CSV en el cliente (Papa Parse)
  • Migrar todos los gráficos actuales (Recharts)
  • Filtros por año y mes funcionales
  • Sección Resumen con contenido desde DB
  • Diseño responsivo institucional
Dashboard público funcional idéntico al actual, pero con datos dinámicos
Fase
3
3–4 sem

Panel administrador

  • Subida de CSV mensuales (3 archivos a la vez)
  • Editor de texto enriquecido para sección Resumen
  • Editor de títulos y configuración de gráficos
  • Selector de tipo de gráfico (barra/línea/área) por visualización
  • Selector de colores con paleta institucional
  • Vista previa antes de publicar
Panel admin completo con edición en tiempo real y previsualización
Fase
4
2–3 sem

Escalabilidad y pulido

  • Gestión de múltiples usuarios con roles (admin, editor)
  • Historial de versiones de CSV por mes/año
  • Exportación PDF desde el panel admin
  • Notificaciones de carga exitosa / errores
  • Pruebas finales y documentación básica
Sistema production-ready con multi-usuario y gestión de versiones
Estimación realista para una persona con Claude Code: Fases 1 + 2 son las más importantes y deberían estar listas en ~6 semanas trabajando 2–3 horas/día. Las fases 3 y 4 pueden ir en paralelo con el uso real del sistema.