AIwareness

Proyecto global de Global Shapers para concienciar sobre contenido generado por IA. Fase 1: reconocimiento rápido (imagen real vs. IA). Fase 2: formación con explicaciones localizadas por hub.

Estructura del repositorio

aiwareness/
├── app/                     # Next.js App Router
│   ├── page.tsx              # Onboarding: año nacimiento + hub/país
│   ├── phase1/page.tsx       # Modo simple/nativo digital
│   ├── results/page.tsx      # Resumen de aciertos + compartir estilo Wordle
│   └── phase2/page.tsx       # Módulo formativo
├── components/
│   ├── HubPicker.tsx          # Selector de hub con búsqueda
│   ├── ImageCard.tsx          # Tarjeta con botones grandes + swipe opcional
│   ├── ShareResults.tsx       # Genera el texto de resultados para compartir
│   └── ZoomableImage.tsx      # Imagen con zoom/pan táctil
├── lib/
│   ├── supabaseClient.ts
│   ├── images.ts              # Resuelve URLs de imagen (Storage o local)
│   ├── hubConfig.ts           # Carga el config.json de un hub concreto
│   ├── i18n.ts                # Diccionario de textos de interfaz por idioma
│   ├── pendingAttempts.ts     # Cola de reintento para inserts fallidos
│   ├── hubs.ts                # Carga el índice de hubs generado en build
│   ├── sampling.ts            # Aleatorizador: N imágenes del pool del hub
│   └── types.ts
├── content/
│   ├── manifest.json          # Banco global: id -> {file, is_ai_generated}
│   └── images/                # Copia local para desarrollo sin Supabase
├── locales/
│   └── {idioma}/{hub}/config.json
│       # Cada hub NO sube imágenes propias: solo elige, por id, qué
│       # subconjunto del pool usar (phase1_pool) y añade sus textos
│       # explicativos localizados (phase2). "hub"/"label"/"country"/
│       # "language" son la ÚNICA fuente de verdad sobre qué hubs
│       # existen — no hay ninguna lista hardcodeada en el código.
├── supabase/
│   └── schema.sql             # Modelo de datos completo
├── scripts/
│   ├── analyze_results.py     # Estadísticas por país/hub/edad (PEP 8)
│   ├── validate-configs.js    # Valida configs + referencias al manifest
│   ├── copy-locales-to-public.js  # Genera hubs-index.json + assets estáticos
│   ├── sync-hubs.js           # Sincroniza locales/ -> tabla "hubs"
│   ├── setup-storage.js       # Crea el bucket de imágenes (una vez)
│   ├── import-hf-images.js    # Descarga imágenes al azar de Hugging Face al banco
│   ├── normalize-images.js    # Iguala nitidez/tamaño de las fotos reales a las de IA
│   └── upload-images.js       # Sube content/images/ al bucket
├── docs/                     # Fuente HTML de los documentos imprimibles
│   ├── one-pager.html         # -> AIwareness-Global-Shapers-Valencia.pdf
│   ├── hub-onboarding-guide.html  # -> AIwareness-Hub-Onboarding-Guide.pdf
│   └── build-pdfs.sh          # Regenera los dos PDF desde su HTML
├── AIwareness-Global-Shapers-Valencia.pdf   # Generado con docs/build-pdfs.sh
├── AIwareness-Hub-Onboarding-Guide.pdf      # Generado con docs/build-pdfs.sh
└── .env.example

Cómo funciona el banco de imágenes compartido

En vez de que cada hub suba y mantenga su propio set de imágenes, hay un único banco compartido, con la verdad sobre cada imagen (¿es real o generada por IA?) centralizada en content/manifest.json:

{
  "img001": { "file": "images/img001.jpg", "is_ai_generated": true }
}

Las imágenes en sí viven en Supabase Storage (bucket público aiwareness-images), no en el repositorio — así el banco puede crecer sin inflar el clon de git y sin necesitar un redeploy para publicar contenido nuevo. lib/images.ts resuelve la ruta del manifest a la URL pública del bucket; en local, si no hay un proyecto de Supabase configurado, cae automáticamente a servir las imágenes que tengas en content/images/ como assets estáticos (modo solo-interfaz, ver más abajo).

Cada hub, en su config.json, simplemente declara qué subconjunto de ese banco es culturalmente relevante para su región y cuántas se muestran por sesión:

{
  "phase1_pool": ["img001", "img002", "img003", "..."],
  "phase1_sample_size": 10
}

En cada partida, lib/sampling.ts elige aleatoriamente phase1_sample_size imágenes de ese phase1_pool. Así, con un banco de (por ejemplo) 50 imágenes, cada usuario ve una combinación distinta de 10, y un hub puede tener un pool de 50 mientras otro usa solo 15 de esas mismas imágenes si son las que le resultan relevantes.

Cómo funciona el registro de hubs

No hay ninguna lista de hubs escrita a mano en el código. La carpeta locales/{idioma}/{hub}/config.json es la única fuente de verdad:

• En build/dev, scripts/copy-locales-to-public.js recorre todos los config.json y genera public/content/hubs-index.json. El selector de hub del onboarding (app/page.tsx) lo carga vía lib/hubs.ts.
• En CI, scripts/sync-hubs.js hace el mismo recorrido y sincroniza (upsert) la tabla hubs de Supabase, para que los insert en participants/attempts no fallen por la foreign key. Se ejecuta automáticamente al fusionar cambios en locales/** sobre main (ver .github/workflows/sync-hubs.yml) — añadir un hub nuevo no requiere ningún paso manual en Supabase ni tocar código.

1. Requisitos previos

• Cuenta de GitHub (ya la tenéis, es donde vive el repo).
• Cuenta de Supabase (gratis, plan Free es suficiente para empezar: 500MB de base de datos, 1GB de almacenamiento de archivos y 5GB de transferencia al mes).
• Cuenta de Vercel (gratis, se conecta directo al repo de GitHub).
• Node.js 18+ instalado localmente si quieres probar antes de desplegar.

This is the beginning of the README. Read the rest at the original. Read the full README ↗