diff --git a/README.md b/README.md
index 7454c37..0c90fa6 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,149 @@
-# Mercados-Web
+---
 
-API y Worker para la recolección y exposición de datos de mercados financieros.
\ No newline at end of file
+# Proyecto de Widgets de Mercados Financieros
+
+Este repositorio contiene la solución completa para la recolección, almacenamiento y visualización de datos de mercados financieros. La arquitectura está diseñada para ser robusta, escalable y fácil de mantener, separando las responsabilidades en un backend de .NET, un worker de fondo, y un frontend de React basado en widgets.
+
+---
+
+## 🚀 Arquitectura General
+
+El sistema se compone de los siguientes elementos principales:
+
+1.  **Backend (`Mercados.Api`):** Una API web de .NET 8 que expone los datos almacenados en la base de datos a través de endpoints RESTful.
+2.  **Worker Service (`Mercados.Worker`):** Un servicio de fondo de .NET 8 responsable de obtener los datos de fuentes externas (`Finnhub`, `Bolsa de Comercio de Rosario`, `Yahoo Finance` y scraping) de forma programada, procesarlos y guardarlos en la base de datos.
+3.  **Frontend (`frontend/`):** Una aplicación de React (construida con Vite + TypeScript) que proporciona un conjunto de "widgets" modulares y portátiles para visualizar los datos.
+4.  **Base de Datos (`Mercados.Database`):** Utiliza SQL Server para la persistencia de los datos. El esquema es gestionado a través de migraciones con **FluentMigrator**.
+5.  **Documentación (`docs/`):** Un portal de documentación unificado generado con **DocFX**, **TypeDoc** y **Storybook**.
+
+---
+
+## 🛠️ Configuración del Entorno de Desarrollo
+
+Para ejecutar este proyecto en un entorno local, necesitarás tener instalado:
+
+-   **.NET 9 SDK**
+-   **Node.js** (v20 o superior) y npm
+-   **SQL Server** (Developer o Express Edition)
+-   **Docker y Docker Compose** (Opcional, para simular el entorno de producción)
+-   **DocFX Command Line Tool** (Instalar con: `dotnet tool install -g docfx`)
+
+### Pasos de Configuración Inicial:
+
+1.  **Clonar el Repositorio:**
+    ```bash
+    git clone [URL_DE_TU_REPOSITORIO_GITEA]
+    cd [NOMBRE_DE_LA_CARPETA]
+    ```
+
+2.  **Configurar Secretos del Backend:**
+    Este proyecto utiliza "User Secrets" para manejar información sensible en desarrollo. Configúralos desde la raíz del repositorio:
+
+    ```bash
+    # Habilitar secretos para la API y el Worker
+    dotnet user-secrets init --project src/Mercados.Api
+    dotnet user-secrets init --project src/Mercados.Worker
+
+    # Establecer los valores (reemplaza con tus datos)
+    dotnet user-secrets set "ConnectionStrings:DefaultConnection" "Server=...;Database=..." --project src/Mercados.Api
+    dotnet user-secrets set "ApiKeys:Finnhub" "tu_api_key" --project src/Mercados.Api
+    # ...añadir el resto de las claves para ApiKeys y SmtpSettings
+    # Repite el proceso para el Worker
+    dotnet user-secrets set "ConnectionStrings:DefaultConnection" "..." --project src/Mercados.Worker
+    # ...
+    ```
+
+3.  **Instalar Dependencias del Frontend:**
+    ```bash
+    cd frontend
+    npm install
+    cd ..
+    ```
+
+4.  **Crear y Migrar la Base de Datos:**
+    Simplemente ejecuta la API una vez. La primera vez que se inicie, FluentMigrator creará la base de datos `MercadosDb` y aplicará todas las migraciones necesarias.
+    ```bash
+    dotnet run --project src/Mercados.Api
+    ```
+    Puedes detenerla con `Ctrl+C` una vez que veas el mensaje "Application started".
+
+---
+
+## 🏃 Cómo Ejecutar el Proyecto
+
+Para trabajar en el proyecto, necesitarás ejecutar los 3 servicios principales en terminales separadas.
+
+1.  **Iniciar el Backend API:**
+    ```bash
+    dotnet run --project src/Mercados.Api
+    ```
+    *La API estará disponible (por defecto) en `http://localhost:5045`.*
+
+2.  **Iniciar el Worker Service:**
+    ```bash
+    dotnet run --project src/Mercados.Worker
+    ```
+    *El worker comenzará a obtener datos según los horarios definidos en `appsettings.json`.*
+
+3.  **Iniciar el Frontend (Servidor de Desarrollo):**
+    ```bash
+    cd frontend
+    npm run dev
+    ```
+    *La aplicación de React estará disponible en `http://localhost:5173`.*
+
+---
+
+## 📚 Documentación
+
+Este proyecto incluye un portal de documentación unificado que cubre tanto el backend como el frontend.
+
+### Para Generar la Documentación:
+
+1.  **Compilar el Backend:**
+    ```bash
+    # Desde la raíz
+    dotnet build
+    ```
+2.  **Generar la documentación TypeScript:**
+    ```bash
+    # Desde la carpeta /frontend
+    npm run doc:ts
+    ```
+3.  **Construir el sitio DocFX:**
+    ```bash
+    # Desde la raíz, usando el archivo de configuración en /docs
+    docfx docs/docfx.json
+    ```
+4.  **Visualizar la documentación:**
+    ```bash
+    # Desde la raíz
+    docfx serve docs/_site
+    ```
+    *Abre tu navegador en `http://localhost:8080`.*
+
+### Para ver la Librería de Componentes Visuales (Storybook):
+
+```bash
+# Desde la carpeta /frontend
+npm run storybook
+```
+*Abre tu navegador en `http://localhost:6006`.*
+
+---
+
+## 🐳 Despliegue en Producción (Docker)
+
+El despliegue está diseñado para ser realizado con Docker y Docker Compose.
+
+1.  **Construir las imágenes de Docker:**
+    ```bash
+    # Desde la raíz del proyecto
+    docker compose build
+    ```
+2.  **Lanzar el stack de servicios:**
+    Asegúrate de tener el archivo `.env` configurado en el servidor de producción antes de ejecutar.
+    ```bash
+    docker compose up -d
+    ```
+El `docker-compose.yml` está configurado para conectarse a una red externa `shared-net` para la base de datos y para ser gestionado por un proxy inverso externo como Nginx Proxy Manager.
\ No newline at end of file