From 4eb1b42068bbf278c77d6b7524ae679be6edc3c0 Mon Sep 17 00:00:00 2001
From: Ochoa-Stack <eliaslucinoochoamalaga@gmail.com>
Date: Thu, 4 Jun 2026 07:25:50 -0600
Subject: [PATCH] docs: add internal project documentation and team guidelines

---
 CONTRIBUTING.md                    | 142 +++++++++++++++++++++++++++++
 backend/README.md                  |  29 ++++++
 backend/app/controllers/README.md  |  26 ++++++
 backend/app/models/README.md       |  22 +++++
 backend/app/repositories/README.md |  23 +++++
 backend/app/services/README.md     |  28 ++++++
 backend/clients/README.md          |  23 +++++
 data/README.md                     |  23 +++++
 docs/ARQUITECTURA.md               |  46 ++++++++++
 docs/GUIA_ENTORNO.md               | 100 ++++++++++++++++++++
 docs/GUIA_GIT.md                   | 111 ++++++++++++++++++++++
 frontend/README.md                 |  38 ++++++++
 scripts/README.md                  |  32 +++++++
 13 files changed, 643 insertions(+)
 create mode 100644 CONTRIBUTING.md
 create mode 100644 backend/README.md
 create mode 100644 backend/app/controllers/README.md
 create mode 100644 backend/app/models/README.md
 create mode 100644 backend/app/repositories/README.md
 create mode 100644 backend/app/services/README.md
 create mode 100644 backend/clients/README.md
 create mode 100644 data/README.md
 create mode 100644 docs/ARQUITECTURA.md
 create mode 100644 docs/GUIA_ENTORNO.md
 create mode 100644 docs/GUIA_GIT.md
 create mode 100644 frontend/README.md
 create mode 100644 scripts/README.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..c823edd
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,142 @@
+# ¿Cómo trabajamos en SkillStat?
+
+Este documento describe cómo organizamos el trabajo, cómo nos comunicamos
+a través del historial de cambios y cómo escribimos código. Lo leemos todos
+antes de tocar cualquier archivo del repositorio.
+
+## Ramas del repositorio
+
+Tenemos dos ramas permanentes que nunca se modifican directamente:
+
+- `main` - contiene el código que está en producción. Solo recibe cambios
+  desde `develop` a través de un Pull Request revisado y aprobado.
+- `develop` - es la rama de trabajo activo del equipo. Aquí integramos
+  todo antes de que llegue a producción.
+
+Para cualquier tarea nueva creamos una rama temporal que nace desde
+`develop` y muere cuando hacemos merge:
+
+| Tipo | Cuándo usarla | Ejemplo |
+|------|---------------|---------|
+| `feature/` | Funcionalidad nueva | `feature/jwt-authentication` |
+| `fix/` | Corrección de error en desarrollo | `fix/city-normalization` |
+| `hotfix/` | Corrección urgente en producción | `hotfix/token-exposure` |
+| `refactor/` | Reorganización sin cambiar comportamiento | `refactor/ingestion-cleanup` |
+| `chore/` | Mantenimiento, dependencias, configuración | `chore/update-requirements` |
+| `docs/` | Documentación únicamente | `docs/guia-entorno` |
+| `test/` | Pruebas nuevas o actualizadas | `test/trends-service-unit` |
+| `release/` | Preparación de versión para producción | `release/v1.0.0` |
+
+Los nombres van en minúsculas, con guiones y sin acentos.
+
+## Flujo de trabajo paso a paso
+
+Cada vez que vamos a trabajar en algo seguimos estos pasos:
+
+```bash
+# Nos aseguramos de que develop esté al día antes de empezar
+git checkout develop
+git pull origin develop
+
+# Creamos nuestra rama desde develop
+git checkout -b feature/nombre-descriptivo
+
+# Trabajamos y guardamos nuestros avances en commits
+git add .
+git commit -m "feat(scope): descripcion del cambio"
+
+# Mantenemos nuestra rama sincronizada con develop mientras trabajamos
+git fetch origin
+git rebase origin/develop
+
+# Subimos nuestra rama y abrimos el Pull Request hacia develop
+git push origin feature/nombre-descriptivo
+```
+
+Nadie toca `main` ni `develop` directamente. Todo pasa por un Pull Request.
+Nadie hace merge de su propio trabajo sin que alguien más lo haya revisado.
+Después del merge borramos la rama.
+
+## Formato de commits
+
+Cada commit sigue esta estructura:
+
+```
+tipo(alcance): descripcion breve en imperativo
+```
+
+Los tipos disponibles:
+
+| Tipo | Cuándo usarlo |
+|------|---------------|
+| `feat` | Funcionalidad nueva |
+| `fix` | Corrección de error |
+| `docs` | Cambio de documentación |
+| `style` | Formato sin cambio de lógica |
+| `refactor` | Reorganización sin cambio de comportamiento |
+| `test` | Agregar o modificar pruebas |
+| `chore` | Mantenimiento, dependencias, configuración |
+| `perf` | Mejora de rendimiento |
+
+Ejemplos reales del proyecto:
+
+```
+feat(auth): implement JWT login and token validation
+fix(nlp): resolve phrase matcher failure on multi-word skills
+chore(deps): add Flask-JWT-Extended and spaCy to requirements
+docs(contributing): add commit format and branching guide
+test(trends): add unit tests for weekly growth rate calculation
+refactor(ingestion): isolate Adzuna client from ingestion logic
+```
+
+## Cómo escribimos comentarios en el código
+
+Comentamos solo cuando el código por sí solo no deja clara la intención
+detrás de lo que hace. Si el código se entiende solo, no ponemos comentario.
+
+El comentario explica el por qué, no el qué. El qué ya lo dice el código.
+
+Escribimos en primera persona del plural, en español, sin tecnicismos,
+sin emojis y sin numerar los pasos. Aplica a todos los lenguajes del
+proyecto: Python, JavaScript, CSS e HTML.
+
+Así escribimos:
+
+```python
+# Descartamos las vacantes que ya procesamos para no duplicar los resultados.
+pending = jobs.filter(processed=False)
+
+# Guardamos el hash para detectar si la descripcion cambio en la fuente original.
+job.description_hash = compute_hash(raw_description)
+
+# Si el umbral ya se supero avisamos al usuario antes de continuar.
+if demand_count >= alert.threshold:
+    notify_user(alert)
+```
+
+```javascript
+// Esperamos el token antes de hacer la peticion para no enviar una solicitud sin autenticar.
+const token = await getAuthToken();
+
+// Mostramos el mensaje directamente para que el usuario sepa que paso sin tener que buscar.
+showErrorMessage(error.message);
+```
+
+Así no escribimos:
+
+```python
+# 1. Filtramos los jobs
+# Funcion para filtrar vacantes usando ORM
+# Filter unprocessed jobs from database
+# 🔍 Buscamos vacantes sin procesar
+```
+
+## Reglas que no se negocian
+
+- Nadie hace push directo a `main` ni a `develop`.
+- Nadie hace merge de su propio Pull Request sin revision previa.
+- Un commit representa un solo cambio logico. No mezclamos cosas distintas.
+- No dejamos deuda tecnica sin documentar. Si algo quedo incompleto
+  abrimos un issue o lo anotamos en el PR.
+- Si una rama lleva mas de una semana sin actividad, revisamos si sigue
+  siendo necesaria o la cerramos.
diff --git a/backend/README.md b/backend/README.md
new file mode 100644
index 0000000..ff5b8a6
--- /dev/null
+++ b/backend/README.md
@@ -0,0 +1,29 @@
+# backend/
+
+Aqui vive la API REST, los servicios de negocio, los modelos de datos,
+los repositorios y los clientes de APIs externas.
+
+## Estructura principal
+
+```
+backend/
+├── app/           # El nucleo de la aplicacion Flask
+├── clients/       # Clientes para APIs externas
+├── scheduler/     # Procesos automatizados periodicos
+├── migrations/    # Migraciones de base de datos
+├── tests/         # Pruebas unitarias e integracion
+└── run.py         # Punto de entrada del servidor
+```
+
+## Como arranca la aplicacion
+
+El archivo `run.py` inicia el servidor. La aplicacion se construye
+en `app/__init__.py` usando el patron application factory, que permite
+crear instancias independientes para desarrollo, produccion y pruebas.
+
+## Variables de entorno
+
+Todas las configuraciones sensibles (claves de API, URL de base de datos,
+secreto JWT) viven en el archivo `.env`. Nunca se sube al repositorio.
+El archivo `.env.example` muestra que variables se necesitan sin revelar
+sus valores reales.
diff --git a/backend/app/controllers/README.md b/backend/app/controllers/README.md
new file mode 100644
index 0000000..e579f91
--- /dev/null
+++ b/backend/app/controllers/README.md
@@ -0,0 +1,26 @@
+# controllers/
+
+Aqui viven los Blueprints de Flask. Cada archivo corresponde a un
+dominio de la aplicacion y agrupa las rutas relacionadas con ese dominio.
+
+## Lo que va aqui
+
+- Las rutas HTTP (endpoints) organizadas por Blueprint
+- La validacion del formato de la peticion entrante
+- La llamada al servicio correspondiente
+- La construccion de la respuesta que se devuelve al cliente
+
+## Lo que no va aqui
+
+La logica de negocio no vive en los controladores. Si nos encontramos
+escribiendo condiciones complejas o consultas a la base de datos dentro
+de un Blueprint, eso pertenece a un servicio o un repositorio.
+
+## Los Blueprints del proyecto
+
+| Archivo | Dominio |
+|---------|---------|
+| `auth_bp.py` | Registro, login y gestion de sesion |
+| `panorama_bp.py` | Tendencias, rankings y datos del dashboard |
+| `alerts_bp.py` | Configuracion y gestion de alertas del usuario |
+| `admin_bp.py` | Administracion de usuarios y respaldos |
diff --git a/backend/app/models/README.md b/backend/app/models/README.md
new file mode 100644
index 0000000..7625c05
--- /dev/null
+++ b/backend/app/models/README.md
@@ -0,0 +1,22 @@
+# models/
+
+Aqui definimos la estructura de los datos del sistema usando SQLAlchemy.
+Cada archivo representa una tabla de la base de datos.
+
+## Lo que va aqui
+
+- La definicion de columnas, tipos de dato y restricciones
+- Las relaciones entre tablas (claves foraneas, backrefs)
+- Las restricciones de integridad (UNIQUE, CHECK, NOT NULL)
+
+## Lo que no va aqui
+
+La logica de negocio no vive en los modelos. Los modelos describen
+la forma de los datos, no lo que hacemos con ellos.
+
+## Las entidades del proyecto
+
+`category`, `city`, `skill`, `job`, `job_skill`, `user`, `alert`,
+`trend_snapshot`, `backup`.
+
+El diagrama entidad-relacion completo esta en `docs/diagramas/er.png`.
diff --git a/backend/app/repositories/README.md b/backend/app/repositories/README.md
new file mode 100644
index 0000000..6ccddd5
--- /dev/null
+++ b/backend/app/repositories/README.md
@@ -0,0 +1,23 @@
+# repositories/
+
+Aqui vive toda la logica de acceso a la base de datos. Los repositorios
+son el unico lugar del sistema donde hablamos directamente con PostgreSQL
+a traves del ORM.
+
+## Lo que va aqui
+
+- Las consultas a la base de datos (lecturas, escrituras, filtros)
+- La logica de paginacion y ordenamiento
+- Las operaciones CRUD de cada entidad
+
+## Lo que no va aqui
+
+La logica de negocio no vive aqui. Si necesitamos hacer algo con los
+datos despues de leerlos, ese trabajo pertenece al servicio que llamo
+al repositorio.
+
+## Como funciona
+
+`base_repository.py` contiene las operaciones comunes (guardar, buscar
+por ID, listar, eliminar). Cada repositorio especifico extiende esa base
+y agrega las consultas particulares que su entidad necesita.
diff --git a/backend/app/services/README.md b/backend/app/services/README.md
new file mode 100644
index 0000000..9de1d64
--- /dev/null
+++ b/backend/app/services/README.md
@@ -0,0 +1,28 @@
+# services/
+
+Aqui vive la logica de negocio del sistema. Los servicios son el
+corazon de SkillStat: procesan datos, toman decisiones y coordinan
+el trabajo entre los distintos componentes.
+
+## Lo que va aqui
+
+- La logica que extrae habilidades de descripciones de vacantes
+- La logica que calcula tendencias y metricas del mercado
+- La logica que evalua alertas y decide cuando notificar
+- La coordinacion entre repositorios y clientes externos
+
+## Lo que no va aqui
+
+Los servicios no conocen Flask. No manejan peticiones HTTP ni
+construyen respuestas JSON. Tampoco acceden directamente a la base
+de datos: para eso usan los repositorios.
+
+## Los servicios del proyecto
+
+| Archivo | Que hace |
+|---------|----------|
+| `ingestion_service.py` | Recopila vacantes desde la API de Adzuna |
+| `skills_extraction_service.py` | Extrae habilidades tecnicas de descripciones |
+| `market_trends_service.py` | Calcula metricas de demanda y tendencias |
+| `alerts_service.py` | Evalua alertas y coordina las notificaciones |
+| `backup_service.py` | Genera y restaura respaldos de la base de datos |
diff --git a/backend/clients/README.md b/backend/clients/README.md
new file mode 100644
index 0000000..02b3205
--- /dev/null
+++ b/backend/clients/README.md
@@ -0,0 +1,23 @@
+# clients/
+
+Aqui viven los clientes que se comunican con APIs externas. Cada archivo
+envuelve una sola API y expone metodos claros para que los servicios
+puedan usarla sin conocer los detalles de la comunicacion HTTP.
+
+## Lo que va aqui
+
+- La logica de autenticacion con cada API externa
+- El manejo de errores y reintentos de conexion
+- La transformacion de la respuesta al formato que el sistema necesita
+
+## Los clientes del proyecto
+
+| Archivo | API que envuelve |
+|---------|-----------------|
+| `adzuna_client.py` | Adzuna Jobs API - fuente de vacantes |
+| `nominatim_client.py` | Nominatim / OpenStreetMap - geocodificacion |
+| `sendgrid_client.py` | SendGrid - envio de correos de alerta |
+| `base_client.py` | Logica compartida: reintentos, timeouts, headers |
+
+Los servicios nunca llaman directamente a `requests` o `httpx`.
+Siempre usan estos clientes.
diff --git a/data/README.md b/data/README.md
new file mode 100644
index 0000000..33bfc34
--- /dev/null
+++ b/data/README.md
@@ -0,0 +1,23 @@
+# data/
+
+Aqui viven los activos de datos que usa el modulo de procesamiento
+de lenguaje natural. No es codigo de la aplicacion: son los archivos
+que alimentan al extractor de habilidades.
+
+## Lo que hay aqui
+
+- `dictionaries/skills_esco.jsonl` - habilidades tecnicas de la
+  taxonomia ESCO (base de datos oficial de la Union Europea). Se
+  descarga y procesa con el script `scripts/build_dictionary.py`.
+- `dictionaries/skills_custom.jsonl` - habilidades que el equipo
+  agrega manualmente cuando la taxonomia base no las incluye.
+- `dictionaries/skill_aliases.json` - mapeo de abreviaciones y
+  variantes al nombre canonico. Por ejemplo: `"JS": "JavaScript"`.
+- `samples/vacantes_sample.json` - vacantes de prueba para
+  desarrollar y probar el extractor sin consumir la API real.
+
+## Como agregar una habilidad nueva
+
+Si encontramos una habilidad que el sistema no detecta, la agregamos
+en `skills_custom.jsonl` siguiendo el mismo formato que el resto
+del archivo. Si es una abreviacion, la agregamos en `skill_aliases.json`.
diff --git a/docs/ARQUITECTURA.md b/docs/ARQUITECTURA.md
new file mode 100644
index 0000000..bcb4340
--- /dev/null
+++ b/docs/ARQUITECTURA.md
@@ -0,0 +1,46 @@
+# Arquitectura de SkillStat
+
+SkillStat es una plataforma de inteligencia de mercado laboral que
+recopila vacantes tecnologicas, extrae habilidades con procesamiento
+de lenguaje natural y presenta los resultados en un dashboard analitico
+llamado Panorama.
+
+## Como esta organizado el repositorio
+
+```
+SkillStat/
+├── frontend/     # Interfaz web: vistas, estilos y logica del cliente
+├── backend/      # API REST, servicios, modelos y acceso a datos
+├── data/         # Activos de datos para el procesamiento NLP
+├── scripts/      # Herramientas de uso manual para el equipo
+└── docs/         # Documentacion interna del proyecto
+```
+
+## Las capas del backend
+
+El backend sigue una arquitectura en capas donde cada capa tiene una
+responsabilidad clara y no invade la del resto:
+
+| Capa | Donde vive | Que hace |
+|------|-----------|----------|
+| Controladores | `backend/app/controllers/` | Recibe peticiones HTTP y devuelve respuestas |
+| Servicios | `backend/app/services/` | Contiene la logica de negocio del sistema |
+| Repositorios | `backend/app/repositories/` | Habla con la base de datos |
+| Modelos | `backend/app/models/` | Define la estructura de los datos |
+| Clientes | `backend/clients/` | Se comunica con APIs externas |
+
+Los controladores llaman a los servicios. Los servicios llaman a los
+repositorios. Los repositorios hablan con la base de datos. Los clientes
+son usados por los servicios para comunicarse con el exterior.
+
+## Donde encontrar cada cosa
+
+- Las rutas de la API viven en `backend/app/controllers/`
+- La logica que procesa vacantes y extrae habilidades vive en `backend/app/services/`
+- Las tablas de la base de datos estan definidas en `backend/app/models/`
+- Las consultas a la base de datos viven en `backend/app/repositories/`
+- Las conexiones con Adzuna, Nominatim y SendGrid viven en `backend/clients/`
+- Las vistas HTML del Panorama y el resto de pantallas viven en `frontend/views/`
+- Los archivos de estilos estan en `frontend/assets/css/`
+- La logica del cliente esta en `frontend/assets/js/`
+- El diccionario de habilidades tecnologicas vive en `data/dictionaries/`
diff --git a/docs/GUIA_ENTORNO.md b/docs/GUIA_ENTORNO.md
new file mode 100644
index 0000000..1c4c973
--- /dev/null
+++ b/docs/GUIA_ENTORNO.md
@@ -0,0 +1,100 @@
+# Configuracion del entorno local
+
+Esta guia explica como preparar la maquina para trabajar en SkillStat
+desde cero. La seguimos la primera vez que clonamos el repositorio y
+cada vez que alguien nuevo se integra al equipo.
+
+## Lo que necesitamos tener instalado
+
+- **Python 3.13.x** - lo descargamos desde https://www.python.org/downloads/
+  Verificamos la instalacion con: `python --version`
+- **Git** - lo descargamos desde https://git-scm.com/
+  Verificamos con: `git --version`
+- Un editor de codigo. Recomendamos Visual Studio Code.
+
+## Pasos para configurar el proyecto
+
+**1. Clonamos el repositorio**
+
+```bash
+git clone https://github.com/Ochoa-Stack/SkillStat.git
+cd SkillStat
+```
+
+**2. Entramos a la carpeta del backend y creamos el entorno virtual**
+
+El entorno virtual aísla las dependencias del proyecto para que no
+interfieran con otros proyectos en la misma maquina.
+
+```bash
+cd backend
+
+# En Mac y Linux
+python3 -m venv .venv
+
+# En Windows
+python -m venv .venv
+```
+
+**3. Activamos el entorno virtual**
+
+Esto lo hacemos cada vez que abrimos una nueva terminal para trabajar.
+
+```bash
+# En Mac y Linux
+source .venv/bin/activate
+
+# En Windows (PowerShell)
+.venv\Scripts\Activate.ps1
+
+# En Windows (CMD)
+.venv\Scripts\activate.bat
+```
+
+Cuando el entorno esta activo vemos `(.venv)` al inicio de la linea
+en la terminal.
+
+**4. Instalamos las dependencias**
+
+```bash
+pip install -r requirements.txt
+pip install -r requirements-dev.txt
+```
+
+> El archivo requirements.txt se completara en los proximos pasos del
+> desarrollo. Si aun esta vacio este paso se puede omitir por ahora.
+
+**5. Configuramos las variables de entorno**
+
+Copiamos el archivo de ejemplo y lo llenamos con los valores reales:
+
+```bash
+# En Mac y Linux
+cp .env.example .env
+
+# En Windows
+copy .env.example .env
+```
+
+Abrimos `.env` y completamos cada variable con los valores que se
+nos proporcionen. Nunca subimos el archivo `.env` al repositorio.
+
+**6. Corremos el servidor de desarrollo**
+
+```bash
+python run.py
+```
+
+Si todo esta bien veremos un mensaje indicando que Flask esta corriendo,
+generalmente en http://localhost:5000
+
+## Cuando algo no funciona
+
+- Si `python` no se reconoce como comando, probamos con `python3`.
+- Si el entorno virtual no se activa en Windows, es posible que
+  necesitemos ejecutar primero:
+  `Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser`
+- Si hay errores al instalar dependencias, verificamos que el entorno
+  virtual este activado antes de correr `pip install`.
+- Para cualquier otro problema lo comentamos en el canal del equipo
+  antes de intentar soluciones por cuenta propia.
diff --git a/docs/GUIA_GIT.md b/docs/GUIA_GIT.md
new file mode 100644
index 0000000..3211378
--- /dev/null
+++ b/docs/GUIA_GIT.md
@@ -0,0 +1,111 @@
+# Git en el dia a dia
+
+Esta guia cubre los comandos de Git que usamos en SkillStat. No asume
+conocimiento previo. Si ya dominas Git puedes usarla como referencia rapida.
+
+## Como funciona Git en este proyecto
+
+Git guarda el historial de todos los cambios que hacemos al codigo.
+Cada vez que guardamos un cambio con `commit` quedamos un registro de
+que cambio, quien lo hizo y cuando.
+
+Las ramas nos permiten trabajar en algo nuevo sin afectar lo que ya
+funciona. Cuando terminamos, integramos nuestro trabajo a `develop`
+a traves de un Pull Request en GitHub.
+
+## Los comandos que mas usamos
+
+**Ver en que rama estamos y que archivos cambiamos:**
+```bash
+git status
+```
+
+**Ver el historial de commits:**
+```bash
+git log --oneline
+```
+
+**Traer los cambios mas recientes del repositorio remoto:**
+```bash
+git pull origin develop
+```
+
+**Crear una rama nueva desde develop:**
+```bash
+git checkout develop
+git pull origin develop
+git checkout -b feature/nombre-de-la-tarea
+```
+
+**Guardar nuestros cambios en un commit:**
+```bash
+git add .
+git commit -m "feat(scope): descripcion del cambio"
+```
+
+**Subir nuestra rama al repositorio remoto:**
+```bash
+git push origin feature/nombre-de-la-tarea
+```
+
+**Actualizar nuestra rama con los ultimos cambios de develop:**
+```bash
+git fetch origin
+git rebase origin/develop
+```
+
+**Cambiar de rama:**
+```bash
+git checkout nombre-de-la-rama
+```
+
+**Ver todas las ramas disponibles:**
+```bash
+git branch -a
+```
+
+## El flujo completo de una tarea
+
+```bash
+# Empezamos siempre desde develop actualizado
+git checkout develop
+git pull origin develop
+
+# Creamos nuestra rama
+git checkout -b feature/mi-tarea
+
+# Trabajamos... hacemos cambios... y guardamos
+git add .
+git commit -m "feat(modulo): descripcion"
+
+# Si develop recibio nuevos cambios mientras trabajabamos
+git fetch origin
+git rebase origin/develop
+
+# Subimos nuestra rama
+git push origin feature/mi-tarea
+
+# Desde GitHub abrimos el Pull Request hacia develop
+```
+
+## Lo que no hacemos
+
+- No hacemos commits directamente sobre `develop` o `main`.
+- No usamos `git push --force` en ramas compartidas.
+- No hacemos merge de nuestro propio Pull Request.
+- No subimos el archivo `.env` ni ninguna credencial al repositorio.
+
+## Cuando algo sale mal
+
+Si nos equivocamos en el mensaje de un commit antes de subir los cambios:
+```bash
+git commit --amend -m "feat(scope): mensaje corregido"
+```
+
+Si queremos deshacer el ultimo commit pero conservar los cambios:
+```bash
+git reset --soft HEAD~1
+```
+
+Si tenemos dudas sobre algo que no esta en esta guia lo preguntamos
+antes de intentar comandos desconocidos.
diff --git a/frontend/README.md b/frontend/README.md
new file mode 100644
index 0000000..ef98d8c
--- /dev/null
+++ b/frontend/README.md
@@ -0,0 +1,38 @@
+# frontend/
+
+Aqui vive todo lo que el usuario ve y con lo que interactua: las vistas
+HTML, los estilos CSS y la logica JavaScript del cliente.
+
+## Estructura
+
+```
+frontend/
+├── assets/
+│   ├── css/      Estilos organizados por funcion
+│   ├── js/       Logica del cliente organizada por responsabilidad
+│   └── images/   Iconos y recursos graficos
+└── views/        Un archivo HTML por cada pantalla de la aplicacion
+```
+
+## Como organizamos los estilos
+
+- `css/base/` - variables globales, reset y tipografia. Lo que aplica a toda la app.
+- `css/components/` - estilos de piezas reutilizables: botones, tarjetas, graficas.
+- `css/layouts/` - rejillas y contenedores estructurales.
+- `css/pages/` - estilos especificos de cada pantalla.
+- `css/main.css` - punto de entrada que importa todo lo anterior.
+
+## Como organizamos el JavaScript
+
+- `js/api/` - funciones que se comunican con la API del backend. Una por dominio.
+- `js/components/` - inicializacion de componentes visuales como Chart.js o el mapa.
+- `js/pages/` - logica especifica de cada pantalla.
+- `js/utils/` - funciones compartidas: formateo de numeros, validacion, manejo del token.
+
+## Las vistas
+
+Cada pantalla tiene su propio archivo HTML en `views/`. El archivo
+`views/panorama.html` es el dashboard principal del sistema.
+
+No ponemos logica de backend aqui. No accedemos a la base de datos
+desde el frontend. Todo pasa por la API REST del backend.
diff --git a/scripts/README.md b/scripts/README.md
new file mode 100644
index 0000000..f677df6
--- /dev/null
+++ b/scripts/README.md
@@ -0,0 +1,32 @@
+# scripts/
+
+Aqui viven herramientas de uso manual para tareas de mantenimiento
+y configuracion del proyecto. Estos scripts no forman parte de la
+aplicacion y no se ejecutan automaticamente.
+
+## Los scripts disponibles
+
+**`seed_db.py`** - Carga los datos iniciales en la base de datos:
+categorias de habilidades, ciudades base y el catalogo de habilidades
+del diccionario ESCO. Se corre una sola vez al configurar un ambiente
+nuevo.
+
+**`build_dictionary.py`** - Descarga y procesa la taxonomia ESCO para
+generar el archivo `data/dictionaries/skills_esco.jsonl`. Se corre
+cuando actualizamos la version del diccionario.
+
+**`backup_manual.py`** - Genera un respaldo de la base de datos de
+forma manual sin pasar por la interfaz de administracion. Util para
+respaldos puntuales antes de cambios importantes.
+
+## Como correr un script
+
+```bash
+# Nos aseguramos de estar en la carpeta backend con el entorno activo
+cd backend
+source .venv/bin/activate   # Mac / Linux
+.venv\Scripts\activate      # Windows
+
+# Corremos el script desde la raiz del repositorio
+python scripts/nombre_del_script.py
+```